Skip to content

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

docs: reorganize API reference and complete response contracts (#3507)

yufengf4ade62410ed
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index d137900c8..f6309d90c 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -174,27 +174,57 @@ const apiReferenceSidebar = {
overview: 'Overview',
groups: [
{
- text: 'Core Capabilities',
+ text: 'Core Data',
items: [
['02-resources.md', 'Resources'],
+ ['12-content.md', 'Content'],
['03-filesystem.md', 'File System'],
['04-skills.md', 'Skills'],
- ['05-sessions.md', 'Sessions & Memory'],
- ['06-retrieval.md', 'Retrieval']
+ ['05-sessions.md', 'Sessions'],
+ ['16-memory.md', 'Memory']
]
},
{
- text: 'Operations & Governance',
+ text: 'Retrieval & Relations',
+ items: [
+ ['06-retrieval.md', 'Retrieval'],
+ ['13-relations.md', 'Relations'],
+ ['21-code.md', 'Code Navigation']
+ ]
+ },
+ {
+ text: 'Data Lifecycle',
+ items: [
+ ['15-watches.md', 'Resource Watches'],
+ ['11-snapshot.md', 'Snapshots'],
+ ['14-ovpack.md', 'OVPack']
+ ]
+ },
+ {
+ text: 'Operations & Observability',
+ items: [
+ ['07-system.md', 'System Status'],
+ ['17-tasks.md', 'Background Tasks'],
+ ['18-observer.md', 'Runtime Observability'],
+ ['09-metrics.md', 'Metrics']
+ ]
+ },
+ {
+ text: 'Identity & Governance',
items: [
- ['07-system.md', 'System'],
['08-admin.md', 'Multi-Tenancy'],
- ['09-metrics.md', 'Metrics'],
- ['10-privacy.md', 'Privacy'],
- ['11-snapshot.md', 'Snapshots']
+ ['10-privacy.md', 'Privacy']
+ ]
+ },
+ {
+ text: 'Protocols & Extensions',
+ items: [
+ ['20-webdav.md', 'WebDAV'],
+ ['24-vikingbot.md', 'VikingBot API']
]
},
{
- text: 'Contributing',
+ text: 'Documentation Maintenance',
items: [['99-api-doc-writing-guide.md', 'API Docs Guide']]
}
]
@@ -203,27 +233,57 @@ const apiReferenceSidebar = {
overview: '概览',
groups: [
{
- text: '核心能力',
+ text: '核心数据',
items: [
['02-resources.md', '资源'],
+ ['12-content.md', '内容'],
['03-filesystem.md', '文件系统'],
['04-skills.md', '技能'],
- ['05-sessions.md', '会话与记忆'],
- ['06-retrieval.md', '检索']
+ ['05-sessions.md', '会话'],
+ ['16-memory.md', '记忆']
]
},
{
- text: '运维与治理',
+ text: '检索与关系',
+ items: [
+ ['06-retrieval.md', '检索'],
+ ['13-relations.md', '关系'],
+ ['21-code.md', '代码导航']
+ ]
+ },
+ {
+ text: '数据生命周期',
+ items: [
+ ['15-watches.md', '资源 Watch'],
+ ['11-snapshot.md', '快照'],
+ ['14-ovpack.md', 'OVPack']
+ ]
+ },
+ {
+ text: '运维与观测',
+ items: [
+ ['07-system.md', '系统状态'],
+ ['17-tasks.md', '后台任务'],
+ ['18-observer.md', '运行观测'],
+ ['09-metrics.md', '监控指标']
+ ]
+ },
+ {
+ text: '身份与治理',
items: [
- ['07-system.md', '系统管理'],
['08-admin.md', '多租户'],
- ['09-metrics.md', '监控指标'],
- ['10-privacy.md', '隐私配置'],
- ['11-snapshot.md', '快照管理']
+ ['10-privacy.md', '隐私配置']
+ ]
+ },
+ {
+ text: '协议与扩展',
+ items: [
+ ['20-webdav.md', 'WebDAV'],
+ ['24-vikingbot.md', 'VikingBot API']
]
},
{
- text: '文档贡献',
+ text: '文档维护',
items: [['99-api-doc-writing-guide.md', 'API 文档规范']]
}
]
diff --git a/docs/en/api/01-overview.md b/docs/en/api/01-overview.md
index a2f230b87..f3decfc75 100644
--- a/docs/en/api/01-overview.md
+++ b/docs/en/api/01-overview.md
@@ -396,221 +396,185 @@ JSON output - error:
## API Endpoints
-Below are all HTTP API endpoints provided by OpenViking, grouped by functional module:
+This catalog follows the routes actually mounted by the server. Each group heading links to its detailed reference. Detail pages show an HTTP, Python SDK, TypeScript SDK, Go SDK, or CLI tab only when that surface is genuinely available; a raw HTTP workaround is not presented as an SDK.
-### System
-
-| Method | Path | Description | Authentication |
-|--------|------|-------------|----------------|
-| GET | `/health` | Health check (no auth) | No auth required |
-| GET | `/ready` | Readiness probe (no auth) | No auth required |
-| GET | `/metrics` | Prometheus metrics export | Optional |
-| GET | `/api/v1/system/status` | System status | Required |
-| POST | `/api/v1/system/wait` | Wait for processing | Required |
-| POST | `/api/v1/system/consistency` | Filesystem/vector-index consistency check | Required |
-
-### Resources
-
-| Method | Path | Description |
-|--------|------|-------------|
-| POST | `/api/v1/resources/temp_upload` | Upload local file for raw HTTP resource / pack import |
-| POST | `/api/v1/resources` | Add resource (supports URL or temp_file_id) |
-
-### Skills
-
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/api/v1/skills` | List installed skills |
-| POST | `/api/v1/skills` | Add skill |
-| POST | `/api/v1/skills/find` | Search installed skills |
-| POST | `/api/v1/skills/validate` | Validate skill payload |
-| GET | `/api/v1/skills/{skill_name}` | Get skill |
-| PUT | `/api/v1/skills/{skill_name}` | Update skill |
-| DELETE | `/api/v1/skills/{skill_name}` | Delete skill |
-
-### Watches
+### [System Status](07-system.md)
| Method | Path | Description |
|--------|------|-------------|
-| GET | `/api/v1/watches` | List watches or get one by `to_uri` |
-| GET | `/api/v1/watches/{task_id}` | Get watch |
-| PATCH | `/api/v1/watches` | Update watch by `to_uri` |
-| PATCH | `/api/v1/watches/{task_id}` | Update watch by task ID |
-| DELETE | `/api/v1/watches` | Delete watch by `to_uri` |
-| DELETE | `/api/v1/watches/{task_id}` | Delete watch by task ID |
-| POST | `/api/v1/watches/trigger` | Trigger watch by `to_uri` |
-| POST | `/api/v1/watches/{task_id}/trigger` | Trigger watch by task ID |
-
-### Pack
-
-| Method | Path | Description | Permission |
-|--------|------|-------------|------------|
-| POST | `/api/v1/pack/export` | Export .ovpack | ROOT/ADMIN/USER, subject to normal URI ACL |
-| POST | `/api/v1/pack/import` | Import .ovpack | ROOT/ADMIN/USER, subject to normal URI ACL |
-| POST | `/api/v1/pack/backup` | Back up public scopes | ROOT/ADMIN |
-| POST | `/api/v1/pack/restore` | Restore backup package | ROOT/ADMIN |
-
-### File System
+| GET | `/health` | Basic health check (no authentication) |
+| GET | `/ready` | AGFS, VectorDB, and API key manager 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 |
+| POST | `/api/v1/system/backend/sync-status` | Query backend synchronization status |
+| POST | `/api/v1/system/backend/sync-retry` | Retry backend synchronization |
+| GET | `/api/v1/system/sync/{sync_path}` | Path-form compatibility endpoint for synchronization status |
+| POST | `/api/v1/system/sync/{sync_path}/retry` | Path-form compatibility endpoint for synchronization retry |
+
+### [Resources](02-resources.md) and [Filesystem](03-filesystem.md)
| Method | Path | Description |
|--------|------|-------------|
-| GET | `/api/v1/fs/ls` | List directory |
-| GET | `/api/v1/fs/tree` | Directory tree |
-| GET | `/api/v1/fs/stat` | Resource status |
-| GET | `/api/v1/fs/attrs` | Logical extended attributes |
-| POST | `/api/v1/fs/attrs/set_tags` | Set retrieval tags |
-| POST | `/api/v1/fs/mkdir` | Create directory |
-| DELETE | `/api/v1/fs` | Delete resource |
-| POST | `/api/v1/fs/mv` | Move/rename resource |
-
-### Snapshots (Multi-Version Management)
-
-| Method | Path | Description |
-|--------|------|-------------|
-| POST | `/api/v1/snapshot/commit` | Save the current workspace state as a new snapshot |
-| GET | `/api/v1/snapshot/log` | Walk commit history newest-first |
-| GET | `/api/v1/snapshot/show` | View commit metadata, or read a file from a commit |
-| GET | `/api/v1/snapshot/diff` | Compare one file between two snapshots |
-| POST | `/api/v1/snapshot/restore` | Restore a directory or the whole account tree to a past snapshot (forward commit) |
-
-### Content
+| POST | `/api/v1/resources/temp_upload` | Upload a temporary file for a later import |
+| POST | `/api/v1/resources` | Add a resource from a URL or temporary upload |
+| GET | `/api/v1/fs/ls` | List a directory |
+| GET | `/api/v1/fs/tree` | Get a directory tree |
+| GET | `/api/v1/fs/stat` | Get resource status |
+| GET | `/api/v1/fs/attrs` | Get logical extended attributes |
+| POST | `/api/v1/fs/attrs/set_tags` | Set retrieval tags (compatibility alias) |
+| POST | `/api/v1/fs/mkdir` | Create a directory |
+| DELETE | `/api/v1/fs` | Delete a resource |
+| POST | `/api/v1/fs/mv` | Move or rename a resource |
+
+### [Content](12-content.md)
| Method | Path | Description |
|--------|------|-------------|
| 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 |
+| GET | `/api/v1/content/abstract` | Read an abstract (L0) |
+| 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/set_tags` | Set retrieval tags |
+| POST | `/api/v1/content/reindex` | Rebuild semantic or vector indexes |
-### Search
+### [Skills](04-skills.md)
| Method | Path | Description |
|--------|------|-------------|
-| POST | `/api/v1/search/find` | Semantic search (no session context) |
-| POST | `/api/v1/search/search` | Context-aware search (supports sessions) |
-| POST | `/api/v1/search/grep` | Content pattern search |
-| POST | `/api/v1/search/glob` | File pattern matching |
+| GET | `/api/v1/skills` | List skills |
+| POST | `/api/v1/skills` | Add a skill |
+| POST | `/api/v1/skills/find` | Search skills |
+| POST | `/api/v1/skills/validate` | Validate skill data |
+| GET | `/api/v1/skills/{skill_name}` | Get a skill |
+| PUT | `/api/v1/skills/{skill_name}` | Update a skill |
+| DELETE | `/api/v1/skills/{skill_name}` | Delete a skill |
-### Relations (Experimental, may change in future versions)
+### [Sessions](05-sessions.md) and [Memory](16-memory.md)
| Method | Path | Description |
|--------|------|-------------|
-| GET | `/api/v1/relations` | Get relations |
-| POST | `/api/v1/relations/link` | Create link |
-| DELETE | `/api/v1/relations/link` | Remove link |
-
-### Sessions
-
-| Method | Path | Description |
-|--------|------|-------------|
-| POST | `/api/v1/sessions` | Create session |
+| POST | `/api/v1/sessions` | Create a session |
| GET | `/api/v1/sessions` | List sessions |
-| GET | `/api/v1/sessions/{session_id}` | Get session |
-| GET | `/api/v1/sessions/{session_id}/context` | Get assembled session context |
-| GET | `/api/v1/sessions/{session_id}/archives/{archive_id}` | Get a specific session archive |
-| DELETE | `/api/v1/sessions/{session_id}` | Delete session |
-| POST | `/api/v1/sessions/{session_id}/commit` | Commit session (archive and extract memories) |
-| POST | `/api/v1/sessions/{session_id}/extract` | Extract memories from a session |
-| POST | `/api/v1/sessions/{session_id}/messages` | Add message |
-| POST | `/api/v1/sessions/{session_id}/used` | Record contexts / skills actually used |
-
-### Privacy Configs
+| GET | `/api/v1/sessions/{session_id}` | Get a session |
+| GET | `/api/v1/sessions/{session_id}/tool-results` | List tool results |
+| GET | `/api/v1/sessions/{session_id}/tool-results/{tool_result_id}` | Read a tool result |
+| GET | `/api/v1/sessions/{session_id}/tool-results/{tool_result_id}/search` | Search within a tool result |
+| GET | `/api/v1/sessions/{session_id}/context` | Get assembled context |
+| GET | `/api/v1/sessions/{session_id}/archives/{archive_id}` | Get a session archive |
+| DELETE | `/api/v1/sessions/{session_id}` | Delete a session |
+| POST | `/api/v1/sessions/{session_id}/commit` | Archive a session and extract memory |
+| POST | `/api/v1/sessions/{session_id}/extract` | Extract memory |
+| POST | `/api/v1/sessions/{session_id}/messages` | Add one message |
+| POST | `/api/v1/sessions/{session_id}/messages/batch` | Add messages in a batch |
+| POST | `/api/v1/sessions/{session_id}/used` | Record context or skills actually used |
+| POST | `/api/v1/search/recall` | Recall memory as injection-ready context |
+
+### [Retrieval](06-retrieval.md), [Code Retrieval](21-code.md), and [Relations](13-relations.md)
| Method | Path | Description |
|--------|------|-------------|
-| GET | `/api/v1/privacy-configs` | List privacy config categories |
-| GET | `/api/v1/privacy-configs/{category}` | List targets under a category |
-| GET | `/api/v1/privacy-configs/{category}/{target_key}` | Get active config (`meta + current`) |
-| POST | `/api/v1/privacy-configs/{category}/{target_key}` | Upsert and activate |
-| GET | `/api/v1/privacy-configs/{category}/{target_key}/versions` | List version numbers |
-| GET | `/api/v1/privacy-configs/{category}/{target_key}/versions/{version}` | Get version snapshot |
-| POST | `/api/v1/privacy-configs/{category}/{target_key}/activate` | Activate a version |
+| POST | `/api/v1/search/find` | Semantic search |
+| POST | `/api/v1/search/search` | Context-aware search |
+| POST | `/api/v1/search/grep` | Content pattern search |
+| POST | `/api/v1/search/glob` | File pattern matching |
+| POST | `/api/v1/code/outline` | Extract code structure |
+| POST | `/api/v1/code/search` | Search code |
+| POST | `/api/v1/code/expand` | Expand code context |
+| GET | `/api/v1/relations` | Get resource relations |
+| POST | `/api/v1/relations/link` | Create a resource link |
+| DELETE | `/api/v1/relations/link` | Delete a resource link |
+| POST | `/api/v1/relations/build_graph` | Build a relation graph |
-### Tasks
+### [Watches](15-watches.md), [Snapshots](11-snapshot.md), and [OVPack](14-ovpack.md)
| Method | Path | Description |
|--------|------|-------------|
-| GET | `/api/v1/tasks/{task_id}` | Get background task status |
-| GET | `/api/v1/tasks` | List background tasks (supports filtering by type, status, resource) |
-
-### Observer
+| GET | `/api/v1/watches` | List watches or query by `to_uri` |
+| GET | `/api/v1/watches/{task_id}` | Get a watch by task ID |
+| PATCH | `/api/v1/watches` | Update a watch by `to_uri` |
+| PATCH | `/api/v1/watches/{task_id}` | Update a watch by task ID |
+| DELETE | `/api/v1/watches` | Delete a watch by `to_uri` |
+| DELETE | `/api/v1/watches/{task_id}` | Delete a watch by task ID |
+| POST | `/api/v1/watches/trigger` | Trigger a watch by `to_uri` |
+| POST | `/api/v1/watches/{task_id}/trigger` | Trigger a watch by task ID |
+| POST | `/api/v1/snapshot/commit` | Create a snapshot |
+| GET | `/api/v1/snapshot/log` | Read snapshot history |
+| POST | `/api/v1/snapshot/restore` | Restore a historical snapshot |
+| GET | `/api/v1/snapshot/show` | Inspect a snapshot or one of its files |
+| GET | `/api/v1/snapshot/diff` | Compare snapshots |
+| GET | `/api/v1/snapshot/ignore` | Read snapshot ignore rules |
+| PUT | `/api/v1/snapshot/ignore` | Replace snapshot ignore rules |
+| DELETE | `/api/v1/snapshot/ignore` | Clear snapshot ignore rules |
+| POST | `/api/v1/pack/export` | Export an `.ovpack` |
+| POST | `/api/v1/pack/import` | Import an `.ovpack` |
+| POST | `/api/v1/pack/backup` | Back up public scopes |
+| POST | `/api/v1/pack/restore` | Restore a backup package |
+
+### [Background Tasks](17-tasks.md), [Runtime Observer](18-observer.md), and [Metrics](09-metrics.md)
| Method | Path | Description |
|--------|------|-------------|
+| GET | `/api/v1/tasks/{task_id}` | Get a background task |
+| GET | `/api/v1/tasks` | List background tasks |
| GET | `/api/v1/observer/queue` | Queue status |
| GET | `/api/v1/observer/vikingdb` | VikingDB 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 |
+| GET | `/api/v1/observer/models` | Model status |
+| GET | `/api/v1/observer/lock` | Lock status |
+| GET | `/api/v1/observer/retrieval` | Retrieval status |
+| GET | `/api/v1/observer/filesystem` | Filesystem status |
+| GET | `/api/v1/observer/system` | Aggregate runtime status |
+| GET | `/metrics` | Prometheus metrics |
-### Statistics
+### [Administration](08-admin.md) and [Privacy Configuration](10-privacy.md)
| Method | Path | Description |
|--------|------|-------------|
-| GET | `/api/v1/stats/memories` | Get memory health statistics (supports category filtering) |
-| GET | `/api/v1/stats/sessions/{session_id}` | Get session extraction statistics |
-
-### Admin (Multi-tenant)
-
-| Method | Path | Description | Permission |
-|--------|------|-------------|------------|
-| POST | `/api/v1/admin/accounts` | Create workspace + first admin | ROOT |
-| GET | `/api/v1/admin/accounts` | List workspaces | ROOT |
-| DELETE | `/api/v1/admin/accounts/{account_id}` | Delete workspace (cascade data cleanup) | ROOT |
-| POST | `/api/v1/admin/accounts/{account_id}/users` | Register user | ROOT/ADMIN |
-| GET | `/api/v1/admin/accounts/{account_id}/users` | List users | ROOT/ADMIN |
-| DELETE | `/api/v1/admin/accounts/{account_id}/users/{user_id}` | Remove user | ROOT/ADMIN |
-| PUT | `/api/v1/admin/accounts/{account_id}/users/{user_id}/role` | Change user role | ROOT |
-| POST | `/api/v1/admin/accounts/{account_id}/users/{user_id}/key` | Regenerate user key | ROOT/ADMIN |
-
-### VikingBot Interaction Endpoints (Optional)
-
-VikingBot API requires the server to be started with the `--with-bot` option:
-
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/health` | Bot health check (reused with system /health) |
-| POST | `/chat` | Send message to Bot |
-| POST | `/chat/stream` | Bot streaming response |
+| POST | `/api/v1/admin/accounts` | Create an account and its first administrator |
+| GET | `/api/v1/admin/accounts` | List accounts |
+| POST | `/api/v1/admin/migrate` | Migrate legacy identity data |
+| DELETE | `/api/v1/admin/accounts/{account_id}` | Delete an account |
+| POST | `/api/v1/admin/accounts/{account_id}/users` | Register a user |
+| GET | `/api/v1/admin/accounts/{account_id}/users` | List users |
+| DELETE | `/api/v1/admin/accounts/{account_id}/users/{user_id}` | Remove a user |
+| PUT | `/api/v1/admin/accounts/{account_id}/users/{user_id}/role` | Change a user role |
+| POST | `/api/v1/admin/accounts/{account_id}/users/{user_id}/key` | Regenerate a user key |
+| GET | `/api/v1/privacy-configs` | List privacy configuration categories |
+| GET | `/api/v1/privacy-configs/{category}` | List category targets |
+| GET | `/api/v1/privacy-configs/{category}/{target_key}` | Get the active configuration |
+| GET | `/api/v1/privacy-configs/{category}/{target_key}/versions` | List configuration versions |
+| GET | `/api/v1/privacy-configs/{category}/{target_key}/versions/{version}` | Get one version |
+| POST | `/api/v1/privacy-configs/{category}/{target_key}` | Write and activate a new version |
+| POST | `/api/v1/privacy-configs/{category}/{target_key}/activate` | Activate a version |
-### WebDAV Endpoints
+### [WebDAV](20-webdav.md) and [VikingBot API](24-vikingbot.md)
| Method | Path | Description |
|--------|------|-------------|
-| OPTIONS | `/webdav/resources`, `/webdav/resources/{path}` | WebDAV options query |
-| PROPFIND | `/webdav/resources`, `/webdav/resources/{path}` | WebDAV property query |
-| GET/HEAD | `/webdav/resources/{path}` | Read file |
-| PUT | `/webdav/resources/{path}` | Upload/create file (UTF-8 text only) |
-| DELETE | `/webdav/resources/{path}` | Delete file/directory |
-| MKCOL | `/webdav/resources/{path}` | Create directory |
-| MOVE | `/webdav/resources/{path}` | Move/rename resource |
+| OPTIONS | `/webdav/resources`, `/webdav/resources/{resource_path}` | Query WebDAV capabilities |
+| PROPFIND | `/webdav/resources`, `/webdav/resources/{resource_path}` | Query resource properties |
+| GET / HEAD | `/webdav/resources`, `/webdav/resources/{resource_path}` | Read a file or directory |
+| PUT | `/webdav/resources`, `/webdav/resources/{resource_path}` | Write a UTF-8 text file |
+| DELETE | `/webdav/resources`, `/webdav/resources/{resource_path}` | Delete a file or directory |
+| MKCOL | `/webdav/resources`, `/webdav/resources/{resource_path}` | Create a directory |
+| MOVE | `/webdav/resources`, `/webdav/resources/{resource_path}` | Move or rename a resource |
+| GET | `/bot/v1/health` | VikingBot health check |
+| POST | `/bot/v1/chat` | Non-streaming VikingBot chat |
+| POST | `/bot/v1/chat/stream` | Streaming VikingBot chat |
+| POST | `/bot/v1/feedback` | Submit feedback for a VikingBot answer |
---
## Documentation Reading Plan
-Subsequent API documentation is organized by functional module as follows:
-
-| Document | Content |
-|----------|---------|
-| [Resources](02-resources.md) - Resource management API | Adding, importing, exporting resources and skills |
-| [Retrieval](06-retrieval.md) - Search API | Search, relations, context acquisition |
-| [File System](03-filesystem.md) - File system operations | Directory operations, content reading and writing |
-| [Snapshots](11-snapshot.md) - Multi-version management | Snapshot commit, history walk, single-file diff, version restore |
-| [Sessions](05-sessions.md) - Session management | Session creation, message management, memory extraction |
-| [Skills](04-skills.md) - Skill management API | Skill management |
-| [System](07-system.md) - System and monitoring API | System status, monitoring, debug API |
-| [Privacy Configs](10-privacy.md) - Privacy config version management and activation | Privacy configuration |
-| [Metrics](09-metrics.md) - Prometheus metrics export and scraping guide | Metrics documentation |
-| [Admin](08-admin.md) - Multi-tenant management API | Multi-tenant account and user management |
+The sidebar is organized by responsibility rather than historical file size:
+
+| Group | What to look for |
+|-------|------------------|
+| Core Data | Resources, content, filesystem, skills, sessions, and memory |
+| Retrieval & Relations | Semantic retrieval, code retrieval, and resource relations |
+| Data Lifecycle | Watches, snapshots, and OVPack |
+| Operations & Observability | System, tasks, Observer, and Metrics |
+| Identity & Governance | Administration and privacy configuration |
+| Protocols & Extensions | WebDAV and VikingBot API |
diff --git a/docs/en/api/02-resources.md b/docs/en/api/02-resources.md
index cd086c2db..301b4fbc9 100644
--- a/docs/en/api/02-resources.md
+++ b/docs/en/api/02-resources.md
@@ -537,312 +537,7 @@ For Git repository sources with `wait=false`, the background task has `task_type
---
-### Watch Management
-
-List, inspect, update, and trigger watch tasks created via [`add_resource`](#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.
-
-#### 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.
-
-**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.
-- **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
-
-**Code Entry Points**:
-- `openviking/server/routers/watches.py` — REST router for `/api/v1/watches`
-- `crates/ov_cli/src/commands/watch.rs` — `ov task watch` CLI subcommand group
-- `openviking/server/mcp_endpoint.py` — MCP `list_watches` / `cancel_watch` tools and the `watch_interval` / `to` parameters on `add_resource`
-- `openviking/resource/watch_manager.py:WatchManager` — task persistence and scheduling primitives
-
-#### 2. Interface and Parameter Description
-
-For every single-task endpoint the path `{task_id}` can be replaced with a `?to_uri=` query argument. The CLI `<key>` argument is auto-classified: any value starting with `viking://` routes to the by-URI path, anything else is treated as a task ID (other URI schemes such as `http://` are rejected locally to avoid silent 404s).
-
-**`PATCH /watches` body** (all fields optional; at least one is required)
-
-| Field | Type | Description |
-|-------|------|-------------|
-| watch_interval | float | New cadence in minutes. Must be `> 0`; use `is_active=false` to pause without losing the cadence. |
-| is_active | bool | Toggle activation without losing the cadence (pause / resume). |
-| reason | string | Update the recorded reason for the watch. |
-| instruction | string | Update the semantic processing instruction. |
-
-Unrecognized fields are rejected with 422 (`extra="forbid"`). Fields left unset preserve their current values.
-
-#### 3. Usage Examples
-
-**HTTP API**
-
-```bash
-# List active watch tasks (drop ?active_only to include paused ones)
-curl -s "http://localhost:1933/api/v1/watches?active_only=true" \
- -H "X-API-Key: your-key"
-
-# Pause a watch without losing its cadence
-curl -X PATCH "http://localhost:1933/api/v1/watches/<task_id>" \
- -H "X-API-Key: your-key" -H "Content-Type: application/json" \
- -d '{"is_active": false}'
-
-# Trigger an immediate refresh (fire-and-forget; returns before the re-ingest finishes)
-curl -X POST "http://localhost:1933/api/v1/watches/<task_id>/trigger" \
- -H "X-API-Key: your-key"
-
-# Resolve by URI instead of task ID
-curl -X DELETE "http://localhost:1933/api/v1/watches?to_uri=viking://resources/guide.md" \
- -H "X-API-Key: your-key"
-```
-
-**Python SDK**
-
-```python
-watches = client.list_watches(active_only=True)
-client.update_watch(to_uri="viking://resources/guide.md", is_active=False)
-client.trigger_watch(to_uri="viking://resources/guide.md")
-client.delete_watch(to_uri="viking://resources/guide.md")
-```
-
-**Go SDK**
-
-```go
-watches, err := client.ListWatches(ctx, &openviking.ListWatchesOptions{
- ActiveOnly: true,
-})
-updated, err := client.UpdateWatch(ctx, openviking.UpdateWatchOptions{
- ToURI: "viking://resources/guide.md",
- IsActive: openviking.Bool(false),
-})
-triggered, err := client.TriggerWatch(ctx, openviking.WatchRef{
- ToURI: "viking://resources/guide.md",
-})
-deleted, err := client.DeleteWatch(ctx, openviking.WatchRef{
- ToURI: "viking://resources/guide.md",
-})
-_, _, _, _ = watches, updated, triggered, deleted
-```
-
-**CLI** (subcommands of `ov task watch`)
-
-```bash
-# List active watches (drop --active-only to include paused ones)
-ov task watch ls --active-only
-
-# Inspect a single watch (key may be either a viking:// URI or a task_id)
-ov task watch show viking://resources/guide.md
-
-# Pause / resume without losing the cadence
-ov task watch pause viking://resources/guide.md
-ov task watch resume viking://resources/guide.md
-
-# Update the cadence (or any combination of --active / --reason / --instruction)
-ov task watch update viking://resources/guide.md --interval 30
-
-# Trigger an immediate fire-and-forget refresh
-ov task watch trigger viking://resources/guide.md
-
-# Remove a watch task entirely
-ov task watch rm viking://resources/guide.md
-```
-
-**MCP** (agent control plane — minimum closure only)
-
-```text
-list_watches() # one line per task; URIs only, no task_ids surfaced
-cancel_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`](#add_resource) with `watch_interval`; pass `to` explicitly or let the system bind to the `root_uri` returned by this import.
-
----
-
-### add_skill
-
-Add a skill to the knowledge base.
-
-#### 1. API Implementation Overview
-
-Skills are special resources used to define operations or tools that agents can execute.
-
-**Processing Flow**:
-1. Receive skill data or uploaded temporary file
-2. Parse skill definition
-3. Store to skill directory
-4. Wait for skill processing completion if `wait=true`
-
-**Code Entry Points**:
-- `openviking/client/local.py:LocalClient.add_skill` - SDK entry (embedded)
-- `openviking_cli/client/http.py:AsyncHTTPClient.add_skill` - SDK entry (HTTP)
-- `openviking/server/routers/resources.py:add_skill` - HTTP router
-- `openviking/service/resource_service.py` - Core service implementation
-- `crates/ov_cli/src/handlers.rs:handle_add_skill` - CLI handler
-
-#### 2. Interface and Parameter Description
-
-**Parameters**
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| data | Any | No | - | Inline skill content or structured data. Mutually exclusive with `temp_file_id` |
-| temp_file_id | string | No | - | Temporary upload file ID (obtained via [temp_upload](#temp_upload)). Mutually exclusive with `data` |
-| target_uri | string | No | - | Skill root override. Explicit value wins over user and deployment defaults |
-| wait | bool | No | False | Whether to wait for skill processing to complete |
-| timeout | float | No | None | Timeout in seconds, only effective when `wait=True` |
-| telemetry | TelemetryRequest | No | False | Whether to return telemetry data |
-
-When `target_uri` is omitted, the server may use the current user's
-`add_targets.skill_uri` override, then
-`server.user_config_defaults.add_targets.skill_uri`. If neither is set,
-legacy behavior installs under the current user's skills root. The public
-short form `viking://user/skills` resolves to
-`viking://user/{user_id}/skills`. The v1 API accepts only
-`viking://user/skills` and `viking://agent/skills` as skill add roots.
-
-#### 3. Usage Examples
-
-**HTTP API**
-
-```
-POST /api/v1/skills
-Content-Type: application/json
-```
-
-```bash
-# Using inline data
-curl -X POST http://localhost:1933/api/v1/skills \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d '{
- "data": {
- "name": "my-skill",
- "description": "My custom skill",
- "steps": []
- }
- }'
-
-# Using local file (requires temp_upload first)
-TEMP_FILE_ID=$(
- curl -s -X POST http://localhost:1933/api/v1/resources/temp_upload \
- -H "X-API-Key: your-key" \
- -F "file=@./skills/my-skill.json" \
- | jq -r '.result.temp_file_id'
-)
-
-curl -X POST http://localhost:1933/api/v1/skills \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d "{
- \"temp_file_id\": \"$TEMP_FILE_ID\"
- }"
-```
-
-**Python SDK**
-
-```python
-import openviking as ov
-
-client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")
-client.initialize()
-
-# Add skill from local file
-result = client.add_skill("./skills/my-skill.json")
-
-# Wait for processing to complete
-client.wait_processed()
-```
-
-**TypeScript SDK**
-
-```typescript
-const task = await client.addSkill("./my-skill", { wait: true });
-console.log(task);
-```
-
-**Go SDK**
-
-```go
-result, err := client.AddSkill(ctx, "./skills/my-skill.json", &openviking.AddSkillOptions{
- Wait: true,
-})
-if err != nil {
- return err
-}
-fmt.Println(result["uri"])
-```
-
-**CLI**
-
-```bash
-# Add skill
-ov add-skill ./skills/my-skill.json
-
-# Wait for processing to complete
-ov add-skill ./skills/my-skill.json --wait
-```
-
-#### 4. Response Example
-
-**HTTP API Response (JSON)**
-
-```json
-{
- "status": "ok",
- "result": {
- "status": "success",
- "root_uri": "viking://user/alice/skills/my-skill",
- "uri": "viking://user/alice/skills/my-skill",
- "name": "my-skill",
- "auxiliary_files": 2,
- "queue_status": {
- "pending": 0,
- "processing": 0,
- "completed": 1
- }
- },
- "telemetry": {
- "operation_id": "550e8400-e29b-41d4-a716-446655440000"
- }
-}
-```
-
-**CLI Response (Default Table Format)**
-
-```
-Note: Skill is being processed in the background.
-Use 'ov wait' to wait for completion, or 'ov observer queue' to check status.
-status success
-root_uri viking://user/alice/skills/my-skill
-uri viking://user/alice/skills/my-skill
-name my-skill
-auxiliary_files 2
-```
-
-**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
-}
-```
-
-**Field Description**
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `status` | string | Processing status: "success" or "error" |
-| `root_uri` | string | Canonical final URI of the skill in OpenViking (same as `uri`) |
-| `uri` | string | Canonical final URI of the skill in OpenViking (same as `root_uri`) |
-| `name` | string | Skill name |
-| `auxiliary_files` | number | Number of auxiliary files attached to the skill |
-| `queue_status` | object | (Optional, only when `wait=true`) Queue processing status with `pending`, `processing`, `completed` counts |
-
----
+<a id="watch-management"></a><a id="add_skill"></a>
### temp_upload
diff --git a/docs/en/api/03-filesystem.md b/docs/en/api/03-filesystem.md
index 25148e6a3..eeda19823 100644
--- a/docs/en/api/03-filesystem.md
+++ b/docs/en/api/03-filesystem.md
@@ -2,352 +2,11 @@
OpenViking provides Unix-like file system operations for managing context.
-## WebDAV (Phase 1)
-
-OpenViking Server also exposes a minimal WebDAV adapter for resource files:
-
-```text
-/webdav/resources
-```
-
-Phase 1 intentionally keeps the scope narrow:
-
-- Resources only. Memories, skills, sessions, and other namespaces are not exposed.
-- Text-first writes. `PUT` currently accepts UTF-8 text content only.
-- WebDAV subset only. `OPTIONS`, `PROPFIND`, `GET`, `HEAD`, `PUT`, `DELETE`, `MKCOL`, and `MOVE` are supported.
-- Semantic sidecars and internal system files stay internal. Derived or internal files such as `.abstract.md`, `.overview.md`, `.relations.json`, `.path.ovlock`, `.redirect.json`, and `.sync_log.json` are hidden from listings and cannot be accessed directly through WebDAV.
-
-Behavior notes:
-
-- Creating a new file through WebDAV triggers OpenViking semantic generation for that file path.
-- Replacing an existing file through WebDAV refreshes related semantics and vectors, same as `write()`.
-- `PUT` does not create parent collections automatically. Create missing directories with `MKCOL` first.
-- User-created dot-directories and dot-files remain visible unless they match one of the reserved internal filenames above.
-- When multi-write storage is enabled, files redirected to a backup are still exposed through the filesystem APIs as normal files; internal redirect and sync metadata never become visible to callers.
+<a id="webdav"></a><a id="webdav-phase-1"></a>
## API Reference
-### abstract()
-
-Read L0 abstract (~100 tokens summary).
-
-**Parameters**
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| uri | str | Yes | - | Viking URI (must be a directory) |
-
-
-**Python SDK (Embedded / HTTP)**
-
-```python
-abstract = client.abstract("viking://resources/docs/")
-print(f"Abstract: {abstract}")
-# Output: "Documentation for the project API, covering authentication, endpoints..."
-```
-
-**TypeScript SDK**
-
-```typescript
-const abstract = await client.abstract("viking://resources/docs/");
-console.log(abstract);
-```
-
-**Go SDK**
-
-```go
-abstract, err := client.Abstract(ctx, "viking://resources/docs/")
-if err != nil {
- return err
-}
-fmt.Println(abstract)
-```
-
-**HTTP API**
-
-```
-GET /api/v1/content/abstract?uri={uri}
-```
-
-```bash
-curl -X GET "http://localhost:1933/api/v1/content/abstract?uri=viking://resources/docs/" \
- -H "X-API-Key: your-key"
-```
-
-**CLI**
-
-```bash
-openviking abstract viking://resources/docs/
-```
-
-
-**Response**
-
-```json
-{
- "status": "ok",
- "result": "Documentation for the project API, covering authentication, endpoints...",
- "time": 0.1
-}
-```
-
----
-
-### overview()
-
-Read L1 overview, applies to directories.
-
-**Parameters**
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| uri | str | Yes | - | Viking URI (must be a directory) |
-
-
-**Python SDK (Embedded / HTTP)**
-
-```python
-overview = client.overview("viking://resources/docs/")
-print(f"Overview:\n{overview}")
-```
-
-**TypeScript SDK**
-
-```typescript
-const overview = await client.overview("viking://resources/docs/");
-console.log(overview);
-```
-
-**Go SDK**
-
-```go
-overview, err := client.Overview(ctx, "viking://resources/docs/")
-if err != nil {
- return err
-}
-fmt.Println(overview)
-```
-
-**HTTP API**
-
-```
-GET /api/v1/content/overview?uri={uri}
-```
-
-```bash
-curl -X GET "http://localhost:1933/api/v1/content/overview?uri=viking://resources/docs/" \
- -H "X-API-Key: your-key"
-```
-
-**CLI**
-
-```bash
-openviking overview viking://resources/docs/
-```
-
-
-**Response**
-
-```json
-{
- "status": "ok",
- "result": "## docs/\n\nContains API documentation and guides...",
- "time": 0.1
-}
-```
-
----
-
-### read()
-
-Read L2 full content.
-
-**Parameters**
-
-| 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 |
-| raw | bool | No | false | Return raw stored content without memory-field cleanup. HTTP API only (Python SDK does not expose it yet). |
-
-**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.
-- 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`.
-
-
-**Python SDK (Embedded / HTTP)**
-
-```python
-content = client.read("viking://resources/docs/api.md")
-print(f"Content:\n{content}")
-```
-
-**TypeScript SDK**
-
-```typescript
-const content = await client.read("viking://resources/docs/api.md", 0, -1);
-console.log(content);
-```
-
-**Go SDK**
-
-```go
-content, err := client.Read(ctx, "viking://resources/docs/api.md", 0, -1)
-if err != nil {
- return err
-}
-fmt.Println(content)
-```
-
-**HTTP API**
-
-```
-GET /api/v1/content/read?uri={uri}
-```
-
-```bash
-curl -X GET "http://localhost:1933/api/v1/content/read?uri=viking://resources/docs/api.md" \
- -H "X-API-Key: your-key"
-```
-
-**CLI**
-
-```bash
-openviking read viking://resources/docs/api.md
-```
-
-
-**Response**
-
-```json
-{
- "status": "ok",
- "result": "# API Documentation\n\nFull content of the file...",
- "time": 0.1
-}
-```
-
----
-
-### write()
-
-Update an existing file, or create a new one when `mode="create"`, and automatically refresh related semantics and vectors.
-
-**Parameters**
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| uri | str | Yes | - | File URI to write. For `mode="create"`, the file must not already exist |
-| content | str | Yes | - | New content to write |
-| mode | str | No | `replace` | `replace`, `append`, or `create` |
-| wait | bool | No | `false` | Wait for background semantic/vector refresh |
-| timeout | float | No | `null` | Timeout in seconds when `wait=true` |
-
-**Notes**
-
-- `replace` and `append` require the file to exist; `create` targets a new file and returns `409 Conflict` when the path already exists. Directories are always rejected.
-- `create` only accepts text-writable extensions: `.md`, `.txt`, `.json`, `.yaml`, `.yml`, `.toml`, `.py`, `.js`, `.ts`. Parent directories are created automatically.
-- Derived semantic files cannot be written directly: `.abstract.md`, `.overview.md`, `.relations.json`.
-- File content is updated before the API returns. `wait` only controls whether the call waits for semantic/vector refresh to finish.
-- The public API no longer accepts `regenerate_semantics` or `revectorize`; write always refreshes related semantics and vectors.
-
-
-**Python SDK (Embedded / HTTP)**
-
-```python
-result = client.write(
- "viking://resources/docs/api.md",
- "# Updated API\n\nFresh content.",
- mode="replace",
- wait=True,
-)
-print(result["root_uri"])
-```
-
-**TypeScript SDK**
-
-```typescript
-await client.write("viking://resources/docs/new.md", "# New document\n", { wait: true });
-```
-
-**Go SDK**
-
-```go
-result, err := client.Write(
- ctx,
- "viking://resources/docs/api.md",
- "# Updated API\n\nFresh content.",
- &openviking.WriteOptions{
- Mode: "replace",
- Wait: true,
- },
-)
-if err != nil {
- return err
-}
-fmt.Println(result["root_uri"])
-```
-
-**HTTP API**
-
-```
-POST /api/v1/content/write
-```
-
-```bash
-curl -X POST "http://localhost:1933/api/v1/content/write" \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d '{
- "uri": "viking://resources/docs/api.md",
- "content": "# Updated API\n\nFresh content.",
- "mode": "replace",
- "wait": true
- }'
-```
-
-**CLI**
-
-```bash
-openviking write viking://resources/docs/api.md \
- --content "# Updated API\n\nFresh content." \
- --wait
-```
-
-
-**Response**
-
-```json
-{
- "status": "ok",
- "result": {
- "uri": "viking://resources/docs/api.md",
- "root_uri": "viking://resources/docs",
- "context_type": "resource",
- "mode": "replace",
- "written_bytes": 29,
- "content_updated": true,
- "semantic_status": "complete",
- "vector_status": "complete",
- "queue_status": {
- "Semantic": {
- "processed": 1,
- "error_count": 0,
- "errors": []
- },
- "Embedding": {
- "processed": 2,
- "error_count": 0,
- "errors": []
- }
- }
- }
-}
-```
-
----
+<a id="abstract"></a><a id="overview"></a><a id="read"></a><a id="write"></a>
### ls()
@@ -1002,802 +661,11 @@ openviking mv viking://resources/old-name/ viking://resources/new-name/
}
```
----
-
-### grep()
-
-Search content by pattern.
-
-**Parameters**
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| 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 | 256 | Maximum number of results. Omitted requests default to 256; pass a larger integer when you need more results |
-| level_limit | int | No | Python SDK: 5; HTTP API / CLI / Go SDK: 10 | Maximum directory depth to traverse. The Go SDK currently uses the HTTP API default. |
-
-
-**Python SDK (Embedded / HTTP)**
-
-```python
-results = client.grep(
- "viking://resources/",
- "authentication",
- case_insensitive=True,
- node_limit=1024,
-)
-
-print(f"Found {results['count']} matches")
-for match in results['matches']:
- print(f" {match['uri']}:{match['line']}")
- print(f" {match['content']}")
-```
-
-**TypeScript SDK**
-
-```typescript
-const matches = await client.grep("viking://resources/docs/", "authentication");
-console.log(matches);
-```
+<a id="grep"></a><a id="glob"></a>
-**Go SDK**
+<a id="link"></a><a id="relations"></a><a id="unlink"></a>
-```go
-nodeLimit := 1024
-result, err := client.Grep(ctx, "viking://resources/", "authentication", &openviking.GrepOptions{
- CaseInsensitive: true,
- NodeLimit: &nodeLimit,
-})
-if err != nil {
- return err
-}
-fmt.Println(result["matches"])
-```
-
-**HTTP API**
-
-```
-POST /api/v1/search/grep
-```
-
-```bash
-curl -X POST http://localhost:1933/api/v1/search/grep \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d '{
- "uri": "viking://resources/",
- "pattern": "authentication",
- "case_insensitive": true
- }'
-```
-
-**CLI**
-
-```bash
-openviking grep "authentication" --uri viking://resources/ [--ignore-case]
-```
-
-
-**Response**
-
-```json
-{
- "status": "ok",
- "result": {
- "matches": [
- {
- "uri": "viking://resources/docs/auth.md",
- "line": 15,
- "content": "User authentication is handled by..."
- }
- ],
- "count": 1
- },
- "time": 0.1
-}
-```
-
----
-
-### glob()
-
-Match files by pattern.
-
-**Parameters**
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| pattern | str | Yes | - | Glob pattern (e.g., `**/*.md`) |
-| uri | str | No | "viking://" | Starting URI |
-| node_limit | int | No | 256 | Maximum number of results |
-
-
-**Python SDK (Embedded / HTTP)**
-
-```python
-# Find all markdown files
-results = client.glob("**/*.md", "viking://resources/")
-print(f"Found {results['count']} markdown files:")
-for uri in results['matches']:
- print(f" {uri}")
-
-# Find all Python files
-results = client.glob("**/*.py", "viking://resources/")
-print(f"Found {results['count']} Python files")
-```
-
-**TypeScript SDK**
-
-```typescript
-const matches = await client.glob("**/*.md", "viking://resources/docs/");
-console.log(matches);
-```
-
-**Go SDK**
-
-```go
-result, err := client.Glob(ctx, "**/*.md", "viking://resources/", &openviking.GlobOptions{
- NodeLimit: openviking.Int(1024),
-})
-if err != nil {
- return err
-}
-fmt.Println(result["matches"])
-```
-
-**HTTP API**
-
-```
-POST /api/v1/search/glob
-```
-
-```bash
-curl -X POST http://localhost:1933/api/v1/search/glob \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d '{
- "pattern": "**/*.md",
- "uri": "viking://resources/"
- }'
-```
-
-**CLI**
-
-```bash
-openviking glob "**/*.md" [--uri viking://resources/]
-```
-
-
-**Response**
-
-```json
-{
- "status": "ok",
- "result": {
- "matches": [
- "viking://resources/docs/api.md",
- "viking://resources/docs/guide.md"
- ],
- "count": 2
- },
- "time": 0.1
-}
-```
-
----
-
-### link()
-
-Create relations between resources.
-
-**Parameters**
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| from_uri | str | Yes | - | Source URI |
-| to_uris | str or List[str] | Yes | - | Target URI(s) |
-| reason | str | No | "" | Reason for the link |
-
-
-**Python SDK (Embedded / HTTP)**
-
-```python
-# Single link
-client.link(
- "viking://resources/docs/auth/",
- "viking://resources/docs/security/",
- reason="Security best practices for authentication"
-)
-
-# Multiple links
-client.link(
- "viking://resources/docs/api/",
- [
- "viking://resources/docs/auth/",
- "viking://resources/docs/errors/"
- ],
- reason="Related documentation"
-)
-```
-
-**TypeScript SDK**
-
-```typescript
-await client.link(
- "viking://resources/docs/api/",
- [
- "viking://resources/docs/auth/",
- "viking://resources/docs/errors/",
- ],
- "Related documentation",
-);
-```
-
-**HTTP API**
-
-```
-POST /api/v1/relations/link
-```
-
-```bash
-# Single link
-curl -X POST http://localhost:1933/api/v1/relations/link \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d '{
- "from_uri": "viking://resources/docs/auth/",
- "to_uris": "viking://resources/docs/security/",
- "reason": "Security best practices for authentication"
- }'
-
-# Multiple links
-curl -X POST http://localhost:1933/api/v1/relations/link \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d '{
- "from_uri": "viking://resources/docs/api/",
- "to_uris": ["viking://resources/docs/auth/", "viking://resources/docs/errors/"],
- "reason": "Related documentation"
- }'
-```
-
-**CLI**
-
-```bash
-openviking link viking://resources/docs/auth/ viking://resources/docs/security/ --reason "Security best practices"
-```
-
-
-**Response**
-
-```json
-{
- "status": "ok",
- "result": {
- "from": "viking://resources/docs/auth/",
- "to": "viking://resources/docs/security/"
- },
- "time": 0.1
-}
-```
-
----
-
-### relations()
-
-Get relations for a resource.
-
-**Parameters**
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| uri | str | Yes | - | Viking URI |
-
-
-**Python SDK (Embedded / HTTP)**
-
-```python
-relations = client.relations("viking://resources/docs/auth/")
-for rel in relations:
- print(f"Related: {rel['uri']}")
- print(f" Reason: {rel['reason']}")
-```
-
-**TypeScript SDK**
-
-```typescript
-const relations = await client.relations("viking://resources/docs/auth/");
-console.log(relations);
-```
-
-**HTTP API**
-
-```
-GET /api/v1/relations?uri={uri}
-```
-
-```bash
-curl -X GET "http://localhost:1933/api/v1/relations?uri=viking://resources/docs/auth/" \
- -H "X-API-Key: your-key"
-```
-
-**CLI**
-
-```bash
-openviking relations viking://resources/docs/auth/
-```
-
-
-**Response**
-
-```json
-{
- "status": "ok",
- "result": [
- {"uri": "viking://resources/docs/security/", "reason": "Security best practices"},
- {"uri": "viking://resources/docs/errors/", "reason": "Error handling"}
- ],
- "time": 0.1
-}
-```
-
----
-
-### unlink()
-
-Remove a relation.
-
-**Parameters**
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| from_uri | str | Yes | - | Source URI |
-| to_uri | str | Yes | - | Target URI to unlink |
-
-
-**Python SDK (Embedded / HTTP)**
-
-```python
-client.unlink(
- "viking://resources/docs/auth/",
- "viking://resources/docs/security/"
-)
-```
-
-**TypeScript SDK**
-
-```typescript
-await client.unlink(
- "viking://resources/docs/auth/",
- "viking://resources/docs/security/",
-);
-```
-
-**HTTP API**
-
-```
-DELETE /api/v1/relations/link
-```
-
-```bash
-curl -X DELETE http://localhost:1933/api/v1/relations/link \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d '{
- "from_uri": "viking://resources/docs/auth/",
- "to_uri": "viking://resources/docs/security/"
- }'
-```
-
-**CLI**
-
-```bash
-openviking unlink viking://resources/docs/auth/ viking://resources/docs/security/
-```
-
-
-**Response**
-
-```json
-{
- "status": "ok",
- "result": {
- "from": "viking://resources/docs/auth/",
- "to": "viking://resources/docs/security/"
- },
- "time": 0.1
-}
-```
-
----
-
-### export_ovpack
-
-Export a resource tree as a `.ovpack` file.
-
-#### 1. API Implementation Overview
-
-Packages all resources under the specified URI into a `.ovpack` file for backup or migration. Available to ROOT, ADMIN, and USER roles; normal URI access controls still apply.
-
-**Processing Flow**:
-1. Verify user permissions
-2. Traverse resources under the specified URI
-3. Write content files and the OVPack manifest
-4. Package into zip format (`.ovpack`)
-5. Return as file stream
-
-**Format Notes**:
-- The exported ZIP stores user content unchanged under `<root>/files/` and internal metadata under `<root>/_ovpack/`.
-- The manifest is stored at `<root>/_ovpack/manifest.json`.
-- `entries[].path` is relative to the exported root; `""` means the root directory itself.
-- File entries include `size` and `sha256`; `content_sha256` covers the sorted file list of `path`, `size`, and `sha256`.
-- `_ovpack/index_records.jsonl` stores portable index scalar fields. With `include_vectors=true`, `_ovpack/dense.f32` stores a pure-dense float32 vector snapshot plus embedding metadata; vector indexes whose `VectorIndex.IndexType` is hybrid do not support vector snapshot export.
-- Runtime fields such as `id`, `uri`, `account_id`, `created_at`, `updated_at`, and `active_count` are regenerated in the target environment and are not restored from the package.
-- OVPack does not add package-size, file-count, or directory-depth limits; the practical limit comes from ZIP, the storage backend, and the runtime environment.
-
-**Code Entry Points**:
-- `openviking/server/routers/pack.py:export_ovpack` - HTTP router
-- `openviking/service/pack_service.py` - Core service implementation
-- `crates/ov_cli/src/handlers.rs:handle_export` - CLI handler
-
-#### 2. Interface and Parameter Description
-
-**Parameters**
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| uri | string | Yes | - | Viking URI to export |
-| include_vectors | boolean | No | false | Include a pure-dense vector snapshot; hybrid index types are rejected |
-
-**Permission Requirements**: ROOT, ADMIN, or USER
-
-#### 3. Usage Examples
-
-
-**HTTP API**
-
-```
-POST /api/v1/pack/export
-Content-Type: application/json
-```
-
-```bash
-curl -X POST http://localhost:1933/api/v1/pack/export \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-admin-key" \
- -d '{
- "uri": "viking://resources/my-project/",
- "include_vectors": false
- }' \
- --output my-project.ovpack
-```
-
-**Python SDK**
-
-```python
-import openviking as ov
-
-client = 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
-```
-
-**TypeScript SDK**
-
-```typescript
-const outputPath = await client.exportOVPack(
- "viking://resources/docs/",
- "./exports/docs.ovpack",
- true,
-);
-console.log(outputPath);
-```
-
-**Go SDK**
-
-```go
-outPath, err := client.ExportOVPack(
- ctx,
- "viking://resources/my-project/",
- "./exports/my-project.ovpack",
- &openviking.PackOptions{IncludeVectors: false},
-)
-if err != nil {
- return err
-}
-fmt.Println(outPath)
-```
-
-**CLI**
-
-```bash
-# Export resource
-ov export viking://resources/my-project/ ./exports/my-project.ovpack
-
-# Export with a dense vector snapshot
-ov export viking://resources/my-project/ ./exports/my-project.ovpack --include-vectors
-```
-
-
-**Response Example**
-
-This endpoint directly returns a file stream (`Content-Type: application/zip`), does not return a JSON envelope.
-
----
-
-### import_ovpack
-
-Import a `.ovpack` file.
-
-#### 1. API Implementation Overview
-
-Imports a `.ovpack` file to a specified location for restoring or migrating data. Available to ROOT, ADMIN, and USER roles; normal URI access controls still apply.
-
-**Processing Flow**:
-1. Verify user permissions
-2. Parse uploaded `.ovpack` file
-3. Validate manifest metadata, paths, file and directory sets, file sizes, and checksums
-4. Apply `on_conflict`
-5. Import resources to target location and rebuild vectors
-
-**Code Entry Points**:
-- `openviking/server/routers/pack.py:import_ovpack` - HTTP router
-- `openviking/service/pack_service.py` - Core service implementation
-- `crates/ov_cli/src/handlers.rs:handle_import` - CLI handler
-
-#### 2. Interface and Parameter Description
-
-**Parameters**
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| temp_file_id | string | Yes | - | Temporary upload file ID (obtained via [temp_upload](02-resources.md#temp_upload)) |
-| parent | string | Yes | - | Target parent URI (import to this location) |
-| on_conflict | string | No | fail | Conflict policy: `fail`, `overwrite`, or `skip` |
-| vector_mode | string | No | auto | Vector handling: `auto`, `recompute`, or `require` |
-
-**Permission Requirements**: ROOT, ADMIN, or USER
-
-**Behavior Notes**:
-- The API no longer accepts `vectorize` or `force`.
-- `vector_mode=auto` restores a compatible dense snapshot when present, otherwise recomputes vectors. `recompute` always ignores package vectors. `require` fails unless a compatible dense snapshot is present.
-- Dense snapshot compatibility checks compare embedding provider, model, input mode, query/document parameters, and dimensions.
-- Session files are part of the user namespace (`viking://user/{user_id}/sessions/...`) and do not trigger vectorization.
-- `on_conflict=fail` returns a structured `409 CONFLICT` when the target root already exists.
-- `on_conflict=overwrite` replaces the existing target root. `on_conflict=skip` keeps the existing target root and returns it without writing package contents. `skip` is root-level, not file-level.
-- Packages without a manifest are rejected by default because they cannot provide content integrity guarantees.
-- Packages with manifest entries are rejected if content files or directories are missing, extra files or directories are present, file sizes differ, per-file `sha256` differs, or `content_sha256` is missing or differs.
-- Packages whose manifest `format_version` is not the current supported version (`3`) are rejected.
-- `.abstract.md` and `.overview.md` are restored as semantic sidecars. `.relations.json` and OVPack internals are excluded.
-- Manifest `context_type`, when present in index scalar metadata, must match the final import path semantics.
-- Top-level scope packages such as `viking://resources/` must be imported to `viking://`.
-- OVPack does not add import package-size, file-count, or directory-depth limits; the practical limit comes from ZIP, the storage backend, and the runtime environment.
-
-#### 3. Usage Examples
-
-
-**HTTP API**
-
-```
-POST /api/v1/pack/import
-Content-Type: application/json
-```
-
-```bash
-# Step 1: Upload .ovpack file
-TEMP_FILE_ID=$(
- curl -s -X POST http://localhost:1933/api/v1/resources/temp_upload \
- -H "X-API-Key: your-admin-key" \
- -F "file=@./exports/my-project.ovpack" \
- | jq -r '.result.temp_file_id'
-)
-
-# Step 2: Import
-curl -X POST http://localhost:1933/api/v1/pack/import \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-admin-key" \
- -d "{
- \"temp_file_id\": \"$TEMP_FILE_ID\",
- \"parent\": \"viking://resources/imported/\",
- \"on_conflict\": \"overwrite\",
- \"vector_mode\": \"auto\"
- }"
-```
-
-**Python SDK**
-
-```python
-import openviking as ov
-
-client = 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
-```
-
-**TypeScript SDK**
-
-```typescript
-const uri = await client.importOVPack(
- "./exports/docs.ovpack",
- "viking://resources/",
- {
- onConflict: "overwrite",
- vectorMode: "auto",
- },
-);
-console.log(uri);
-```
-
-**Go SDK**
-
-```go
-uri, err := client.ImportOVPack(
- ctx,
- "./exports/my-project.ovpack",
- "viking://resources/imported/",
- &openviking.ImportPackOptions{
- OnConflict: "overwrite",
- VectorMode: "auto",
- },
-)
-if err != nil {
- return err
-}
-fmt.Println(uri)
-```
-
-**CLI**
-
-```bash
-# Import .ovpack file
-ov import ./exports/my-project.ovpack viking://resources/imported/
-
-# Explicit conflict policy
-ov import ./exports/my-project.ovpack viking://resources/imported/ --on-conflict overwrite
-
-# Require restoring a compatible dense vector snapshot
-ov import ./exports/my-project.ovpack viking://resources/imported/ --vector-mode require
-```
-
-
-**Response Example**
-
-```json
-{
- "status": "ok",
- "result": {
- "uri": "viking://resources/imported/my-project/"
- },
- "telemetry": {
- "operation_id": "550e8400-e29b-41d4-a716-446655440000"
- }
-}
-```
-
-**Conflict Error Example**
-
-```json
-{
- "status": "error",
- "error": {
- "code": "CONFLICT",
- "message": "Resource already exists at viking://resources/imported/my-project. Use on_conflict='overwrite' to replace it.",
- "details": {
- "resource": "viking://resources/imported/my-project"
- }
- }
-}
-```
-
----
-
-### backup_ovpack
-
-Back up public scope roots as a restore-only `.ovpack` file. The backup includes
-`resources` and `user`; sessions are included through the user namespace under
-`user/{user_id}/sessions`. It excludes internal runtime data such as `temp` and
-`queue`. Set `include_vectors=true` to include compatible
-pure-dense vector snapshots; hybrid index types reject vector snapshot export.
-
-```
-POST /api/v1/pack/backup
-```
-
-```bash
-curl -X POST http://localhost:1933/api/v1/pack/backup \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-admin-key" \
- -d '{"include_vectors":false}' \
- --output openviking-backup.ovpack
-```
-
-Go SDK:
-
-```go
-outPath, err := client.BackupOVPack(
- ctx,
- "./backups/openviking.ovpack",
- &openviking.PackOptions{IncludeVectors: true},
-)
-if err != nil {
- return err
-}
-fmt.Println(outPath)
-```
-
-CLI:
-
-```bash
-ov backup ./backups/openviking.ovpack
-ov backup ./backups/openviking.ovpack --include-vectors
-```
-
----
-
-### restore_ovpack
-
-Restore a backup package created by `backup_ovpack` to the original public scope
-roots. Regular import rejects backup packages. Vector handling follows
-`vector_mode`; session files under the user namespace are restored without
-vectorization.
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| temp_file_id | string | Yes | - | Temporary upload file ID |
-| on_conflict | string | No | fail | Conflict policy: `fail`, `overwrite`, or `skip` |
-| vector_mode | string | No | auto | Vector handling: `auto`, `recompute`, or `require` |
-
-```
-POST /api/v1/pack/restore
-Content-Type: application/json
-```
-
-```bash
-TEMP_FILE_ID=$(
- curl -s -X POST http://localhost:1933/api/v1/resources/temp_upload \
- -H "X-API-Key: your-admin-key" \
- -F "file=@./backups/openviking.ovpack" \
- | jq -r '.result.temp_file_id'
-)
-
-curl -X POST http://localhost:1933/api/v1/pack/restore \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-admin-key" \
- -d "{\"temp_file_id\":\"$TEMP_FILE_ID\",\"on_conflict\":\"overwrite\",\"vector_mode\":\"auto\"}"
-```
-
-Go SDK:
-
-```go
-uri, err := client.RestoreOVPack(
- ctx,
- "./backups/openviking.ovpack",
- &openviking.ImportPackOptions{
- OnConflict: "overwrite",
- VectorMode: "require",
- },
-)
-if err != nil {
- return err
-}
-fmt.Println(uri)
-```
-
-CLI:
-
-```bash
-ov restore ./backups/openviking.ovpack --on-conflict overwrite
-ov restore ./backups/openviking.ovpack --on-conflict overwrite --vector-mode require
-```
-
----
+<a id="export_ovpack"></a><a id="import_ovpack"></a><a id="backup_ovpack"></a><a id="restore_ovpack"></a>
## Related Documentation
diff --git a/docs/en/api/04-skills.md b/docs/en/api/04-skills.md
index 4645b6920..662904b68 100644
--- a/docs/en/api/04-skills.md
+++ b/docs/en/api/04-skills.md
@@ -574,10 +574,24 @@ _, _ = validated, updated
**HTTP API**
```bash
+# Validate skill data
curl -X POST http://localhost:1933/api/v1/skills/validate \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{"data": {"name": "search-web", "description": "..."}}'
+
+# Replace an existing skill with new content
+curl -X PUT http://localhost:1933/api/v1/skills/search-web \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "data": {
+ "name": "search-web",
+ "description": "Search the web for current information",
+ "content": "# search-web\n\nUpdated instructions."
+ },
+ "wait": true
+ }'
```
### Delete Skills
@@ -608,6 +622,82 @@ curl -X DELETE "http://localhost:1933/api/v1/skills/old-skill" \
-H "X-API-Key: your-key"
```
+### 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`.
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "root_uris": [
+ "viking://user/default/skills",
+ "viking://agent/skills"
+ ],
+ "skills": [
+ {
+ "type": "skill",
+ "name": "search-web",
+ "uri": "viking://user/default/skills/search-web",
+ "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",
+ "tags": [],
+ "allowed_tools": [],
+ "score": 0.87,
+ "match_reason": "semantic",
+ "level": 0
+ }
+ ],
+ "total": 1
+ }
+}
+```
+
+Reading one skill returns the metadata above and conditionally adds `abstract`, `overview`, `content`, `files`, and `source` according to `level` and the `include_*` parameters.
+
+Validation returns `valid`, `strict`, normalized metadata, `body_lines`, `errors`, and `warnings`. Invalid input still uses a successful response envelope with `valid=false`:
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "valid": false,
+ "strict": false,
+ "name": "search-web",
+ "description": "",
+ "tags": [],
+ "allowed_tools": [],
+ "body_lines": 0,
+ "errors": [
+ {
+ "rule": "description_required",
+ "message": "description is required",
+ "field": "description"
+ }
+ ],
+ "warnings": []
+ }
+}
+```
+
+A successful update returns the same processing result as `add_skill` with an additional `"action": "update"`. A successful delete returns:
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "name": "old-skill",
+ "uri": "viking://user/default/skills/old-skill",
+ "root_uri": "viking://user/default/skills/old-skill",
+ "estimated_deleted_count": 4,
+ "privacy_deleted": false
+ }
+}
+```
+
+`estimated_deleted_count` appears only when the filesystem can estimate the number of deleted entries.
+
## Best Practices
### Clear Descriptions
diff --git a/docs/en/api/05-sessions.md b/docs/en/api/05-sessions.md
index f9402d56b..57866c08f 100644
--- a/docs/en/api/05-sessions.md
+++ b/docs/en/api/05-sessions.md
@@ -350,6 +350,145 @@ ov session get a1b2c3d4
---
+### list_tool_results()
+
+List large tool results externalized from a session.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `session_id` | string | Yes | - | Session ID |
+| `tool_name` | string | No | - | Filter by tool name |
+| `limit` | integer | No | `50` | Maximum results |
+
+**HTTP API**
+
+```http
+GET /api/v1/sessions/{session_id}/tool-results
+```
+
+```bash
+curl --get http://localhost:1933/api/v1/sessions/session-id/tool-results \
+ -H "X-API-Key: your-key" \
+ --data-urlencode "tool_name=search" \
+ --data-urlencode "limit=50"
+```
+
+**Response example**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "tool_results": [
+ {
+ "tool_result_id": "tr_search_a1b2c3",
+ "tool_name": "search",
+ "original_chars": 48210,
+ "preview_chars": 2000,
+ "mime_type": "text/plain",
+ "synopsis_kind": "text",
+ "storage_uri": "viking://user/default/sessions/session-id/tool-results/tr_search_a1b2c3",
+ "offset_unit": "unicode_code_point"
+ }
+ ]
+ }
+}
+```
+
+### read_tool_result()
+
+Read one externalized tool result by Unicode character range.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `session_id` | string | Yes | - | Session ID |
+| `tool_result_id` | string | Yes | - | Tool-result ID |
+| `offset` | integer | No | `0` | Starting character offset |
+| `limit` | integer | No | `20000` | Maximum characters; `-1` reads to the end |
+| `include_metadata` | boolean | No | `true` | Include metadata in the response |
+
+**HTTP API**
+
+```http
+GET /api/v1/sessions/{session_id}/tool-results/{tool_result_id}
+```
+
+```bash
+curl --get http://localhost:1933/api/v1/sessions/session-id/tool-results/tool-result-id \
+ -H "X-API-Key: your-key" \
+ --data-urlencode "offset=0" \
+ --data-urlencode "limit=20000"
+```
+
+**Response example**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "tool_result_id": "tr_search_a1b2c3",
+ "content": "A chunk of the tool output...",
+ "offset": 0,
+ "limit": 20000,
+ "offset_unit": "unicode_code_point",
+ "total_chars": 48210,
+ "has_more": true,
+ "metadata": {
+ "tool_name": "search",
+ "mime_type": "text/plain",
+ "sha256": "..."
+ }
+ }
+}
+```
+
+`metadata` is omitted when `include_metadata=false`. To continue reading, set the next request's `offset` to the current `offset` plus the Unicode character count of `content`.
+
+### search_tool_result()
+
+Search within one externalized tool result and return context around each match.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `q` | string | Yes | - | Search text |
+| `limit` | integer | No | `20` | Maximum matches |
+| `context_chars` | integer | No | `300` | Context characters around each match |
+
+**HTTP API**
+
+```http
+GET /api/v1/sessions/{session_id}/tool-results/{tool_result_id}/search?q={query}
+```
+
+```bash
+curl --get http://localhost:1933/api/v1/sessions/session-id/tool-results/tool-result-id/search \
+ -H "X-API-Key: your-key" \
+ --data-urlencode "q=authentication" \
+ --data-urlencode "limit=20"
+```
+
+**Response example**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "tool_result_id": "tr_search_a1b2c3",
+ "matches": [
+ {
+ "offset": 1284,
+ "offset_unit": "unicode_code_point",
+ "snippet": "...authentication failed because..."
+ }
+ ]
+ }
+}
+```
+
+These endpoints are currently used by the Server and Web Studio. The public SDKs and CLI do not wrap them, so the sections above show only the HTTP tab.
+
+---
+
### get_session_context()
#### 1. API Implementation Introduction
@@ -1217,228 +1356,7 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/extract \
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()
-
-#### 1. API Implementation Introduction
-
-Query background task status for APIs that return `task_id`, such as session commit, `add_resource`, and admin reindex.
-
-**Task Statuses:**
-- `pending`: Task waiting to execute
-- `running`: Task in progress
-- `completed`: Task successfully completed
-- `failed`: Task failed
-
-**Code Entries:**
-- `openviking/server/routers/tasks.py:get_task()` - HTTP route
-
-Task records are persisted in AGFS and can be queried after server restart, subject to task retention cleanup.
-
-#### 2. Interface and Parameter Description
-
-**Parameters**
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| task_id | str | Yes | - | Task ID returned by a background API |
-
-#### 3. Usage Examples
-
-**HTTP API**
-
-```http
-GET /api/v1/tasks/{task_id}
-```
-
-```bash
-curl -X GET http://localhost:1933/api/v1/tasks/uuid-xxx \
- -H "X-API-Key: your-key"
-```
-
-**Python SDK**
-
-```python
-import openviking as ov
-
-client = ov.Client(base_url="http://localhost:1933", api_key="your-key")
-
-task = await client.get_task(task_id="uuid-xxx")
-print(f"Status: {task['status']}")
-```
-
-**TypeScript SDK**
-
-```typescript
-console.log(await client.getTask("task-id"));
-```
-
-**Go SDK**
-
-```go
-task, err := client.GetTask(ctx, "uuid-xxx")
-if err != nil {
- return err
-}
-if task != nil {
- fmt.Println(task["status"])
-}
-```
-
-**Response Example (resource import in progress)**
-
-```json
-{
- "status": "ok",
- "result": {
- "task_id": "uuid-xxx",
- "task_type": "add_resource",
- "status": "running",
- "resource_id": "viking://resources/guide",
- "stage": "processing_queue"
- }
-}
-```
-
-`stage` is nullable. Git repository resource import tasks may report `queued`, `fetching`, `parsing`, `finalizing`, or `processing_queue`; other task types may leave it as `null`. Live queue counters are intentionally not part of task status; use observer queue APIs for live counts, or read `result.queue_status` after completion.
-
-**Response Example (completed)**
-
-```json
-{
- "status": "ok",
- "result": {
- "task_id": "uuid-xxx",
- "task_type": "session_commit",
- "status": "completed",
- "result": {
- "session_id": "a1b2c3d4",
- "archive_uri": "viking://user/alice/sessions/a1b2c3d4/history/archive_001",
- "memory_diff_uri": "viking://user/alice/sessions/a1b2c3d4/history/archive_001/memory_diff.json",
- "memories_extracted": {
- "profile": 1,
- "preferences": 2,
- "entities": 1,
- "cases": 1
- },
- "active_count_updated": 2,
- "token_usage": {
- "llm": {
- "prompt_tokens": 5200,
- "completion_tokens": 1800,
- "total_tokens": 7000
- },
- "embedding": {
- "total_tokens": 1500
- },
- "total": {
- "total_tokens": 8500
- }
- }
- }
- }
-}
-```
-
-`memories_extracted` in the completed task result reports per-category counts for this commit only. Sum its values when you want the total for this commit.
-
----
-
-### list_tasks()
-
-#### 1. API Implementation Introduction
-
-List background tasks visible to the current caller, supporting filtering by type, status, resource.
-
-**Code Entries:**
-- `openviking/server/routers/tasks.py:list_tasks()` - HTTP route
-- `openviking_cli/client/base.py:BaseClient.list_tasks()` - Python SDK
-
-#### 2. Interface and Parameter Description
-
-**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 |
-
-#### 3. Usage Examples
-
-**HTTP API**
-
-```http
-GET /api/v1/tasks?task_type=session_commit&status=running&limit=20
-```
-
-```bash
-curl -X GET "http://localhost:1933/api/v1/tasks?task_type=session_commit&status=running&limit=20" \
- -H "X-API-Key: your-key"
-```
-
-**Python SDK**
-
-```python
-import openviking as ov
-
-client = ov.Client(base_url="http://localhost:1933", api_key="your-key")
-
-tasks = await client.list_tasks(
- task_type="session_commit",
- status="running",
- limit=20,
-)
-for task in tasks:
- print(task["task_id"], task["status"])
-```
-
-**TypeScript SDK**
-
-```typescript
-console.log(await client.listTasks());
-```
-
-**Go SDK**
-
-```go
-tasks, err := client.ListTasks(ctx, &openviking.ListTasksOptions{
- TaskType: "session_commit",
- Status: "running",
- Limit: 20,
-})
-if err != nil {
- return err
-}
-for _, task := range tasks {
- fmt.Println(task)
-}
-```
-
-**Response Example**
-
-```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,
- "stage": null
- }
- ]
-}
-```
-
----
+<a id="get_task"></a><a id="list_tasks"></a>
## Session Properties
@@ -1529,27 +1447,7 @@ When long-term memory extraction runs successfully, the commit writes a `memory_
An empty `memory_diff.json` (all counts zero) is written when long-term memory extraction runs but produces no memory operations.
----
-
-## Built-in Memory Types
-
-| 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.
-
----
+<a id="built-in-memory-types"></a>
## Full Example
@@ -1670,5 +1568,7 @@ results = await client.search(query, session_id=session_id)
## Related Documentation
- [Context Types](../concepts/02-context-types.md) - Memory types
+- [Memory](16-memory.md) - memory types and type-quota recall
- [Retrieval](06-retrieval.md) - Search with session
- [Resources](02-resources.md) - Resource management
+- [Background Tasks](17-tasks.md) - track commit tasks
diff --git a/docs/en/api/07-system.md b/docs/en/api/07-system.md
index 581174033..754fd591a 100644
--- a/docs/en/api/07-system.md
+++ b/docs/en/api/07-system.md
@@ -1,6 +1,6 @@
-# System and Monitoring
+# System Status
-OpenViking provides system health, observability, and debug APIs for monitoring component status.
+The OpenViking System API provides health, readiness, consistency, and multi-write backend synchronization status. Component observers and Prometheus metrics are documented separately.
## API Reference
@@ -426,769 +426,105 @@ ov system wait --timeout 60
---
-### reindex()
+### backend_sync_status()
-Reindex semantic and/or vector artifacts for existing content already stored in OpenViking. This is an operational maintenance API intended for scenarios such as embedding model changes, VLM changes, vector store rebuild, or post-upgrade repair of existing indexes.
-
-This API operates on existing `viking://...` content. It does not import new files. For normal ingestion, use [Resources](02-resources.md).
-
-**Authentication**
-
-- HTTP endpoint: requires admin/root role when authentication is enabled. In `api_key` mode, use an admin key for tenant content; a raw root key cannot access tenant-scoped data.
-- Python embedded mode: uses the current service context
-- Python HTTP client / CLI: sends the current authenticated identity
-
-**Parameters**
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| uri | str | Yes | - | Viking URI to reindex |
-| mode | str | No | `vectors_only` | Reindex mode: `vectors_only`, `semantic_and_vectors`, or `prune_orphans` |
-| wait | bool | No | `true` | Whether to wait for completion |
-| dry_run | bool | No | `false` | Only valid with `mode="prune_orphans"`; report orphan vector records without deleting them |
-
-The HTTP request body rejects unknown fields. `uri` may use OpenViking path variables accepted by other content APIs; it is resolved before validation.
-
-**Supported URI scopes**
-
-- `viking://`
-- `viking://user`
-- `viking://user/<user_id>`
-- `viking://resources`
-- `viking://resources/...`
-- `viking://user/<user_id>/memories/...`
-- `viking://user/<user_id>/skills`
-- `viking://user/<user_id>/skills/<skill_name>`
-
-Session namespaces are not supported by `reindex()`. Requests for
-`viking://session/...` or `viking://user/<user_id>/sessions/...` are rejected;
-when reindexing a broader user namespace, session subtrees are skipped.
-
-**Modes**
-
-- `vectors_only`: rebuilds vector-store records from currently recoverable source data without rewriting `.abstract.md` or `.overview.md`
-- `semantic_and_vectors`: regenerates semantic artifacts first, then rebuilds vectors from the refreshed semantic outputs
-- `prune_orphans`: deletes vector-store records under the requested URI whose source files no longer exist in the filesystem. With `dry_run=true`, it only reports how many records would be deleted.
-
-For `resource` and `skill`, `semantic_and_vectors` refreshes directory/file semantic artifacts, including `.abstract.md` and `.overview.md`. For `memory`, it rebuilds the current persisted memory subtree semantics and vectors, but it does not replay historical extraction order.
-
-For `semantic_and_vectors`, semantic generation and vector rebuilding are sequenced by the reindex executor. The semantic refresh step does not enqueue its own background vectorization work; vectors are rebuilt by the reindex step so `wait=true` reflects the reindex operation itself.
-
-For `prune_orphans`, source existence is checked against the filesystem. If an entire directory is missing, vector records for files and semantic sidecars below that directory, such as `.abstract.md` and `.overview.md`, are pruned together. `dry_run` is rejected for other modes.
-
-**Python SDK (Embedded / HTTP)**
-
-```python
-result = client.reindex(
- uri="viking://resources",
- mode="vectors_only",
- wait=True,
-)
-print(result)
-```
-
-```python
-result = client.reindex(
- uri="viking://user/default/skills",
- mode="semantic_and_vectors",
- wait=False,
-)
-print(result["status"])
-```
-
-```python
-result = client.reindex(
- uri="viking://resources",
- mode="prune_orphans",
- dry_run=True,
-)
-print(result["would_delete_records"])
-```
-
-**TypeScript SDK**
-
-```typescript
-console.log(await client.reindex("viking://resources/docs/"));
-```
-
-**Go SDK**
-
-```go
-result, err := client.Reindex(ctx, "viking://resources", &openviking.ReindexOptions{
- Mode: "vectors_only",
- Wait: true,
-})
-if err != nil {
- return err
-}
-fmt.Println(result["status"])
-```
-
-```go
-result, err := client.Reindex(ctx, "viking://resources", &openviking.ReindexOptions{
- Mode: "prune_orphans",
- Wait: true,
- DryRun: true,
-})
-if err != nil {
- return err
-}
-fmt.Println(result["would_delete_records"])
-```
+Return multi-write backend synchronization status for a Viking URI subtree. This endpoint requires ROOT or ADMIN permission.
**HTTP API**
+```http
+POST /api/v1/system/backend/sync-status
+Content-Type: application/json
```
-POST /api/v1/content/reindex
-```
-
-There is no `/api/v1/maintenance/reindex` endpoint. Use `/api/v1/content/reindex`.
```bash
-curl -X POST http://localhost:1933/api/v1/content/reindex \
+curl -X POST http://localhost:1933/api/v1/system/backend/sync-status \
-H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -H "X-OpenViking-Account: default" \
- -d '{
- "uri": "viking://resources",
- "mode": "prune_orphans",
- "wait": true,
- "dry_run": true
- }'
-```
-
-**CLI**
-
-```bash
-openviking reindex viking://resources --mode vectors_only
-```
-
-```bash
-openviking reindex viking://user/default/skills --mode semantic_and_vectors --wait false
-```
-
-```bash
-openviking reindex viking://resources --mode prune_orphans --dry-run
-```
-
-**Synchronous response (`wait=true`)**
-
-```json
-{
- "status": "ok",
- "result": {
- "uri": "viking://resources",
- "mode": "vectors_only",
- "status": "completed",
- "object_type": "resource",
- "scanned_records": 120,
- "rebuilt_records": 118,
- "deleted_records": 0,
- "would_delete_records": 0,
- "unsupported_records": 2,
- "failed_records": 0,
- "duration_ms": 1284,
- "warnings": []
- },
- "time": 0.1
-}
-```
-
-**Asynchronous response (`wait=false`)**
-
-```json
-{
- "status": "ok",
- "result": {
- "uri": "viking://resources",
- "mode": "vectors_only",
- "object_type": "resource",
- "status": "accepted",
- "task_id": "task_xxx"
- },
- "time": 0.1
-}
-```
-
-Poll the returned task through the task API:
-
-```bash
-curl -X GET http://localhost:1933/api/v1/tasks/task_xxx \
- -H "X-API-Key: your-key" \
- -H "X-OpenViking-Account: default"
-```
-
-Reindex background tasks use `task_type="admin_reindex"` and `resource_id` equal to the requested `uri`, so they can also be listed with:
-
-```text
-GET /api/v1/tasks?task_type=admin_reindex&resource_id=viking://resources
-```
-
-Task records are persisted under `/local/{account_id}/_system/tasks/{user_id}/{task_id}.json` and can be queried after restart.
-
-**Result fields**
-
-| Field | Description |
-|-------|-------------|
-| status | `completed` for synchronous completion, `accepted` for background execution |
-| uri | Requested URI after path-variable resolution |
-| object_type | Inferred target type, such as `resource`, `skill`, `memory`, `user_namespace`, `skill_namespace`, or `global_namespace` |
-| mode | Effective reindex mode |
-| scanned_records | Number of records or semantic sources considered |
-| rebuilt_records | Number of vector records successfully rebuilt |
-| deleted_records | Number of vector records deleted by `prune_orphans`; `0` for `dry_run=true` |
-| would_delete_records | Number of vector records that would be deleted by `prune_orphans` in dry-run mode |
-| unsupported_records | Number of records skipped because no usable vector source was available |
-| failed_records | Number of records that failed while rebuilding |
-| duration_ms | Synchronous run duration in milliseconds |
-| warnings | Recoverable per-record warnings |
-| task_id | Background task ID, present only when `wait=false` |
-
-**Behavior notes**
-
-- `vectors_only` and `semantic_and_vectors` are non-destructive. They use rebuild/upsert behavior and do not require dropping the vector collection first.
-- `prune_orphans` is destructive unless `dry_run=true`: it removes vector records whose source files no longer exist.
-- `viking://` reindex fans out to supported top-level namespaces and excludes `session`.
-- Namespace reindex operations such as `viking://user` propagate to supported child content types.
-- `vectors_only` is the right mode when only the embedding model or vector index needs to be refreshed.
-- `semantic_and_vectors` is the right mode when semantic artifacts themselves must be regenerated before re-vectorization.
-- `prune_orphans` is the right mode when the filesystem has been changed outside normal APIs and the vector store may still contain records for deleted paths.
-- Only one reindex task can run for the same URI and owner at a time. A concurrent request for the same target returns a conflict.
-- For resource files, text files can use file content when no summary is available. Non-text files require a generated summary or existing vector record fallback; otherwise they are counted as unsupported.
-
-**Current limitations**
-
-- Reindex uses the best currently recoverable source inputs. It is not guaranteed to replay the exact historical embedding input byte-for-byte in every case.
-- Memory semantic reindex is based on the currently persisted memory tree. It does not reconstruct the original chronological memory-extraction pipeline.
-
----
-
-## Observer API
-
-The observer API provides detailed component-level monitoring.
-
-### observer.queue
-
-#### 1. API Implementation Overview
-
-Get queue system status (embedding and semantic processing queues). Shows pending, in-progress, completed, and error counts for each queue.
-
-**Code Entry Points**:
-- `openviking/server/routers/observer.py:observer_queue` - HTTP route
-- `openviking/service/debug_service.py:ObserverService.queue` - Core implementation
-- `openviking/storage/observers/queue_observer.py` - Queue observer
-
-#### 2. Interface and Parameters
-
-No parameters.
-
-#### 3. Usage Examples
-
-**HTTP API**
-
-```
-GET /api/v1/observer/queue
-```
-
-```bash
-curl -X GET http://localhost:1933/api/v1/observer/queue \
- -H "X-API-Key: your-key"
-```
-
-**Python SDK**
-
-```python
-print(client.observer.queue)
-# Output:
-# [queue] (healthy)
-# Queue Pending In Progress Processed Errors Total
-# Embedding 0 0 10 0 10
-# Semantic 0 0 10 0 10
-# TOTAL 0 0 20 0 20
-```
-
-**TypeScript SDK**
-
-```typescript
-console.log(await client.queueStatus());
-```
-
-**Go SDK**
-
-```go
-status, err := client.QueueStatus(ctx)
-if err != nil {
- return err
-}
-fmt.Println(status["is_healthy"])
-```
-
-**CLI**
-
-```bash
-ov observer queue
-```
-
-**Response Example**
-
-```json
-{
- "status": "ok",
- "result": {
- "name": "queue",
- "is_healthy": true,
- "has_errors": false,
- "status": "Queue Pending In Progress Processed Errors Total\nEmbedding 0 0 10 0 10\nSemantic 0 0 10 0 10\nTOTAL 0 0 20 0 20"
- },
- "time": 0.1
-}
-```
-
----
-
-### observer.vikingdb
-
-#### 1. API Implementation Overview
-
-Get VikingDB status (collections, indexes, vector counts).
-
-**Code Entry Points**:
-- `openviking/server/routers/observer.py:observer_vikingdb` - HTTP route
-- `openviking/service/debug_service.py:ObserverService.vikingdb` - Core implementation
-- `openviking/storage/observers/vikingdb_observer.py` - VikingDB observer
-- `crates/ov_cli/src/commands/observer.rs` - CLI command
-
-#### 2. Interface and Parameters
-
-No parameters.
-
-#### 3. Usage Examples
-
-**HTTP API**
-
-```
-GET /api/v1/observer/vikingdb
-```
-
-```bash
-curl -X GET http://localhost:1933/api/v1/observer/vikingdb \
- -H "X-API-Key: your-key"
-```
-
-**Python SDK**
-
-```python
-print(client.observer.vikingdb())
-# Output:
-# [vikingdb] (healthy)
-# Collection Index Count Vector Count Status
-# context 1 55 OK
-# TOTAL 1 55
-
-# Access specific attributes
-print(client.observer.vikingdb().is_healthy) # True
-print(client.observer.vikingdb().status) # Status table string
-```
-
-**TypeScript SDK**
-
-```typescript
-console.log(await client.vikingDBStatus());
-```
-
-**Go SDK**
-
-```go
-status, err := client.VikingDBStatus(ctx)
-if err != nil {
- return err
-}
-fmt.Println(status["is_healthy"])
-```
-
-**CLI**
-
-```bash
-ov observer vikingdb
-```
-
-**Response Example**
-
-```json
-{
- "status": "ok",
- "result": {
- "name": "vikingdb",
- "is_healthy": true,
- "has_errors": false,
- "status": "Collection Index Count Vector Count Status\ncontext 1 55 OK\nTOTAL 1 55"
- },
- "time": 0.1
-}
+ -H "X-API-Key: your-admin-key" \
+ -d '{"uri":"viking://resources"}'
```
----
-
-### observer.models
-
-#### 1. API Implementation Overview
-
-Get aggregated model subsystem status (VLM, embedding, rerank). Checks if each model provider is healthy and available.
-
-**Code Entry Points**:
-- `openviking/server/routers/observer.py:observer_models` - HTTP route
-- `openviking/service/debug_service.py:ObserverService.models` - Core implementation
-- `openviking/storage/observers/models_observer.py` - Models observer
-- `crates/ov_cli/src/commands/observer.rs` - CLI command
-
-#### 2. Interface and Parameters
-
-No parameters.
+The URI-path form is also available:
-#### 3. Usage Examples
-
-**HTTP API**
-
-```
-GET /api/v1/observer/models
-```
-
-```bash
-curl -X GET http://localhost:1933/api/v1/observer/models \
- -H "X-API-Key: your-key"
-```
-
-**Python SDK**
-
-```python
-print(client.observer.models)
-# Output:
-# [models] (healthy)
-# provider_model healthy detail
-# dense_embedding yes ...
-# rerank yes ...
-# vlm yes ...
-```
-
-**TypeScript SDK**
-
-```typescript
-console.log(await client.modelsStatus());
-```
-
-**Go SDK**
-
-```go
-status, err := client.ModelsStatus(ctx)
-if err != nil {
- return err
-}
-fmt.Println(status["is_healthy"])
+```http
+GET /api/v1/system/sync/{sync_path}
```
**CLI**
```bash
-ov observer models
-```
-
-**Response Example**
-
-```json
-{
- "status": "ok",
- "result": {
- "name": "models",
- "is_healthy": true,
- "has_errors": false,
- "status": "provider_model healthy detail\ndense_embedding yes ...\nrerank yes ...\nvlm yes ..."
- },
- "time": 0.1
-}
-```
-
----
-
-### observer.lock
-
-#### 1. API Implementation Overview
-
-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
-
-No parameters.
-
-#### 3. Usage Examples
-
-**HTTP API**
-
-```
-GET /api/v1/observer/lock
-```
-
-```bash
-curl -X GET http://localhost:1933/api/v1/observer/lock \
- -H "X-API-Key: your-key"
+ov system backend sync-status viking://resources
```
-**Python SDK**
-
-```python
-print(client.observer.lock)
-```
-
-The CLI does not currently expose a lock-specific observer subcommand. Use the HTTP API or Python SDK for this component; `ov observer system` includes it in the aggregate status.
-
-**Response Example**
+**Response example**
```json
{
"status": "ok",
"result": {
- "name": "lock",
- "is_healthy": true,
- "has_errors": false,
- "status": "..."
- },
- "time": 0.1
+ "path": "viking://resources",
+ "entry_count": 12
+ }
}
```
----
+`result` is supplied by the active filesystem backend. `path` identifies the queried scope and `entry_count` is the number of sync records in that scope. A backend may add diagnostics such as pending or failed records.
-### observer.retrieval
+### backend_sync_retry()
-#### 1. API Implementation Overview
-
-Get retrieval quality metrics.
-
-**Code Entry Points**:
-- `openviking/server/routers/observer.py:observer_retrieval` - HTTP route
-- `openviking/service/debug_service.py:ObserverService.retrieval` - Core implementation
-- `openviking/storage/observers/retrieval_observer.py` - Retrieval observer
-- `crates/ov_cli/src/commands/observer.rs` - CLI command
-
-#### 2. Interface and Parameters
-
-No parameters.
-
-#### 3. Usage Examples
+Retry incomplete multi-write backend synchronization work for a URI subtree. This endpoint requires ROOT or ADMIN permission.
**HTTP API**
-```
-GET /api/v1/observer/retrieval
+```http
+POST /api/v1/system/backend/sync-retry
+Content-Type: application/json
```
```bash
-curl -X GET http://localhost:1933/api/v1/observer/retrieval \
- -H "X-API-Key: your-key"
+curl -X POST http://localhost:1933/api/v1/system/backend/sync-retry \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-admin-key" \
+ -d '{"uri":"viking://resources"}'
```
-**Python SDK**
+The URI-path form is:
-```python
-print(client.observer.retrieval)
+```http
+POST /api/v1/system/sync/{sync_path}/retry
```
**CLI**
```bash
-ov observer retrieval
+ov system backend sync-retry viking://resources
```
-**Response Example**
+**Response example**
```json
{
"status": "ok",
"result": {
- "name": "retrieval",
- "is_healthy": true,
- "has_errors": false,
- "status": "..."
- },
- "time": 0.1
+ "path": "viking://resources",
+ "retried": 2,
+ "failed": 0
+ }
}
```
----
-
-### observer.filesystem
-
-#### 1. API Implementation Overview
-
-Get filesystem operation metrics.
-
-**Code Entry Points**:
-- `openviking/server/routers/observer.py:observer_filesystem` - HTTP route
-- `openviking/service/debug_service.py:ObserverService.filesystem` - Core implementation
-- `openviking/storage/observers/filesystem_observer.py` - Filesystem observer
-- `crates/ov_cli/src/commands/observer.rs` - CLI command
-
-#### 2. Interface and Parameters
+`retried` is the number of records rescheduled by this request, and `failed` is the number that could not be scheduled. A backend may include additional diagnostic fields.
-No parameters.
-
-#### 3. Usage Examples
-
-**HTTP API**
-
-```
-GET /api/v1/observer/filesystem
-```
-
-```bash
-curl -X GET http://localhost:1933/api/v1/observer/filesystem \
- -H "X-API-Key: your-key"
-```
-
-**Python SDK**
-
-```python
-print(client.observer.filesystem)
-```
-
-**CLI**
-
-```bash
-ov observer filesystem
-```
-
-**Response Example**
-
-```json
-{
- "status": "ok",
- "result": {
- "name": "filesystem",
- "is_healthy": true,
- "has_errors": false,
- "status": "..."
- },
- "time": 0.1
-}
-```
+The public Python, TypeScript, and Go SDKs do not currently expose multi-write backend synchronization methods, so the sections above show only HTTP and CLI tabs.
---
-### observer.system
-
-#### 1. API Implementation Overview
-
-Get overall system status, including all components (queue, vikingdb, models, lock, retrieval).
-
-**Code Entry Points**:
-- `openviking/server/routers/observer.py:observer_system` - HTTP route
-- `openviking/service/debug_service.py:ObserverService.system` - Core implementation
-- `crates/ov_cli/src/commands/observer.rs` - CLI command
-
-#### 2. Interface and Parameters
-
-No parameters.
-
-#### 3. Usage Examples
-
-**HTTP API**
-
-```
-GET /api/v1/observer/system
-```
-
-```bash
-curl -X GET http://localhost:1933/api/v1/observer/system \
- -H "X-API-Key: your-key"
-```
-
-**Python SDK**
-
-```python
-print(client.observer.system())
-# Output:
-# [queue] (healthy)
-# ...
-#
-# [vikingdb] (healthy)
-# ...
-#
-# [models] (healthy)
-# ...
-#
-# [system] (healthy)
-```
-
-**Go SDK**
-
-```go
-status, err := client.GetStatus(ctx)
-if err != nil {
- return err
-}
-fmt.Println(status["is_healthy"])
-```
-
-**CLI**
-
-```bash
-ov observer system
-```
-
-**Response Example**
-
-```json
-{
- "status": "ok",
- "result": {
- "is_healthy": true,
- "errors": [],
- "components": {
- "queue": {
- "name": "queue",
- "is_healthy": true,
- "has_errors": false,
- "status": "..."
- },
- "vikingdb": {
- "name": "vikingdb",
- "is_healthy": true,
- "has_errors": false,
- "status": "..."
- },
- "models": {
- "name": "models",
- "is_healthy": true,
- "has_errors": false,
- "status": "..."
- },
- "lock": {
- "name": "lock",
- "is_healthy": true,
- "has_errors": false,
- "status": "..."
- },
- "retrieval": {
- "name": "retrieval",
- "is_healthy": true,
- "has_errors": false,
- "status": "..."
- }
- }
- },
- "time": 0.1
-}
-```
-
----
+<a id="reindex"></a><a id="observer-api"></a>
## Related Documentation
- [Resources](02-resources.md) - Resource management
- [Retrieval](06-retrieval.md) - Search and retrieval
- [Sessions](05-sessions.md) - Session management
+- [Runtime Observability](18-observer.md) - immediate component status
+- [Metrics](09-metrics.md) - Prometheus metrics
diff --git a/docs/en/api/08-admin.md b/docs/en/api/08-admin.md
index 021f2c17d..c81133415 100644
--- a/docs/en/api/08-admin.md
+++ b/docs/en/api/08-admin.md
@@ -1052,49 +1052,7 @@ ov --sudo admin migrate --cleanup --output json
---
-### user add-location settings
-
-Per-user add defaults are stored as user config under
-`viking://user/{user_id}/settings/user_config.json`. They affect add calls that
-omit explicit targets:
-
-1. `add_resource`: explicit `to` / `parent` wins, then user
- `add_targets.resource_uri`, then
- `server.user_config_defaults.add_targets.resource_uri`, then legacy behavior.
-2. `add_skill`: explicit `target_uri` wins, then user
- `add_targets.skill_uri`, then
- `server.user_config_defaults.add_targets.skill_uri`, then legacy behavior.
-
-#### HTTP API
-
-```
-GET /api/v1/user-settings/add-locations
-PATCH /api/v1/user-settings/add-locations
-DELETE /api/v1/user-settings/add-locations
-```
-
-`PATCH` accepts the add-target fields directly. Passing `null` clears one field;
-deleting the settings clears the whole per-user override.
-
-```bash
-curl -X PATCH http://localhost:1933/api/v1/user-settings/add-locations \
- -H "Content-Type: application/json" \
- -H "X-API-Key: <user-key>" \
- -d '{"resource_uri": "viking://user/resources/project-a"}'
-```
-
-`resource_uri` must be a writable resource directory URI:
-`viking://resources` or `viking://resources/...`,
-`viking://user/resources` or `viking://user/resources/...`,
-`viking://user/{user_id}/resources` or
-`viking://user/{user_id}/resources/...`, or
-`viking://user/{user_id}/peers/{peer_id}/resources` or
-`viking://user/{user_id}/peers/{peer_id}/resources/...`. `skill_uri` must be
-`viking://user/skills` or `viking://agent/skills`; explicit
-`viking://user/{user_id}/skills` is not accepted in v1. Invalid configured
-values are rejected; OpenViking does not silently fall back to another target.
-
----
+<a id="user-add-location-settings"></a>
## Full Example
diff --git a/docs/en/api/09-metrics.md b/docs/en/api/09-metrics.md
index 19c8736f0..335c4d294 100644
--- a/docs/en/api/09-metrics.md
+++ b/docs/en/api/09-metrics.md
@@ -2,7 +2,7 @@
OpenViking exposes a `/metrics` endpoint for Prometheus, Grafana Agent, and other monitoring systems that scrape Prometheus exposition text.
-Unlike `/api/v1/observer/*` and `/api/v1/stats/*`, `/metrics` is intended for:
+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
@@ -78,7 +78,6 @@ If your deployment protects `/metrics` at the gateway layer, configure the scrap
- `/metrics` is meant for frequent scraping, so the exported metrics should remain low-cardinality and low-cost.
- `/metrics` returns Prometheus text, not the standard OpenViking `{status, result, time}` JSON response format.
-- Analytics-oriented statistics such as memory health, staleness, or session extraction should remain under `/api/v1/stats/*`, not `/metrics`.
- For human-readable component snapshots, prefer `/api/v1/observer/*`.
- `/metrics` also includes VikingBot feedback observability metrics derived from scrape-time aggregation of persisted session data; see the Metrics concept documentation for the feedback metric families and examples.
diff --git a/docs/en/api/11-snapshot.md b/docs/en/api/11-snapshot.md
index 3b98f6b26..332092cfa 100644
--- a/docs/en/api/11-snapshot.md
+++ b/docs/en/api/11-snapshot.md
@@ -347,7 +347,22 @@ ov snapshot diff viking://resources/my_project/guide.md \
--to 9a0b1c2d
```
-The response contains `path`, resolved `from_commit` and `to_commit`, `change_type` (`added`, `deleted`, `modified`, or `unchanged`), and `diff_text`. Each side is limited to 10 MiB and 100,000 lines, and the generated diff is limited to 20 MiB; larger requests return `RESOURCE_EXHAUSTED` rather than a truncated diff.
+**Response**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "path": "viking://resources/my_project/guide.md",
+ "from_commit": "3f2a1b9c...",
+ "to_commit": "9a0b1c2d...",
+ "change_type": "modified",
+ "diff_text": "--- a/guide.md\n+++ b/guide.md\n@@ -1 +1 @@\n-old line\n+new line\n"
+ }
+}
+```
+
+`change_type` is `added`, `deleted`, `modified`, or `unchanged`. Each side is limited to 10 MiB and 100,000 lines, and the generated diff is limited to 20 MiB; larger requests return `RESOURCE_EXHAUSTED` rather than a truncated diff.
---
diff --git a/docs/en/api/12-content.md b/docs/en/api/12-content.md
new file mode 100644
index 000000000..fbaf20dad
--- /dev/null
+++ b/docs/en/api/12-content.md
@@ -0,0 +1,702 @@
+# Content
+
+The Content API reads L0/L1/L2 content, writes text, and maintains semantic and vector indexes for stored content.
+
+## API Reference
+
+### abstract()
+
+Read L0 abstract (~100 tokens summary).
+
+**Parameters**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| uri | str | Yes | - | Viking URI (must be a directory) |
+
+
+**Python SDK**
+
+```python
+abstract = client.abstract("viking://resources/docs/")
+print(f"Abstract: {abstract}")
+# Output: "Documentation for the project API, covering authentication, endpoints..."
+```
+
+**TypeScript SDK**
+
+```typescript
+const abstract = await client.abstract("viking://resources/docs/");
+console.log(abstract);
+```
+
+**Go SDK**
+
+```go
+abstract, err := client.Abstract(ctx, "viking://resources/docs/")
+if err != nil {
+ return err
+}
+fmt.Println(abstract)
+```
+
+**HTTP API**
+
+```
+GET /api/v1/content/abstract?uri={uri}
+```
+
+```bash
+curl -X GET "http://localhost:1933/api/v1/content/abstract?uri=viking://resources/docs/" \
+ -H "X-API-Key: your-key"
+```
+
+**CLI**
+
+```bash
+openviking abstract viking://resources/docs/
+```
+
+
+**Response**
+
+```json
+{
+ "status": "ok",
+ "result": "Documentation for the project API, covering authentication, endpoints...",
+ "time": 0.1
+}
+```
+
+---
+
+### overview()
+
+Read L1 overview, applies to directories.
+
+**Parameters**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| uri | str | Yes | - | Viking URI (must be a directory) |
+
+
+**Python SDK**
+
+```python
+overview = client.overview("viking://resources/docs/")
+print(f"Overview:\n{overview}")
+```
+
+**TypeScript SDK**
+
+```typescript
+const overview = await client.overview("viking://resources/docs/");
+console.log(overview);
+```
+
+**Go SDK**
+
+```go
+overview, err := client.Overview(ctx, "viking://resources/docs/")
+if err != nil {
+ return err
+}
+fmt.Println(overview)
+```
+
+**HTTP API**
+
+```
+GET /api/v1/content/overview?uri={uri}
+```
+
+```bash
+curl -X GET "http://localhost:1933/api/v1/content/overview?uri=viking://resources/docs/" \
+ -H "X-API-Key: your-key"
+```
+
+**CLI**
+
+```bash
+openviking overview viking://resources/docs/
+```
+
+
+**Response**
+
+```json
+{
+ "status": "ok",
+ "result": "## docs/\n\nContains API documentation and guides...",
+ "time": 0.1
+}
+```
+
+---
+
+### read()
+
+Read L2 full content.
+
+**Parameters**
+
+| 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 |
+| raw | bool | No | false | Return raw stored content without memory-field cleanup. HTTP API only (Python SDK does not expose it yet). |
+
+**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.
+- 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`.
+
+
+**Python SDK**
+
+```python
+content = client.read("viking://resources/docs/api.md")
+print(f"Content:\n{content}")
+```
+
+**TypeScript SDK**
+
+```typescript
+const content = await client.read("viking://resources/docs/api.md", 0, -1);
+console.log(content);
+```
+
+**Go SDK**
+
+```go
+content, err := client.Read(ctx, "viking://resources/docs/api.md", 0, -1)
+if err != nil {
+ return err
+}
+fmt.Println(content)
+```
+
+**HTTP API**
+
+```
+GET /api/v1/content/read?uri={uri}
+```
+
+```bash
+curl -X GET "http://localhost:1933/api/v1/content/read?uri=viking://resources/docs/api.md" \
+ -H "X-API-Key: your-key"
+```
+
+**CLI**
+
+```bash
+openviking read viking://resources/docs/api.md
+```
+
+
+**Response**
+
+```json
+{
+ "status": "ok",
+ "result": "# API Documentation\n\nFull content of the file...",
+ "time": 0.1
+}
+```
+
+---
+
+### write()
+
+Update an existing file, or create a new one when `mode="create"`, and automatically refresh related semantics and vectors.
+
+**Parameters**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| uri | str | Yes | - | File URI to write. For `mode="create"`, the file must not already exist |
+| content | str | Yes | - | New content to write |
+| mode | str | No | `replace` | `replace`, `append`, or `create` |
+| wait | bool | No | `false` | Wait for background semantic/vector refresh |
+| timeout | float | No | `null` | Timeout in seconds when `wait=true` |
+
+**Notes**
+
+- `replace` and `append` require the file to exist; `create` targets a new file and returns `409 Conflict` when the path already exists. Directories are always rejected.
+- `create` only accepts text-writable extensions: `.md`, `.txt`, `.json`, `.yaml`, `.yml`, `.toml`, `.py`, `.js`, `.ts`. Parent directories are created automatically.
+- Derived semantic files cannot be written directly: `.abstract.md`, `.overview.md`, `.relations.json`.
+- File content is updated before the API returns. `wait` only controls whether the call waits for semantic/vector refresh to finish.
+- The public API no longer accepts `regenerate_semantics` or `revectorize`; write always refreshes related semantics and vectors.
+
+
+**Python SDK**
+
+```python
+result = client.write(
+ "viking://resources/docs/api.md",
+ "# Updated API\n\nFresh content.",
+ mode="replace",
+ wait=True,
+)
+print(result["root_uri"])
+```
+
+**TypeScript SDK**
+
+```typescript
+await client.write("viking://resources/docs/new.md", "# New document\n", { wait: true });
+```
+
+**Go SDK**
+
+```go
+result, err := client.Write(
+ ctx,
+ "viking://resources/docs/api.md",
+ "# Updated API\n\nFresh content.",
+ &openviking.WriteOptions{
+ Mode: "replace",
+ Wait: true,
+ },
+)
+if err != nil {
+ return err
+}
+fmt.Println(result["root_uri"])
+```
+
+**HTTP API**
+
+```
+POST /api/v1/content/write
+```
+
+```bash
+curl -X POST "http://localhost:1933/api/v1/content/write" \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "uri": "viking://resources/docs/api.md",
+ "content": "# Updated API\n\nFresh content.",
+ "mode": "replace",
+ "wait": true
+ }'
+```
+
+**CLI**
+
+```bash
+openviking write viking://resources/docs/api.md \
+ --content "# Updated API\n\nFresh content." \
+ --wait
+```
+
+
+**Response**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "uri": "viking://resources/docs/api.md",
+ "root_uri": "viking://resources/docs",
+ "context_type": "resource",
+ "mode": "replace",
+ "written_bytes": 29,
+ "content_updated": true,
+ "semantic_status": "complete",
+ "vector_status": "complete",
+ "queue_status": {
+ "Semantic": {
+ "processed": 1,
+ "error_count": 0,
+ "errors": []
+ },
+ "Embedding": {
+ "processed": 2,
+ "error_count": 0,
+ "errors": []
+ }
+ }
+ }
+}
+```
+
+---
+
+### download()
+
+Download a file as raw bytes. This is intended for images, PDFs, and other non-text content. The response uses `application/octet-stream` and returns the filename through `Content-Disposition`.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `uri` | string | Yes | File URI to download |
+
+**HTTP API**
+
+```http
+GET /api/v1/content/download?uri={uri}
+```
+
+```bash
+curl --get http://localhost:1933/api/v1/content/download \
+ -H "X-API-Key: your-key" \
+ --data-urlencode "uri=viking://resources/images/logo.png" \
+ --output logo.png
+```
+
+**Response**
+
+On success, the endpoint returns HTTP `200` with the raw file bytes instead of the standard JSON envelope:
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/octet-stream
+Content-Disposition: attachment; filename*=UTF-8''logo.png
+
+<binary body>
+```
+
+The public SDKs and CLI do not currently expose a dedicated raw-byte download method, so this section shows only the HTTP tab.
+
+---
+
+### set_tags()
+
+Set explicit `k=v` tags used by retrieval filters. `replace` replaces existing tags, while `append` adds tags. When the target is a directory, `recursive=true` applies the update to files below it.
+
+**Python SDK**
+
+```python
+result = client.set_tags(
+ "viking://resources/project/",
+ ["team=search", "env=prod"],
+ mode="replace",
+ recursive=True,
+)
+```
+
+**TypeScript SDK**
+
+```typescript
+const result = await client.setTags(
+ "viking://resources/project/",
+ ["team=search", "env=prod"],
+ { mode: "replace", recursive: true },
+);
+```
+
+**Go SDK**
+
+```go
+result, err := client.SetTags(
+ ctx,
+ "viking://resources/project/",
+ []string{"team=search", "env=prod"},
+ &openviking.SetTagsOptions{Mode: "replace", Recursive: true},
+)
+```
+
+**HTTP API**
+
+```http
+POST /api/v1/content/set_tags
+Content-Type: application/json
+```
+
+```bash
+curl -X POST http://localhost:1933/api/v1/content/set_tags \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "uri":"viking://resources/project/",
+ "tags":["team=search","env=prod"],
+ "mode":"replace",
+ "recursive":true
+ }'
+```
+
+`POST /api/v1/fs/attrs/set_tags` is an equivalent compatibility path currently used by the Python, TypeScript, and Go SDKs and the CLI.
+
+**CLI**
+
+```bash
+ov set-tags viking://resources/project/ \
+ --tags team=search,env=prod \
+ --mode replace \
+ --recursive
+```
+
+**Response**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "uri": "viking://resources/project/",
+ "updated_uris": [
+ "viking://resources/project/guide.md"
+ ],
+ "root_uri": "viking://resources/project/",
+ "context_type": "resource",
+ "tags": [
+ "team=search",
+ "env=prod"
+ ],
+ "mode": "replace",
+ "success_count": 1,
+ "skipped_count": 0,
+ "failed_count": 0,
+ "tags_updated": true
+ }
+}
+```
+
+`updated_uris` contains the semantic record URIs actually updated. For recursive directory updates, `success_count`, `skipped_count`, and `failed_count` summarize all targets.
+
+---
+
+### reindex()
+
+Reindex semantic and/or vector artifacts for existing content already stored in OpenViking. This is an operational maintenance API intended for scenarios such as embedding model changes, VLM changes, vector store rebuild, or post-upgrade repair of existing indexes.
+
+This API operates on existing `viking://...` content. It does not import new files. For normal ingestion, use [Resources](02-resources.md).
+
+**Authentication**
+
+- HTTP endpoint: requires admin/root role when authentication is enabled. In `api_key` mode, use an admin key for tenant content; a raw root key cannot access tenant-scoped data.
+- Python embedded mode: uses the current service context
+- Python HTTP client / CLI: sends the current authenticated identity
+
+**Parameters**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| uri | str | Yes | - | Viking URI to reindex |
+| mode | str | No | `vectors_only` | Reindex mode: `vectors_only`, `semantic_and_vectors`, or `prune_orphans` |
+| wait | bool | No | `true` | Whether to wait for completion |
+| dry_run | bool | No | `false` | Only valid with `mode="prune_orphans"`; report orphan vector records without deleting them |
+
+The HTTP request body rejects unknown fields. `uri` may use OpenViking path variables accepted by other content APIs; it is resolved before validation.
+
+**Supported URI scopes**
+
+- `viking://`
+- `viking://user`
+- `viking://user/<user_id>`
+- `viking://resources`
+- `viking://resources/...`
+- `viking://user/<user_id>/memories/...`
+- `viking://user/<user_id>/skills`
+- `viking://user/<user_id>/skills/<skill_name>`
+
+Session namespaces are not supported by `reindex()`. Requests for
+`viking://session/...` or `viking://user/<user_id>/sessions/...` are rejected;
+when reindexing a broader user namespace, session subtrees are skipped.
+
+**Modes**
+
+- `vectors_only`: rebuilds vector-store records from currently recoverable source data without rewriting `.abstract.md` or `.overview.md`
+- `semantic_and_vectors`: regenerates semantic artifacts first, then rebuilds vectors from the refreshed semantic outputs
+- `prune_orphans`: deletes vector-store records under the requested URI whose source files no longer exist in the filesystem. With `dry_run=true`, it only reports how many records would be deleted.
+
+For `resource` and `skill`, `semantic_and_vectors` refreshes directory/file semantic artifacts, including `.abstract.md` and `.overview.md`. For `memory`, it rebuilds the current persisted memory subtree semantics and vectors, but it does not replay historical extraction order.
+
+For `semantic_and_vectors`, semantic generation and vector rebuilding are sequenced by the reindex executor. The semantic refresh step does not enqueue its own background vectorization work; vectors are rebuilt by the reindex step so `wait=true` reflects the reindex operation itself.
+
+For `prune_orphans`, source existence is checked against the filesystem. If an entire directory is missing, vector records for files and semantic sidecars below that directory, such as `.abstract.md` and `.overview.md`, are pruned together. `dry_run` is rejected for other modes.
+
+**Python SDK**
+
+```python
+result = client.reindex(
+ uri="viking://resources",
+ mode="vectors_only",
+ wait=True,
+)
+print(result)
+```
+
+```python
+result = client.reindex(
+ uri="viking://user/default/skills",
+ mode="semantic_and_vectors",
+ wait=False,
+)
+print(result["status"])
+```
+
+```python
+result = client.reindex(
+ uri="viking://resources",
+ mode="prune_orphans",
+ dry_run=True,
+)
+print(result["would_delete_records"])
+```
+
+**TypeScript SDK**
+
+```typescript
+console.log(await client.reindex("viking://resources/docs/"));
+```
+
+**Go SDK**
+
+```go
+result, err := client.Reindex(ctx, "viking://resources", &openviking.ReindexOptions{
+ Mode: "vectors_only",
+ Wait: true,
+})
+if err != nil {
+ return err
+}
+fmt.Println(result["status"])
+```
+
+```go
+result, err := client.Reindex(ctx, "viking://resources", &openviking.ReindexOptions{
+ Mode: "prune_orphans",
+ Wait: true,
+ DryRun: true,
+})
+if err != nil {
+ return err
+}
+fmt.Println(result["would_delete_records"])
+```
+
+**HTTP API**
+
+```
+POST /api/v1/content/reindex
+```
+
+There is no `/api/v1/maintenance/reindex` endpoint. Use `/api/v1/content/reindex`.
+
+```bash
+curl -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" \
+ -d '{
+ "uri": "viking://resources",
+ "mode": "prune_orphans",
+ "wait": true,
+ "dry_run": true
+ }'
+```
+
+**CLI**
+
+```bash
+openviking reindex viking://resources --mode vectors_only
+```
+
+```bash
+openviking reindex viking://user/default/skills --mode semantic_and_vectors --wait false
+```
+
+```bash
+openviking reindex viking://resources --mode prune_orphans --dry-run
+```
+
+**Synchronous response (`wait=true`)**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "uri": "viking://resources",
+ "mode": "vectors_only",
+ "status": "completed",
+ "object_type": "resource",
+ "scanned_records": 120,
+ "rebuilt_records": 118,
+ "deleted_records": 0,
+ "would_delete_records": 0,
+ "unsupported_records": 2,
+ "failed_records": 0,
+ "duration_ms": 1284,
+ "warnings": []
+ },
+ "time": 0.1
+}
+```
+
+**Asynchronous response (`wait=false`)**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "uri": "viking://resources",
+ "mode": "vectors_only",
+ "object_type": "resource",
+ "status": "accepted",
+ "task_id": "task_xxx"
+ },
+ "time": 0.1
+}
+```
+
+Poll the returned task through the task API:
+
+```bash
+curl -X GET http://localhost:1933/api/v1/tasks/task_xxx \
+ -H "X-API-Key: your-key" \
+ -H "X-OpenViking-Account: default"
+```
+
+Reindex background tasks use `task_type="admin_reindex"` and `resource_id` equal to the requested `uri`, so they can also be listed with:
+
+```text
+GET /api/v1/tasks?task_type=admin_reindex&resource_id=viking://resources
+```
+
+Task records are persisted under `/local/{account_id}/_system/tasks/{user_id}/{task_id}.json` and can be queried after restart.
+
+**Result fields**
+
+| Field | Description |
+|-------|-------------|
+| status | `completed` for synchronous completion, `accepted` for background execution |
+| uri | Requested URI after path-variable resolution |
+| object_type | Inferred target type, such as `resource`, `skill`, `memory`, `user_namespace`, `skill_namespace`, or `global_namespace` |
+| mode | Effective reindex mode |
+| scanned_records | Number of records or semantic sources considered |
+| rebuilt_records | Number of vector records successfully rebuilt |
+| deleted_records | Number of vector records deleted by `prune_orphans`; `0` for `dry_run=true` |
+| would_delete_records | Number of vector records that would be deleted by `prune_orphans` in dry-run mode |
+| unsupported_records | Number of records skipped because no usable vector source was available |
+| failed_records | Number of records that failed while rebuilding |
+| duration_ms | Synchronous run duration in milliseconds |
+| warnings | Recoverable per-record warnings |
+| task_id | Background task ID, present only when `wait=false` |
+
+**Behavior notes**
+
+- `vectors_only` and `semantic_and_vectors` are non-destructive. They use rebuild/upsert behavior and do not require dropping the vector collection first.
+- `prune_orphans` is destructive unless `dry_run=true`: it removes vector records whose source files no longer exist.
+- `viking://` reindex fans out to supported top-level namespaces and excludes `session`.
+- Namespace reindex operations such as `viking://user` propagate to supported child content types.
+- `vectors_only` is the right mode when only the embedding model or vector index needs to be refreshed.
+- `semantic_and_vectors` is the right mode when semantic artifacts themselves must be regenerated before re-vectorization.
+- `prune_orphans` is the right mode when the filesystem has been changed outside normal APIs and the vector store may still contain records for deleted paths.
+- Only one reindex task can run for the same URI and owner at a time. A concurrent request for the same target returns a conflict.
+- For resource files, text files can use file content when no summary is available. Non-text files require a generated summary or existing vector record fallback; otherwise they are counted as unsupported.
+
+**Current limitations**
+
+- Reindex uses the best currently recoverable source inputs. It is not guaranteed to replay the exact historical embedding input byte-for-byte in every case.
+- Memory semantic reindex is based on the currently persisted memory tree. It does not reconstruct the original chronological memory-extraction pipeline.
+
+---
+
+## Related Documentation
+
+- [File System](03-filesystem.md) - directory and file operations
+- [Retrieval](06-retrieval.md) - semantic and pattern search
+- [Background Tasks](17-tasks.md) - track asynchronous reindex tasks
diff --git a/docs/en/api/13-relations.md b/docs/en/api/13-relations.md
new file mode 100644
index 000000000..41a961313
--- /dev/null
+++ b/docs/en/api/13-relations.md
@@ -0,0 +1,282 @@
+# Relations
+
+The Relations API creates, reads, and removes explicit links between Viking URIs.
+
+## API Reference
+
+### link()
+
+Create relations between resources.
+
+**Parameters**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| from_uri | str | Yes | - | Source URI |
+| to_uris | str or List[str] | Yes | - | Target URI(s) |
+| reason | str | No | "" | Reason for the link |
+
+
+**Python SDK**
+
+```python
+# Single link
+client.link(
+ "viking://resources/docs/auth/",
+ "viking://resources/docs/security/",
+ reason="Security best practices for authentication"
+)
+
+# Multiple links
+client.link(
+ "viking://resources/docs/api/",
+ [
+ "viking://resources/docs/auth/",
+ "viking://resources/docs/errors/"
+ ],
+ reason="Related documentation"
+)
+```
+
+**TypeScript SDK**
+
+```typescript
+await client.link(
+ "viking://resources/docs/api/",
+ [
+ "viking://resources/docs/auth/",
+ "viking://resources/docs/errors/",
+ ],
+ "Related documentation",
+);
+```
+
+**HTTP API**
+
+```
+POST /api/v1/relations/link
+```
+
+```bash
+# Single link
+curl -X POST http://localhost:1933/api/v1/relations/link \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "from_uri": "viking://resources/docs/auth/",
+ "to_uris": "viking://resources/docs/security/",
+ "reason": "Security best practices for authentication"
+ }'
+
+# Multiple links
+curl -X POST http://localhost:1933/api/v1/relations/link \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "from_uri": "viking://resources/docs/api/",
+ "to_uris": ["viking://resources/docs/auth/", "viking://resources/docs/errors/"],
+ "reason": "Related documentation"
+ }'
+```
+
+**CLI**
+
+```bash
+openviking link viking://resources/docs/auth/ viking://resources/docs/security/ --reason "Security best practices"
+```
+
+
+**Response**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "from": "viking://resources/docs/auth/",
+ "to": "viking://resources/docs/security/"
+ },
+ "time": 0.1
+}
+```
+
+---
+
+### relations()
+
+Get relations for a resource.
+
+**Parameters**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| uri | str | Yes | - | Viking URI |
+
+
+**Python SDK**
+
+```python
+relations = client.relations("viking://resources/docs/auth/")
+for rel in relations:
+ print(f"Related: {rel['uri']}")
+ print(f" Reason: {rel['reason']}")
+```
+
+**TypeScript SDK**
+
+```typescript
+const relations = await client.relations("viking://resources/docs/auth/");
+console.log(relations);
+```
+
+**HTTP API**
+
+```
+GET /api/v1/relations?uri={uri}
+```
+
+```bash
+curl -X GET "http://localhost:1933/api/v1/relations?uri=viking://resources/docs/auth/" \
+ -H "X-API-Key: your-key"
+```
+
+**CLI**
+
+```bash
+openviking relations viking://resources/docs/auth/
+```
+
+
+**Response**
+
+```json
+{
+ "status": "ok",
+ "result": [
+ {"uri": "viking://resources/docs/security/", "reason": "Security best practices"},
+ {"uri": "viking://resources/docs/errors/", "reason": "Error handling"}
+ ],
+ "time": 0.1
+}
+```
+
+---
+
+### unlink()
+
+Remove a relation.
+
+**Parameters**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| from_uri | str | Yes | - | Source URI |
+| to_uri | str | Yes | - | Target URI to unlink |
+
+
+**Python SDK**
+
+```python
+client.unlink(
+ "viking://resources/docs/auth/",
+ "viking://resources/docs/security/"
+)
+```
+
+**TypeScript SDK**
+
+```typescript
+await client.unlink(
+ "viking://resources/docs/auth/",
+ "viking://resources/docs/security/",
+);
+```
+
+**HTTP API**
+
+```
+DELETE /api/v1/relations/link
+```
+
+```bash
+curl -X DELETE http://localhost:1933/api/v1/relations/link \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "from_uri": "viking://resources/docs/auth/",
+ "to_uri": "viking://resources/docs/security/"
+ }'
+```
+
+**CLI**
+
+```bash
+openviking unlink viking://resources/docs/auth/ viking://resources/docs/security/
+```
+
+
+**Response**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "from": "viking://resources/docs/auth/",
+ "to": "viking://resources/docs/security/"
+ },
+ "time": 0.1
+}
+```
+
+---
+
+### build_graph()
+
+Generate a self-contained HTML relation graph from multiple memory roots and write it to a Viking URI.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `space_uris` | string[] | Yes | Memory roots to merge |
+| `output_uri` | string | Yes | Viking URI of the output HTML file |
+
+**HTTP API**
+
+```http
+POST /api/v1/relations/build_graph
+Content-Type: application/json
+```
+
+```bash
+curl -X POST http://localhost:1933/api/v1/relations/build_graph \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "space_uris":[
+ "viking://user/default/memories",
+ "viking://user/default/peers/project-a/memories"
+ ],
+ "output_uri":"viking://user/default/memories/.graph.html"
+ }'
+```
+
+**Response**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "graph_uri": "viking://user/default/memories/.graph.html"
+ }
+}
+```
+
+`graph_uri` is the URI of the generated self-contained HTML file. Read it through the content or filesystem API.
+
+This endpoint does not currently have a public SDK or CLI wrapper, so this section shows only the HTTP tab.
+
+---
+
+## Related Documentation
+
+- [Retrieval](06-retrieval.md) - retrieve and use related content
+- [File System](03-filesystem.md) - manage relation targets
+- [Memory](16-memory.md) - memory namespaces and types
diff --git a/docs/en/api/14-ovpack.md b/docs/en/api/14-ovpack.md
new file mode 100644
index 000000000..5f0eb61a7
--- /dev/null
+++ b/docs/en/api/14-ovpack.md
@@ -0,0 +1,423 @@
+# OVPack
+
+The OVPack API imports, exports, backs up, and restores OpenViking data.
+
+## API Reference
+
+### export_ovpack
+
+Export a resource tree as a `.ovpack` file.
+
+#### 1. API Implementation Overview
+
+Packages all resources under the specified URI into a `.ovpack` file for backup or migration. Available to ROOT, ADMIN, and USER roles; normal URI access controls still apply.
+
+**Processing Flow**:
+1. Verify user permissions
+2. Traverse resources under the specified URI
+3. Write content files and the OVPack manifest
+4. Package into zip format (`.ovpack`)
+5. Return as file stream
+
+**Format Notes**:
+- The exported ZIP stores user content unchanged under `<root>/files/` and internal metadata under `<root>/_ovpack/`.
+- The manifest is stored at `<root>/_ovpack/manifest.json`.
+- `entries[].path` is relative to the exported root; `""` means the root directory itself.
+- File entries include `size` and `sha256`; `content_sha256` covers the sorted file list of `path`, `size`, and `sha256`.
+- `_ovpack/index_records.jsonl` stores portable index scalar fields. With `include_vectors=true`, `_ovpack/dense.f32` stores a pure-dense float32 vector snapshot plus embedding metadata; vector indexes whose `VectorIndex.IndexType` is hybrid do not support vector snapshot export.
+- Runtime fields such as `id`, `uri`, `account_id`, `created_at`, `updated_at`, and `active_count` are regenerated in the target environment and are not restored from the package.
+- OVPack does not add package-size, file-count, or directory-depth limits; the practical limit comes from ZIP, the storage backend, and the runtime environment.
+
+**Code Entry Points**:
+- `openviking/server/routers/pack.py:export_ovpack` - HTTP router
+- `openviking/service/pack_service.py` - Core service implementation
+- `crates/ov_cli/src/handlers.rs:handle_export` - CLI handler
+
+#### 2. Interface and Parameter Description
+
+**Parameters**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| uri | string | Yes | - | Viking URI to export |
+| include_vectors | boolean | No | false | Include a pure-dense vector snapshot; hybrid index types are rejected |
+
+**Permission Requirements**: ROOT, ADMIN, or USER
+
+#### 3. Usage Examples
+
+
+**HTTP API**
+
+```
+POST /api/v1/pack/export
+Content-Type: application/json
+```
+
+```bash
+curl -X POST http://localhost:1933/api/v1/pack/export \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-admin-key" \
+ -d '{
+ "uri": "viking://resources/my-project/",
+ "include_vectors": false
+ }' \
+ --output my-project.ovpack
+```
+
+**Python SDK**
+
+```python
+import openviking as ov
+
+client = 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
+```
+
+**TypeScript SDK**
+
+```typescript
+const outputPath = await client.exportOVPack(
+ "viking://resources/docs/",
+ "./exports/docs.ovpack",
+ true,
+);
+console.log(outputPath);
+```
+
+**Go SDK**
+
+```go
+outPath, err := client.ExportOVPack(
+ ctx,
+ "viking://resources/my-project/",
+ "./exports/my-project.ovpack",
+ &openviking.PackOptions{IncludeVectors: false},
+)
+if err != nil {
+ return err
+}
+fmt.Println(outPath)
+```
+
+**CLI**
+
+```bash
+# Export resource
+ov export viking://resources/my-project/ ./exports/my-project.ovpack
+
+# Export with a dense vector snapshot
+ov export viking://resources/my-project/ ./exports/my-project.ovpack --include-vectors
+```
+
+
+**Response Example**
+
+This endpoint directly returns a file stream (`Content-Type: application/zip`), does not return a JSON envelope.
+
+---
+
+### import_ovpack
+
+Import a `.ovpack` file.
+
+#### 1. API Implementation Overview
+
+Imports a `.ovpack` file to a specified location for restoring or migrating data. Available to ROOT, ADMIN, and USER roles; normal URI access controls still apply.
+
+**Processing Flow**:
+1. Verify user permissions
+2. Parse uploaded `.ovpack` file
+3. Validate manifest metadata, paths, file and directory sets, file sizes, and checksums
+4. Apply `on_conflict`
+5. Import resources to target location and rebuild vectors
+
+**Code Entry Points**:
+- `openviking/server/routers/pack.py:import_ovpack` - HTTP router
+- `openviking/service/pack_service.py` - Core service implementation
+- `crates/ov_cli/src/handlers.rs:handle_import` - CLI handler
+
+#### 2. Interface and Parameter Description
+
+**Parameters**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| temp_file_id | string | Yes | - | Temporary upload file ID (obtained via [temp_upload](02-resources.md#temp_upload)) |
+| parent | string | Yes | - | Target parent URI (import to this location) |
+| on_conflict | string | No | fail | Conflict policy: `fail`, `overwrite`, or `skip` |
+| vector_mode | string | No | auto | Vector handling: `auto`, `recompute`, or `require` |
+
+**Permission Requirements**: ROOT, ADMIN, or USER
+
+**Behavior Notes**:
+- The API no longer accepts `vectorize` or `force`.
+- `vector_mode=auto` restores a compatible dense snapshot when present, otherwise recomputes vectors. `recompute` always ignores package vectors. `require` fails unless a compatible dense snapshot is present.
+- Dense snapshot compatibility checks compare embedding provider, model, input mode, query/document parameters, and dimensions.
+- Session files are part of the user namespace (`viking://user/{user_id}/sessions/...`) and do not trigger vectorization.
+- `on_conflict=fail` returns a structured `409 CONFLICT` when the target root already exists.
+- `on_conflict=overwrite` replaces the existing target root. `on_conflict=skip` keeps the existing target root and returns it without writing package contents. `skip` is root-level, not file-level.
+- Packages without a manifest are rejected by default because they cannot provide content integrity guarantees.
+- Packages with manifest entries are rejected if content files or directories are missing, extra files or directories are present, file sizes differ, per-file `sha256` differs, or `content_sha256` is missing or differs.
+- Packages whose manifest `format_version` is not the current supported version (`3`) are rejected.
+- `.abstract.md` and `.overview.md` are restored as semantic sidecars. `.relations.json` and OVPack internals are excluded.
+- Manifest `context_type`, when present in index scalar metadata, must match the final import path semantics.
+- Top-level scope packages such as `viking://resources/` must be imported to `viking://`.
+- OVPack does not add import package-size, file-count, or directory-depth limits; the practical limit comes from ZIP, the storage backend, and the runtime environment.
+
+#### 3. Usage Examples
+
+
+**HTTP API**
+
+```
+POST /api/v1/pack/import
+Content-Type: application/json
+```
+
+```bash
+# Step 1: Upload .ovpack file
+TEMP_FILE_ID=$(
+ curl -s -X POST http://localhost:1933/api/v1/resources/temp_upload \
+ -H "X-API-Key: your-admin-key" \
+ -F "file=@./exports/my-project.ovpack" \
+ | jq -r '.result.temp_file_id'
+)
+
+# Step 2: Import
+curl -X POST http://localhost:1933/api/v1/pack/import \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-admin-key" \
+ -d "{
+ \"temp_file_id\": \"$TEMP_FILE_ID\",
+ \"parent\": \"viking://resources/imported/\",
+ \"on_conflict\": \"overwrite\",
+ \"vector_mode\": \"auto\"
+ }"
+```
+
+**Python SDK**
+
+```python
+import openviking as ov
+
+client = 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
+```
+
+**TypeScript SDK**
+
+```typescript
+const uri = await client.importOVPack(
+ "./exports/docs.ovpack",
+ "viking://resources/",
+ {
+ onConflict: "overwrite",
+ vectorMode: "auto",
+ },
+);
+console.log(uri);
+```
+
+**Go SDK**
+
+```go
+uri, err := client.ImportOVPack(
+ ctx,
+ "./exports/my-project.ovpack",
+ "viking://resources/imported/",
+ &openviking.ImportPackOptions{
+ OnConflict: "overwrite",
+ VectorMode: "auto",
+ },
+)
+if err != nil {
+ return err
+}
+fmt.Println(uri)
+```
+
+**CLI**
+
+```bash
+# Import .ovpack file
+ov import ./exports/my-project.ovpack viking://resources/imported/
+
+# Explicit conflict policy
+ov import ./exports/my-project.ovpack viking://resources/imported/ --on-conflict overwrite
+
+# Require restoring a compatible dense vector snapshot
+ov import ./exports/my-project.ovpack viking://resources/imported/ --vector-mode require
+```
+
+
+**Response Example**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "uri": "viking://resources/imported/my-project/"
+ },
+ "telemetry": {
+ "operation_id": "550e8400-e29b-41d4-a716-446655440000"
+ }
+}
+```
+
+**Conflict Error Example**
+
+```json
+{
+ "status": "error",
+ "error": {
+ "code": "CONFLICT",
+ "message": "Resource already exists at viking://resources/imported/my-project. Use on_conflict='overwrite' to replace it.",
+ "details": {
+ "resource": "viking://resources/imported/my-project"
+ }
+ }
+}
+```
+
+---
+
+### backup_ovpack
+
+Back up public scope roots as a restore-only `.ovpack` file. The backup includes
+`resources` and `user`; sessions are included through the user namespace under
+`user/{user_id}/sessions`. It excludes internal runtime data such as `temp` and
+`queue`. Set `include_vectors=true` to include compatible
+pure-dense vector snapshots; hybrid index types reject vector snapshot export.
+
+```
+POST /api/v1/pack/backup
+```
+
+```bash
+curl -X POST http://localhost:1933/api/v1/pack/backup \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-admin-key" \
+ -d '{"include_vectors":false}' \
+ --output openviking-backup.ovpack
+```
+
+Go SDK:
+
+```go
+outPath, err := client.BackupOVPack(
+ ctx,
+ "./backups/openviking.ovpack",
+ &openviking.PackOptions{IncludeVectors: true},
+)
+if err != nil {
+ return err
+}
+fmt.Println(outPath)
+```
+
+CLI:
+
+```bash
+ov backup ./backups/openviking.ovpack
+ov backup ./backups/openviking.ovpack --include-vectors
+```
+
+**Response**
+
+On HTTP success, the endpoint returns an `application/zip` byte stream instead of the standard JSON envelope:
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/zip
+Content-Disposition: attachment; filename="openviking-backup.ovpack"
+
+<ovpack binary body>
+```
+
+The Go SDK and CLI write the stream to the requested path and return or print that local path.
+
+---
+
+### restore_ovpack
+
+Restore a backup package created by `backup_ovpack` to the original public scope
+roots. Regular import rejects backup packages. Vector handling follows
+`vector_mode`; session files under the user namespace are restored without
+vectorization.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| temp_file_id | string | Yes | - | Temporary upload file ID |
+| on_conflict | string | No | fail | Conflict policy: `fail`, `overwrite`, or `skip` |
+| vector_mode | string | No | auto | Vector handling: `auto`, `recompute`, or `require` |
+
+```
+POST /api/v1/pack/restore
+Content-Type: application/json
+```
+
+```bash
+TEMP_FILE_ID=$(
+ curl -s -X POST http://localhost:1933/api/v1/resources/temp_upload \
+ -H "X-API-Key: your-admin-key" \
+ -F "file=@./backups/openviking.ovpack" \
+ | jq -r '.result.temp_file_id'
+)
+
+curl -X POST http://localhost:1933/api/v1/pack/restore \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-admin-key" \
+ -d "{\"temp_file_id\":\"$TEMP_FILE_ID\",\"on_conflict\":\"overwrite\",\"vector_mode\":\"auto\"}"
+```
+
+Go SDK:
+
+```go
+uri, err := client.RestoreOVPack(
+ ctx,
+ "./backups/openviking.ovpack",
+ &openviking.ImportPackOptions{
+ OnConflict: "overwrite",
+ VectorMode: "require",
+ },
+)
+if err != nil {
+ return err
+}
+fmt.Println(uri)
+```
+
+CLI:
+
+```bash
+ov restore ./backups/openviking.ovpack --on-conflict overwrite
+ov restore ./backups/openviking.ovpack --on-conflict overwrite --vector-mode require
+```
+
+**Response**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "uri": "viking://"
+ }
+}
+```
+
+`uri` is the public scope root restored from the backup.
+
+---
+
+## Related Documentation
+
+- [OVPack Guide](../guides/09-ovpack.md) - format, migration, and workflows
+- [Snapshots](11-snapshot.md) - workspace version management
+- [Temporary Upload](02-resources.md#temp_upload) - upload packages before import
diff --git a/docs/en/api/15-watches.md b/docs/en/api/15-watches.md
new file mode 100644
index 000000000..d77e01e15
--- /dev/null
+++ b/docs/en/api/15-watches.md
@@ -0,0 +1,205 @@
+# Resource Watches
+
+The Watch API manages periodic resource checks, pausing, resuming, and manual triggers.
+
+## API Reference
+
+### 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.
+
+#### 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.
+
+**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.
+- **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
+
+**Code Entry Points**:
+- `openviking/server/routers/watches.py` — REST router for `/api/v1/watches`
+- `crates/ov_cli/src/commands/watch.rs` — `ov task watch` CLI subcommand group
+- `openviking/server/mcp_endpoint.py` — MCP `list_watches` / `cancel_watch` tools and the `watch_interval` / `to` parameters on `add_resource`
+- `openviking/resource/watch_manager.py:WatchManager` — task persistence and scheduling primitives
+
+#### 2. Interface and Parameter Description
+
+For every single-task endpoint the path `{task_id}` can be replaced with a `?to_uri=` query argument. The CLI `<key>` argument is auto-classified: any value starting with `viking://` routes to the by-URI path, anything else is treated as a task ID (other URI schemes such as `http://` are rejected locally to avoid silent 404s).
+
+**`PATCH /watches` body** (all fields optional; at least one is required)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| watch_interval | float | New cadence in minutes. Must be `> 0`; use `is_active=false` to pause without losing the cadence. |
+| is_active | bool | Toggle activation without losing the cadence (pause / resume). |
+| reason | string | Update the recorded reason for the watch. |
+| instruction | string | Update the semantic processing instruction. |
+
+Unrecognized fields are rejected with HTTP `400` and `INVALID_ARGUMENT` (`extra="forbid"` on the request model). Fields left unset preserve their current values.
+
+#### 3. Usage Examples
+
+**HTTP API**
+
+```bash
+# List active watch tasks (drop ?active_only to include paused ones)
+curl -s "http://localhost:1933/api/v1/watches?active_only=true" \
+ -H "X-API-Key: your-key"
+
+# Pause a watch without losing its cadence
+curl -X PATCH "http://localhost:1933/api/v1/watches/<task_id>" \
+ -H "X-API-Key: your-key" -H "Content-Type: application/json" \
+ -d '{"is_active": false}'
+
+# Trigger an immediate refresh (fire-and-forget; returns before the re-ingest finishes)
+curl -X POST "http://localhost:1933/api/v1/watches/<task_id>/trigger" \
+ -H "X-API-Key: your-key"
+
+# Resolve by URI instead of task ID
+curl -X DELETE "http://localhost:1933/api/v1/watches?to_uri=viking://resources/guide.md" \
+ -H "X-API-Key: your-key"
+```
+
+**Python SDK**
+
+```python
+watches = client.list_watches(active_only=True)
+client.update_watch(to_uri="viking://resources/guide.md", is_active=False)
+client.trigger_watch(to_uri="viking://resources/guide.md")
+client.delete_watch(to_uri="viking://resources/guide.md")
+```
+
+**TypeScript SDK**
+
+```typescript
+const watches = await client.listWatches({ activeOnly: true });
+await client.updateWatch(
+ { toUri: "viking://resources/guide.md" },
+ { isActive: false },
+);
+await client.triggerWatch({ toUri: "viking://resources/guide.md" });
+await client.deleteWatch({ toUri: "viking://resources/guide.md" });
+```
+
+**Go SDK**
+
+```go
+watches, err := client.ListWatches(ctx, &openviking.ListWatchesOptions{
+ ActiveOnly: true,
+})
+updated, err := client.UpdateWatch(ctx, openviking.UpdateWatchOptions{
+ ToURI: "viking://resources/guide.md",
+ IsActive: openviking.Bool(false),
+})
+triggered, err := client.TriggerWatch(ctx, openviking.WatchRef{
+ ToURI: "viking://resources/guide.md",
+})
+deleted, err := client.DeleteWatch(ctx, openviking.WatchRef{
+ ToURI: "viking://resources/guide.md",
+})
+_, _, _, _ = watches, updated, triggered, deleted
+```
+
+**CLI**
+
+The following examples use the `ov task watch` subcommands:
+
+```bash
+# List active watches (drop --active-only to include paused ones)
+ov task watch ls --active-only
+
+# Inspect a single watch (key may be either a viking:// URI or a task_id)
+ov task watch show viking://resources/guide.md
+
+# Pause / resume without losing the cadence
+ov task watch pause viking://resources/guide.md
+ov task watch resume viking://resources/guide.md
+
+# Update the cadence (or any combination of --active / --reason / --instruction)
+ov task watch update viking://resources/guide.md --interval 30
+
+# Trigger an immediate fire-and-forget refresh
+ov task watch trigger viking://resources/guide.md
+
+# Remove a watch task entirely
+ov task watch rm viking://resources/guide.md
+```
+
+**Response**
+
+Listing tasks returns:
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "tasks": [
+ {
+ "task_id": "7f02e980-8df9-4f27-a570-4d8428cbed8a",
+ "path": "https://example.com/guide.md",
+ "to_uri": "viking://resources/guide.md",
+ "parent_uri": "viking://resources",
+ "reason": "keep documentation current",
+ "instruction": "",
+ "watch_interval": 30,
+ "build_index": true,
+ "summarize": false,
+ "processor_kwargs": {},
+ "created_at": "2026-07-24T10:00:00",
+ "last_execution_time": null,
+ "next_execution_time": "2026-07-24T10:30:00",
+ "is_active": true,
+ "account_id": "default",
+ "user_id": "default",
+ "original_role": "user"
+ }
+ ],
+ "total": 1
+ }
+}
+```
+
+Getting one task and a successful update return the same task object directly in `result`. Delete and trigger return:
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "task_id": "7f02e980-8df9-4f27-a570-4d8428cbed8a",
+ "to_uri": "viking://resources/guide.md",
+ "deleted": true
+ }
+}
+```
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "task_id": "7f02e980-8df9-4f27-a570-4d8428cbed8a",
+ "to_uri": "viking://resources/guide.md",
+ "scheduled": true
+ }
+}
+```
+
+`scheduled=true` only confirms that background execution was scheduled. It does not mean re-ingestion has completed; read the task again and inspect `last_execution_time`.
+
+**MCP** (agent control plane — minimum closure only)
+
+```text
+list_watches() # one line per task; URIs only, no task_ids surfaced
+cancel_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.
+
+---
+
+## Related Documentation
+
+- [Resources](02-resources.md) - create resources with watch_interval
+- [Background Tasks](17-tasks.md) - inspect background processing
diff --git a/docs/en/api/16-memory.md b/docs/en/api/16-memory.md
new file mode 100644
index 000000000..785837ecb
--- /dev/null
+++ b/docs/en/api/16-memory.md
@@ -0,0 +1,147 @@
+# Memory
+
+Memory is produced by session commit or explicit extraction, stored in the user memory namespace, and consumed through the content, file-system, and retrieval APIs.
+
+## Built-in Memory Types
+
+| 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.
+
+---
+
+## API Reference
+
+### recall()
+
+Search each memory type independently and assemble a bounded memory block that can be injected directly into Agent context. By default, recall searches `events`, `entities`, and `preferences`; the `experiences` quota defaults to `0` and must be enabled explicitly.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `query` | string | Yes | - | Recall query |
+| `quotas` | object | No | `events=10, entities=10, preferences=3, experiences=0` | Maximum results for each type |
+| `max_chars` | integer | No | `6500` | Maximum rendered memory-block length |
+| `min_score` | number | No | `0.1` | Minimum relevance score |
+| `peer_scope` | string | No | `all` | `actor` searches only the current actor peer; `all` also searches global and other-peer memory |
+| `other_peer_penalty` | number/object | No | Per-type defaults | Score penalty applied to results from other peers |
+| `render` | boolean | No | `true` | Whether to produce the `rendered` memory block |
+
+**HTTP API**
+
+```http
+POST /api/v1/search/recall
+Content-Type: application/json
+```
+
+```bash
+curl -X POST http://localhost:1933/api/v1/search/recall \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "query":"OpenViking API documentation preferences",
+ "quotas":{"events":5,"entities":5,"preferences":3,"experiences":2},
+ "max_chars":6500,
+ "peer_scope":"all"
+ }'
+```
+
+**MCP**
+
+```text
+recall(
+ query="OpenViking API documentation preferences",
+ quotas={"events": 5, "entities": 5, "preferences": 3, "experiences": 2},
+ max_chars=6500,
+ peer_scope="all"
+)
+```
+
+**Response**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "entries": [
+ {
+ "uri": "viking://user/default/memories/preferences/api-docs.md",
+ "score": 0.82,
+ "type": "preferences",
+ "mode": "full",
+ "rank": 1,
+ "content": "The user prefers API documentation with HTTP, SDK, and CLI examples.",
+ "origin": "self"
+ }
+ ],
+ "rendered": "## Global Memory\n### Preferences\n[1] viking://user/default/memories/preferences/api-docs.md (score=0.8200)\nThe user prefers API documentation with HTTP, SDK, and CLI examples.",
+ "stats": {
+ "quotas": {
+ "events": 5,
+ "entities": 5,
+ "preferences": 3,
+ "experiences": 2
+ },
+ "roots": [
+ "viking://user/default/memories"
+ ],
+ "searched": {
+ "events": 2,
+ "entities": 1,
+ "preferences": 1,
+ "experiences": 0
+ },
+ "returned": 1,
+ "dropped": 0,
+ "max_chars": 6500,
+ "min_score": 0.1,
+ "peer_scope": "all",
+ "other_peer_penalties": {
+ "events": 0.1,
+ "entities": 0.1,
+ "preferences": 0.02,
+ "experiences": 0.02
+ },
+ "origins": {
+ "actor_peer": 0,
+ "self": 1,
+ "other_peer": 0
+ }
+ }
+ }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `entries` | object[] | Structured matches selected by per-type quota and relevance |
+| `entries[].uri` | string | Viking URI of the memory entry |
+| `entries[].score` | number | Raw relevance score |
+| `entries[].type` | string | `events`, `entities`, `preferences`, or `experiences` |
+| `entries[].mode` | string | Rendering mode: `full`, `summary`, or `uri` |
+| `entries[].rank` | integer | Rank within the memory type, starting at `1` |
+| `entries[].origin` | string | Source: `actor_peer`, `self`, or `other_peer` |
+| `entries[].content` | string | Full content when `mode=full`; otherwise it may be omitted |
+| `entries[].summary` | string | Summary used for degraded rendering; otherwise it may be omitted |
+| `entries[].abstract` | string | Search-hit abstract; omitted when unavailable |
+| `rendered` | string | Text bounded by `max_chars` and ready for Agent context injection; empty when `render=false` |
+| `stats` | object | Effective quotas, roots, per-type search counts, returned and dropped counts, threshold, peer scope, and origin counts |
+
+The public Python, TypeScript, and Go SDKs and the `ov` CLI do not currently wrap type-quota recall, so this section shows only the HTTP tab and the existing MCP call.
+
+## Related Documentation
+
+- [Sessions](05-sessions.md) - commit and extract
+- [Retrieval](06-retrieval.md) - search memory
+- [Content](12-content.md) - read memory content
diff --git a/docs/en/api/17-tasks.md b/docs/en/api/17-tasks.md
new file mode 100644
index 000000000..39472fd6b
--- /dev/null
+++ b/docs/en/api/17-tasks.md
@@ -0,0 +1,252 @@
+# Background Tasks
+
+The Task API tracks asynchronous resource imports, session commits, reindexing, snapshot restores, and similar operations.
+
+## API Reference
+
+### get_task()
+
+#### 1. API Implementation Introduction
+
+Query background task status for APIs that return `task_id`, such as session commit, `add_resource`, and admin reindex.
+
+**Task Statuses:**
+- `pending`: Task waiting to execute
+- `running`: Task in progress
+- `completed`: Task successfully completed
+- `failed`: Task failed
+
+**Code Entries:**
+- `openviking/server/routers/tasks.py:get_task()` - HTTP route
+
+Task records are persisted in AGFS and can be queried after server restart, subject to task retention cleanup.
+
+#### 2. Interface and Parameter Description
+
+**Parameters**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| task_id | str | Yes | - | Task ID returned by a background API |
+
+#### 3. Usage Examples
+
+**HTTP API**
+
+```http
+GET /api/v1/tasks/{task_id}
+```
+
+```bash
+curl -X GET http://localhost:1933/api/v1/tasks/uuid-xxx \
+ -H "X-API-Key: your-key"
+```
+
+**Python SDK**
+
+```python
+from openviking_sdk import AsyncHTTPClient
+
+client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")
+await client.initialize()
+
+task = await client.get_task("uuid-xxx")
+print(f"Status: {task['status']}")
+await client.close()
+```
+
+**TypeScript SDK**
+
+```typescript
+console.log(await client.getTask("task-id"));
+```
+
+**Go SDK**
+
+```go
+task, err := client.GetTask(ctx, "uuid-xxx")
+if err != nil {
+ return err
+}
+if task != nil {
+ fmt.Println(task["status"])
+}
+```
+
+**CLI**
+
+```bash
+ov task status uuid-xxx
+```
+
+**Response Example (resource import in progress)**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "task_id": "uuid-xxx",
+ "task_type": "add_resource",
+ "status": "running",
+ "resource_id": "viking://resources/guide",
+ "stage": "processing_queue"
+ }
+}
+```
+
+`stage` is nullable. Git repository resource import tasks may report `queued`, `fetching`, `parsing`, `finalizing`, or `processing_queue`; other task types may leave it as `null`. Live queue counters are intentionally not part of task status; use observer queue APIs for live counts, or read `result.queue_status` after completion.
+
+**Response Example (completed)**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "task_id": "uuid-xxx",
+ "task_type": "session_commit",
+ "status": "completed",
+ "result": {
+ "session_id": "a1b2c3d4",
+ "archive_uri": "viking://user/alice/sessions/a1b2c3d4/history/archive_001",
+ "memory_diff_uri": "viking://user/alice/sessions/a1b2c3d4/history/archive_001/memory_diff.json",
+ "memories_extracted": {
+ "profile": 1,
+ "preferences": 2,
+ "entities": 1,
+ "cases": 1
+ },
+ "active_count_updated": 2,
+ "token_usage": {
+ "llm": {
+ "prompt_tokens": 5200,
+ "completion_tokens": 1800,
+ "total_tokens": 7000
+ },
+ "embedding": {
+ "total_tokens": 1500
+ },
+ "total": {
+ "total_tokens": 8500
+ }
+ }
+ }
+ }
+}
+```
+
+`memories_extracted` in the completed task result reports per-category counts for this commit only. Sum its values when you want the total for this commit.
+
+---
+
+### list_tasks()
+
+#### 1. API Implementation Introduction
+
+List background tasks visible to the current caller, supporting filtering by type, status, resource.
+
+**Code Entries:**
+- `openviking/server/routers/tasks.py:list_tasks()` - HTTP route
+- `openviking_cli/client/base.py:BaseClient.list_tasks()` - Python SDK
+
+#### 2. Interface and Parameter Description
+
+**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 |
+
+#### 3. Usage Examples
+
+**HTTP API**
+
+```http
+GET /api/v1/tasks?task_type=session_commit&status=running&limit=20
+```
+
+```bash
+curl -X GET "http://localhost:1933/api/v1/tasks?task_type=session_commit&status=running&limit=20" \
+ -H "X-API-Key: your-key"
+```
+
+**Python SDK**
+
+```python
+from openviking_sdk import AsyncHTTPClient
+
+client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")
+await client.initialize()
+
+tasks = await client.list_tasks(
+ task_type="session_commit",
+ status="running",
+ limit=20,
+)
+for task in tasks:
+ print(task["task_id"], task["status"])
+await client.close()
+```
+
+**TypeScript SDK**
+
+```typescript
+console.log(await client.listTasks());
+```
+
+**Go SDK**
+
+```go
+tasks, err := client.ListTasks(ctx, &openviking.ListTasksOptions{
+ TaskType: "session_commit",
+ Status: "running",
+ Limit: 20,
+})
+if err != nil {
+ return err
+}
+for _, task := range tasks {
+ fmt.Println(task)
+}
+```
+
+**CLI**
+
+```bash
+# List tasks
+ov task list
+
+# Filter by task type and status
+ov task list --task-type session_commit --status running
+```
+
+**Response Example**
+
+```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,
+ "stage": null
+ }
+ ]
+}
+```
+
+---
+
+## Related Documentation
+
+- [Sessions](05-sessions.md) - session commit tasks
+- [Resources](02-resources.md) - resource ingestion tasks
+- [Content](12-content.md) - asynchronous reindex tasks
diff --git a/docs/en/api/18-observer.md b/docs/en/api/18-observer.md
new file mode 100644
index 000000000..b6bfdeadb
--- /dev/null
+++ b/docs/en/api/18-observer.md
@@ -0,0 +1,520 @@
+# Runtime Observability
+
+The Observer API reports immediate status for queues, the vector database, models, locks, retrieval, and the file system.
+
+## Observer API
+
+The observer API provides detailed component-level monitoring.
+
+### observer.queue
+
+#### 1. API Implementation Overview
+
+Get queue system status (embedding and semantic processing queues). Shows pending, in-progress, completed, and error counts for each queue.
+
+**Code Entry Points**:
+- `openviking/server/routers/observer.py:observer_queue` - HTTP route
+- `openviking/service/debug_service.py:ObserverService.queue` - Core implementation
+- `openviking/storage/observers/queue_observer.py` - Queue observer
+
+#### 2. Interface and Parameters
+
+No parameters.
+
+#### 3. Usage Examples
+
+**HTTP API**
+
+```
+GET /api/v1/observer/queue
+```
+
+```bash
+curl -X GET http://localhost:1933/api/v1/observer/queue \
+ -H "X-API-Key: your-key"
+```
+
+**Python SDK**
+
+```python
+print(client.observer.queue())
+# Output:
+# [queue] (healthy)
+# Queue Pending In Progress Processed Errors Total
+# Embedding 0 0 10 0 10
+# Semantic 0 0 10 0 10
+# TOTAL 0 0 20 0 20
+```
+
+**TypeScript SDK**
+
+```typescript
+console.log(await client.queueStatus());
+```
+
+**Go SDK**
+
+```go
+status, err := client.QueueStatus(ctx)
+if err != nil {
+ return err
+}
+fmt.Println(status["is_healthy"])
+```
+
+**CLI**
+
+```bash
+ov observer queue
+```
+
+**Response Example**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "name": "queue",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "Queue Pending In Progress Processed Errors Total\nEmbedding 0 0 10 0 10\nSemantic 0 0 10 0 10\nTOTAL 0 0 20 0 20"
+ },
+ "time": 0.1
+}
+```
+
+---
+
+### observer.vikingdb
+
+#### 1. API Implementation Overview
+
+Get VikingDB status (collections, indexes, vector counts).
+
+**Code Entry Points**:
+- `openviking/server/routers/observer.py:observer_vikingdb` - HTTP route
+- `openviking/service/debug_service.py:ObserverService.vikingdb` - Core implementation
+- `openviking/storage/observers/vikingdb_observer.py` - VikingDB observer
+- `crates/ov_cli/src/commands/observer.rs` - CLI command
+
+#### 2. Interface and Parameters
+
+No parameters.
+
+#### 3. Usage Examples
+
+**HTTP API**
+
+```
+GET /api/v1/observer/vikingdb
+```
+
+```bash
+curl -X GET http://localhost:1933/api/v1/observer/vikingdb \
+ -H "X-API-Key: your-key"
+```
+
+**Python SDK**
+
+```python
+print(client.observer.vikingdb())
+# Output:
+# [vikingdb] (healthy)
+# Collection Index Count Vector Count Status
+# context 1 55 OK
+# TOTAL 1 55
+
+# Access specific attributes
+print(client.observer.vikingdb().is_healthy) # True
+print(client.observer.vikingdb().status) # Status table string
+```
+
+**TypeScript SDK**
+
+```typescript
+console.log(await client.vikingDBStatus());
+```
+
+**Go SDK**
+
+```go
+status, err := client.VikingDBStatus(ctx)
+if err != nil {
+ return err
+}
+fmt.Println(status["is_healthy"])
+```
+
+**CLI**
+
+```bash
+ov observer vikingdb
+```
+
+**Response Example**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "name": "vikingdb",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "Collection Index Count Vector Count Status\ncontext 1 55 OK\nTOTAL 1 55"
+ },
+ "time": 0.1
+}
+```
+
+---
+
+### observer.models
+
+#### 1. API Implementation Overview
+
+Get aggregated model subsystem status (VLM, embedding, rerank). Checks if each model provider is healthy and available.
+
+**Code Entry Points**:
+- `openviking/server/routers/observer.py:observer_models` - HTTP route
+- `openviking/service/debug_service.py:ObserverService.models` - Core implementation
+- `openviking/storage/observers/models_observer.py` - Models observer
+- `crates/ov_cli/src/commands/observer.rs` - CLI command
+
+#### 2. Interface and Parameters
+
+No parameters.
+
+#### 3. Usage Examples
+
+**HTTP API**
+
+```
+GET /api/v1/observer/models
+```
+
+```bash
+curl -X GET http://localhost:1933/api/v1/observer/models \
+ -H "X-API-Key: your-key"
+```
+
+**Python SDK**
+
+```python
+print(client.observer.models())
+# Output:
+# [models] (healthy)
+# provider_model healthy detail
+# dense_embedding yes ...
+# rerank yes ...
+# vlm yes ...
+```
+
+**TypeScript SDK**
+
+```typescript
+console.log(await client.modelsStatus());
+```
+
+**Go SDK**
+
+```go
+status, err := client.ModelsStatus(ctx)
+if err != nil {
+ return err
+}
+fmt.Println(status["is_healthy"])
+```
+
+**CLI**
+
+```bash
+ov observer models
+```
+
+**Response Example**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "name": "models",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "provider_model healthy detail\ndense_embedding yes ...\nrerank yes ...\nvlm yes ..."
+ },
+ "time": 0.1
+}
+```
+
+---
+
+### observer.lock
+
+#### 1. API Implementation Overview
+
+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
+
+No parameters.
+
+#### 3. Usage Examples
+
+**HTTP API**
+
+```
+GET /api/v1/observer/lock
+```
+
+```bash
+curl -X GET http://localhost:1933/api/v1/observer/lock \
+ -H "X-API-Key: your-key"
+```
+
+The public SDKs and CLI do not currently expose a lock-specific observer method. Use the HTTP API for this component; `ov observer system` includes it in the aggregate status.
+
+**Response Example**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "name": "lock",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "..."
+ },
+ "time": 0.1
+}
+```
+
+---
+
+### observer.retrieval
+
+#### 1. API Implementation Overview
+
+Get retrieval quality metrics.
+
+**Code Entry Points**:
+- `openviking/server/routers/observer.py:observer_retrieval` - HTTP route
+- `openviking/service/debug_service.py:ObserverService.retrieval` - Core implementation
+- `openviking/storage/observers/retrieval_observer.py` - Retrieval observer
+- `crates/ov_cli/src/commands/observer.rs` - CLI command
+
+#### 2. Interface and Parameters
+
+No parameters.
+
+#### 3. Usage Examples
+
+**HTTP API**
+
+```
+GET /api/v1/observer/retrieval
+```
+
+```bash
+curl -X GET http://localhost:1933/api/v1/observer/retrieval \
+ -H "X-API-Key: your-key"
+```
+
+**CLI**
+
+```bash
+ov observer retrieval
+```
+
+**Response Example**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "name": "retrieval",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "..."
+ },
+ "time": 0.1
+}
+```
+
+---
+
+### observer.filesystem
+
+#### 1. API Implementation Overview
+
+Get filesystem operation metrics.
+
+**Code Entry Points**:
+- `openviking/server/routers/observer.py:observer_filesystem` - HTTP route
+- `openviking/service/debug_service.py:ObserverService.filesystem` - Core implementation
+- `openviking/storage/observers/filesystem_observer.py` - Filesystem observer
+- `crates/ov_cli/src/commands/observer.rs` - CLI command
+
+#### 2. Interface and Parameters
+
+No parameters.
+
+#### 3. Usage Examples
+
+**HTTP API**
+
+```
+GET /api/v1/observer/filesystem
+```
+
+```bash
+curl -X GET http://localhost:1933/api/v1/observer/filesystem \
+ -H "X-API-Key: your-key"
+```
+
+**CLI**
+
+```bash
+ov observer filesystem
+```
+
+**Response Example**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "name": "filesystem",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "..."
+ },
+ "time": 0.1
+}
+```
+
+---
+
+### observer.system
+
+#### 1. API Implementation Overview
+
+Get overall system status, including all components (queue, vikingdb, models, lock, retrieval).
+
+**Code Entry Points**:
+- `openviking/server/routers/observer.py:observer_system` - HTTP route
+- `openviking/service/debug_service.py:ObserverService.system` - Core implementation
+- `crates/ov_cli/src/commands/observer.rs` - CLI command
+
+#### 2. Interface and Parameters
+
+No parameters.
+
+#### 3. Usage Examples
+
+**HTTP API**
+
+```
+GET /api/v1/observer/system
+```
+
+```bash
+curl -X GET http://localhost:1933/api/v1/observer/system \
+ -H "X-API-Key: your-key"
+```
+
+**Python SDK**
+
+```python
+print(client.observer.system())
+# Output:
+# [queue] (healthy)
+# ...
+#
+# [vikingdb] (healthy)
+# ...
+#
+# [models] (healthy)
+# ...
+#
+# [system] (healthy)
+```
+
+**TypeScript SDK**
+
+```typescript
+console.log(await client.getStatus());
+```
+
+**Go SDK**
+
+```go
+status, err := client.GetStatus(ctx)
+if err != nil {
+ return err
+}
+fmt.Println(status["is_healthy"])
+```
+
+**CLI**
+
+```bash
+ov observer system
+```
+
+**Response Example**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "is_healthy": true,
+ "errors": [],
+ "components": {
+ "queue": {
+ "name": "queue",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "..."
+ },
+ "vikingdb": {
+ "name": "vikingdb",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "..."
+ },
+ "models": {
+ "name": "models",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "..."
+ },
+ "lock": {
+ "name": "lock",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "..."
+ },
+ "retrieval": {
+ "name": "retrieval",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "..."
+ }
+ }
+ },
+ "time": 0.1
+}
+```
+
+---
+
+## Related Documentation
+
+- [Metrics](09-metrics.md) - Prometheus scraping
+- [System Status](07-system.md) - health and consistency checks
diff --git a/docs/en/api/20-webdav.md b/docs/en/api/20-webdav.md
new file mode 100644
index 000000000..7c34986ea
--- /dev/null
+++ b/docs/en/api/20-webdav.md
@@ -0,0 +1,136 @@
+# WebDAV
+
+WebDAV provides file-protocol access to the `resources` namespace.
+
+**Code entry point**: `openviking/server/routers/webdav.py`
+
+## WebDAV (Phase 1)
+
+OpenViking Server also exposes a minimal WebDAV adapter for resource files:
+
+```text
+/webdav/resources
+```
+
+Phase 1 intentionally keeps the scope narrow:
+
+- Resources only. Memories, skills, sessions, and other namespaces are not exposed.
+- Text-first writes. `PUT` currently accepts UTF-8 text content only.
+- WebDAV subset only. `OPTIONS`, `PROPFIND`, `GET`, `HEAD`, `PUT`, `DELETE`, `MKCOL`, and `MOVE` are supported.
+- Semantic sidecars and internal system files stay internal. Derived or internal files such as `.abstract.md`, `.overview.md`, `.relations.json`, `.path.ovlock`, `.redirect.json`, and `.sync_log.json` are hidden from listings and cannot be accessed directly through WebDAV.
+
+Behavior notes:
+
+- Creating a new file through WebDAV triggers OpenViking semantic generation for that file path.
+- Replacing an existing file through WebDAV refreshes related semantics and vectors, same as `write()`.
+- `PUT` does not create parent collections automatically. Create missing directories with `MKCOL` first.
+- User-created dot-directories and dot-files remain visible unless they match one of the reserved internal filenames above.
+- When multi-write storage is enabled, files redirected to a backup are still exposed through the filesystem APIs as normal files; internal redirect and sync metadata never become visible to callers.
+
+## API Reference
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `OPTIONS` | `/webdav/resources`, `/webdav/resources/{resource_path}` | Return supported methods and DAV version |
+| `PROPFIND` | `/webdav/resources`, `/webdav/resources/{resource_path}` | Return properties for the target and immediate children |
+| `GET` / `HEAD` | `/webdav/resources`, `/webdav/resources/{resource_path}` | Read file content or headers |
+| `PUT` | `/webdav/resources`, `/webdav/resources/{resource_path}` | Create or overwrite a UTF-8 text file |
+| `DELETE` | `/webdav/resources`, `/webdav/resources/{resource_path}` | Delete a file or recursively delete a directory |
+| `MKCOL` | `/webdav/resources`, `/webdav/resources/{resource_path}` | Create a directory |
+| `MOVE` | `/webdav/resources`, `/webdav/resources/{resource_path}` | Move or rename a file or directory |
+
+Except for `OPTIONS`, WebDAV requests use the same authentication headers as other OpenViking APIs. Paths must remain under `resources` and cannot escape through `..`, backslashes, or equivalent forms.
+
+| Header | Methods | Required | Description |
+|--------|---------|----------|-------------|
+| `X-API-Key` | All except `OPTIONS` | Yes | OpenViking API key |
+| `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 |
+
+### List a collection
+
+`Depth` supports `0` and one level; other values are treated as one level. A successful response is `207 Multi-Status` with DAV XML.
+
+**HTTP API**
+
+```bash
+curl -X PROPFIND http://localhost:1933/webdav/resources/docs \
+ -H "X-API-Key: your-key" \
+ -H "Depth: 1"
+```
+
+**Response Example**
+
+```xml
+<?xml version='1.0' encoding='utf-8'?>
+<d:multistatus xmlns:d="DAV:">
+ <d:response>
+ <d:href>/webdav/resources/docs/</d:href>
+ <d:propstat>
+ <d:prop>
+ <d:displayname>docs</d:displayname>
+ <d:resourcetype><d:collection /></d:resourcetype>
+ <d:getcontenttype>httpd/unix-directory</d:getcontenttype>
+ </d:prop>
+ <d:status>HTTP/1.1 200 OK</d:status>
+ </d:propstat>
+ </d:response>
+</d:multistatus>
+```
+
+### Read and write files
+
+`PUT` does not create parent directories. File creation returns `201`, replacement returns `204`, and non-UTF-8 content returns `415`.
+
+**HTTP API**
+
+```bash
+curl http://localhost:1933/webdav/resources/docs/readme.md \
+ -H "X-API-Key: your-key"
+```
+
+```bash
+curl -X PUT http://localhost:1933/webdav/resources/docs/readme.md \
+ -H "X-API-Key: your-key" \
+ -H "Content-Type: text/plain; charset=utf-8" \
+ --data-binary @README.md
+```
+
+### Create, move, and delete
+
+`MOVE` requires a `Destination` header whose value remains under `/webdav/resources`. The destination parent directory must already exist.
+
+**HTTP API**
+
+```bash
+curl -X MKCOL http://localhost:1933/webdav/resources/archive \
+ -H "X-API-Key: your-key"
+```
+
+```bash
+curl -X MOVE http://localhost:1933/webdav/resources/docs/readme.md \
+ -H "X-API-Key: your-key" \
+ -H "Destination: /webdav/resources/archive/readme.md"
+```
+
+```bash
+curl -X DELETE http://localhost:1933/webdav/resources/archive \
+ -H "X-API-Key: your-key"
+```
+
+**Status Codes**
+
+| Operation | Success | Common failures |
+|-----------|---------|-----------------|
+| `GET` / `HEAD` | `200` | `404` missing; `405` target is a directory |
+| `PUT` | `201` create; `204` overwrite | `409` parent missing; `415` body is not UTF-8 |
+| `MKCOL` | `201` | `405` already exists; `409` parent missing |
+| `MOVE` | `201` new target; `204` overwrite | `400` destination missing; `409` destination parent missing; `412` overwrite disabled |
+| `DELETE` | `204` | `404` missing; `405` resources root cannot be deleted |
+
+WebDAV is a protocol entry point rather than an OpenViking SDK or `ov` CLI surface, so this page shows only the HTTP tab. Use [File System](03-filesystem.md) for SDK and CLI file operations.
+
+## Related Documentation
+
+- [File System](03-filesystem.md) - equivalent HTTP, SDK, and CLI file operations
diff --git a/docs/en/api/21-code.md b/docs/en/api/21-code.md
new file mode 100644
index 000000000..64be6075a
--- /dev/null
+++ b/docs/en/api/21-code.md
@@ -0,0 +1,119 @@
+# Code Navigation
+
+The Code Navigation API extracts structure, searches symbols, and expands symbols in source code already imported into OpenViking. Every `uri` must be a `viking://` URI; import local code through the Resources API first.
+
+**Code entry points**:
+
+- `openviking/server/routers/code.py` - HTTP routes and request models
+- `openviking/parse/parsers/code/ast/code_tools.py` - outline, search, and symbol expansion
+
+## API Reference
+
+### outline()
+
+Extract the symbol outline of one source file.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `uri` | string | Yes | `viking://` URI of an imported source file |
+
+**HTTP API**
+
+```http
+POST /api/v1/code/outline
+Content-Type: application/json
+```
+
+```bash
+curl -X POST http://localhost:1933/api/v1/code/outline \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{"uri":"viking://resources/project/src/main.py"}'
+```
+
+**Response Example**
+
+`result` is a text outline suitable for display or direct Agent context.
+
+```json
+{
+ "status": "ok",
+ "result": "viking://resources/project/src/main.py [python, 24 lines]\n\nclass SessionService L16-24\n\ndef main() L8-12"
+}
+```
+
+### search()
+
+Search symbols in supported source files below a URI. One request scans at most 200 files; when capped, `result` ends with a prompt to narrow the URI.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `uri` | string | Yes | File or directory URI to search recursively |
+| `query` | string | Yes | Non-empty symbol name or search term |
+
+**HTTP API**
+
+```http
+POST /api/v1/code/search
+Content-Type: application/json
+```
+
+```bash
+curl -X POST http://localhost:1933/api/v1/code/search \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{"uri":"viking://resources/project/src","query":"SessionService"}'
+```
+
+**Response Example**
+
+```json
+{
+ "status": "ok",
+ "result": "1 matches for \"SessionService\" (scanned 8 files)\n\nviking://resources/project/src/session.py\n SessionService L16-24"
+}
+```
+
+### expand()
+
+Return the complete code block for one symbol in a source file.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `uri` | string | Yes | Source file URI containing the symbol |
+| `symbol` | string | Yes | Non-empty symbol name to expand |
+
+**HTTP API**
+
+```http
+POST /api/v1/code/expand
+Content-Type: application/json
+```
+
+```bash
+curl -X POST http://localhost:1933/api/v1/code/expand \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{"uri":"viking://resources/project/src/main.py","symbol":"main"}'
+```
+
+**Response Example**
+
+```json
+{
+ "status": "ok",
+ "result": "# viking://resources/project/src/main.py L8-10 (main)\n\ndef main():\n service = SessionService()\n service.run()"
+}
+```
+
+The current implementation returns business failures such as a non-`viking://` URI, an empty query or symbol, or a non-text file with `status="ok"` and an `Error:` message in `result`. A request body missing required fields returns HTTP `400` with `INVALID_ARGUMENT`.
+
+## Current Client Support
+
+These endpoints are currently server-only HTTP capabilities. They are not wrapped by the public Python, TypeScript, or Go SDKs or by the `ov` CLI, so this page shows only the HTTP tab.
+
+## Related Documentation
+
+- [Resources](02-resources.md) - import source code
+- [Retrieval](06-retrieval.md) - general semantic and pattern retrieval
+- [Content](12-content.md) - read source file content
diff --git a/docs/en/api/24-vikingbot.md b/docs/en/api/24-vikingbot.md
new file mode 100644
index 000000000..0c8bad335
--- /dev/null
+++ b/docs/en/api/24-vikingbot.md
@@ -0,0 +1,161 @@
+# VikingBot API
+
+When OpenViking Server starts with `--with-bot`, it proxies VikingBot's core interaction endpoints below `/bot/v1`. These endpoints return `503` when Bot is not enabled.
+
+**Code entry points**:
+
+- `openviking/server/routers/bot.py` - OpenViking Server proxy and identity forwarding
+- `bot/vikingbot/channels/openapi.py` - VikingBot Gateway routes
+- `bot/vikingbot/channels/openapi_models.py` - request, response, and SSE event models
+
+## API Reference
+
+### health()
+
+Check whether the Bot Gateway is available.
+
+**HTTP API**
+
+```bash
+curl http://localhost:1933/bot/v1/health
+```
+
+**Response Example**
+
+```json
+{
+ "status": "healthy",
+ "version": "0.1.0",
+ "timestamp": "2026-07-24T09:00:00"
+}
+```
+
+### chat()
+
+Send a message and wait for the complete reply. Omit `session_id` to create a new session.
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `message` | string | Yes | - | Non-empty user message |
+| `session_id` | string | No | Generated | Existing session to continue |
+| `context` | array | No | `null` | Additional messages containing `role` and `content` |
+| `need_reply` | boolean | No | `true` | Whether the Bot should reply |
+| `disabled_tools` | string[] | No | `[]` | Tool names disabled for this request |
+| `channel_id` | string | No | `null` | Multi-channel routing identifier |
+
+**HTTP API**
+
+```bash
+curl -X POST http://localhost:1933/bot/v1/chat \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{"message":"Summarize my project progress","session_id":"optional-session-id"}'
+```
+
+**CLI**
+
+```bash
+ov chat -m "Summarize my project progress"
+```
+
+**Response Example**
+
+```json
+{
+ "session_id": "session-id",
+ "response_id": "response-id",
+ "message": "Here is the current project summary…",
+ "events": null,
+ "relevant_memories": null,
+ "token_usage": {
+ "prompt_tokens": 120,
+ "completion_tokens": 42,
+ "total_tokens": 162
+ },
+ "timestamp": "2026-07-24T09:00:00"
+}
+```
+
+### chat_stream()
+
+Return reasoning, tool calls, content deltas, and the final response as Server-Sent Events. The request fields are the same as `chat()`; the Gateway enables streaming automatically.
+
+**HTTP API**
+
+```bash
+curl -N -X POST http://localhost:1933/bot/v1/chat/stream \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{"message":"Analyze the current knowledge base"}'
+```
+
+**CLI**
+
+```bash
+ov chat -m "Analyze the current knowledge base"
+```
+
+**SSE Response Example**
+
+Each message uses `data: <json>` format. The `X-VikingBot-Session-ID` response header contains the session ID.
+
+```text
+data: {"event":"reasoning_delta","data":"Inspecting the knowledge base…","timestamp":"2026-07-24T09:00:00"}
+
+data: {"event":"content_delta","data":"The knowledge base contains","timestamp":"2026-07-24T09:00:01"}
+
+data: {"event":"response","data":{"content":"The knowledge base contains…","response_id":"response-id"},"timestamp":"2026-07-24T09:00:02"}
+```
+
+`event` can be `reasoning`, `reasoning_delta`, `tool_call`, `tool_result`, `content_delta`, `iteration`, or `response`.
+
+### feedback()
+
+Submit explicit feedback for an existing assistant response.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `session_id` | string | Yes | Session containing the target response |
+| `response_id` | string | Yes | Target assistant response ID |
+| `feedback_type` | string | Yes | `thumb_up`, `thumb_down`, or `rating` |
+| `feedback_score` | number | Conditional | Required when `feedback_type=rating` |
+| `feedback_reason` | string | No | Feedback reason label |
+| `feedback_text` | string | No | Free-form feedback |
+| `channel_id` | string | No | Multi-channel routing identifier |
+
+**HTTP API**
+
+```bash
+curl -X POST http://localhost:1933/bot/v1/feedback \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "session_id":"session-id",
+ "response_id":"response-id",
+ "feedback_type":"thumb_up"
+ }'
+```
+
+**Response Example**
+
+```json
+{
+ "accepted": true,
+ "response_id": "response-id",
+ "session_id": "session-id",
+ "feedback_type": "thumb_up",
+ "feedback_delay_sec": 8.42,
+ "timestamp": "2026-07-24T09:00:08"
+}
+```
+
+A missing target response returns `404`. Rating feedback without `feedback_score` returns a request validation error.
+
+## Client Scope
+
+The standard OpenViking Python, TypeScript, and Go SDKs do not currently wrap the Bot proxy. Chat is available through the `ov chat` CLI and HTTP. The VikingBot Gateway also exposes Session and Channel APIs; see the [VikingBot documentation](https://github.com/volcengine/OpenViking/blob/main/bot/README.md#http-api).
+
+## Related Documentation
+
+- [VikingBot Concepts](../concepts/15-vikingbot.md) - architecture and interaction flow
+- [VikingBot Guide](../guides/17-vikingbot.md) - setup and Chat workflow
diff --git a/docs/en/api/99-api-doc-writing-guide.md b/docs/en/api/99-api-doc-writing-guide.md
index 9e1b8f01a..c1fdee53a 100644
--- a/docs/en/api/99-api-doc-writing-guide.md
+++ b/docs/en/api/99-api-doc-writing-guide.md
@@ -88,7 +88,9 @@ Explain the purpose of this API, point to the corresponding code entry, and brie
```
-#### 4. Response Example, Error Handling, and Exception Handling (Optional)
+#### 4. Response Contract (Required) and Error Handling (Optional)
+
+Every 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.
---
@@ -142,6 +144,16 @@ When an operation presents all transports together, prefer this order:
- CLI example
- Response example
+Example tabs are generated from bold labels. Put each invocation label in its own
+paragraph 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 (Embedded / HTTP)**`. Do not put the qualifier after the bold label
+or use full-width parentheses. Show only surfaces that are actually
+implemented. If an SDK or CLI does not expose the capability, omit that tab and
+briefly identify the available alternative. Do not wrap a handwritten HTTP request
+and present it as a nonexistent SDK method.
+
For an existing operation with a workflow-specific structure, keep the local
structure stable and place TypeScript next to the other SDK examples.
@@ -256,5 +268,6 @@ When adding or modifying API documentation, please check:
- [ ] Implementation introduction is clear and 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 implementation
- [ ] HTTP method and path are correct
-- [ ] Response example matches actual output
+- [ ] Every public operation has a successful response contract and its example matches actual output
diff --git a/docs/scripts/check-api-reference.mjs b/docs/scripts/check-api-reference.mjs
index 30d8947bf..29f20b7c3 100644
--- a/docs/scripts/check-api-reference.mjs
+++ b/docs/scripts/check-api-reference.mjs
@@ -4,15 +4,23 @@ import { fileURLToPath } from 'node:url'
const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..')
const routerDir = path.join(repoRoot, 'openviking/server/routers')
-const apiDocs = ['zh', 'en'].flatMap((locale) =>
+const locales = ['zh', 'en']
+const allApiDocs = locales.flatMap((locale) =>
fs.readdirSync(path.join(repoRoot, 'docs', locale, 'api'))
- .filter((file) => file.endsWith('.md') && !file.startsWith('01-') && !file.startsWith('99-'))
+ .filter((file) => file.endsWith('.md'))
.map((file) => path.join(repoRoot, 'docs', locale, 'api', file))
)
+const apiDocs = allApiDocs.filter(
+ (file) => !path.basename(file).startsWith('01-') && !path.basename(file).startsWith('99-')
+)
+const overviewDocs = locales.map((locale) =>
+ path.join(repoRoot, 'docs', locale, 'api', '01-overview.md')
+)
+const httpMethods = 'GET|HEAD|POST|PUT|PATCH|DELETE|OPTIONS|PROPFIND|MKCOL|MOVE'
function normalizePath(value) {
const pathname = value.split('?')[0].replace(/\/$/, '') || '/'
- return pathname.replace(/\{[^}]+\}/g, '{}')
+ return pathname.replace(/\{[^}:]+(?::[^}]+)?\}/g, '{}')
}
function closingDelimiter(source, openingIndex, opening = '(', closing = ')') {
@@ -67,17 +75,44 @@ function splitTopLevel(source) {
const routes = new Map()
const middlewareQueryParameters = new Set(['profile'])
+const internalRouterFiles = new Set(['console.py', 'debug.py', 'stats.py', 'user_settings.py'])
for (const file of fs.readdirSync(routerDir).filter((name) => name.endsWith('.py'))) {
+ if (internalRouterFiles.has(file)) continue
const source = fs.readFileSync(path.join(routerDir, file), 'utf8')
- const prefix = source.match(/router\s*=\s*APIRouter\([^)]*prefix=["']([^"']+)/s)?.[1] ?? ''
- for (const match of source.matchAll(/@router\.(get|post|put|patch|delete)\(\s*["']([^"']*)/g)) {
- const definition = source.indexOf('def ', match.index + match[0].length)
+ const routerPrefix =
+ source.match(/router\s*=\s*APIRouter\([^)]*prefix=["']([^"']+)/s)?.[1] ?? ''
+ const mountPrefix = file === 'bot.py' ? '/bot/v1' : ''
+ const decorators = [
+ ...Array.from(
+ source.matchAll(/@router\.(get|post|put|patch|delete)\(\s*["']([^"']*)/g),
+ (match) => ({
+ index: match.index,
+ methods: [match[1].toUpperCase()],
+ path: match[2],
+ sourceLength: match[0].length,
+ })
+ ),
+ ...Array.from(
+ source.matchAll(
+ /@router\.api_route\(\s*["']([^"']*)["']\s*,\s*methods\s*=\s*\[([^\]]+)\]/g
+ ),
+ (match) => ({
+ index: match.index,
+ methods: Array.from(match[2].matchAll(/["']([A-Z]+)["']/g), (item) => item[1]),
+ path: match[1],
+ sourceLength: match[0].length,
+ })
+ ),
+ ].sort((a, b) => a.index - b.index)
+
+ for (const decorator of decorators) {
+ const definition = source.indexOf('def ', decorator.index + decorator.sourceLength)
const opening = source.indexOf('(', definition)
const closing = closingDelimiter(source, opening)
const signature = closing < 0 ? '' : source.slice(opening + 1, closing)
- const routePath = prefix + match[2]
+ const routePath = mountPrefix + routerPrefix + decorator.path
const pathParameters = new Set(
- Array.from(routePath.matchAll(/\{([^}]+)\}/g), (item) => item[1])
+ Array.from(routePath.matchAll(/\{([^}:]+)(?::[^}]+)?\}/g), (item) => item[1])
)
const query = new Map()
for (const parameter of splitTopLevel(signature)) {
@@ -95,7 +130,9 @@ for (const file of fs.readdirSync(routerDir).filter((name) => name.endsWith('.py
) continue
query.set(defaultMatch[1], false)
}
- routes.set(`${match[1].toUpperCase()} ${normalizePath(routePath)}`, { query, pathParameters })
+ for (const method of decorator.methods) {
+ routes.set(`${method} ${normalizePath(routePath)}`, { query, pathParameters })
+ }
}
}
@@ -123,6 +160,51 @@ const errors = []
let httpExamples = 0
let typescriptCalls = 0
const curlUrlPattern = String.raw`["']?https?:\/\/[^/\s"']+(\/[A-Za-z0-9_{}<>?=&./:-]+)`
+const detailCoverage = new Map(locales.map((locale) => [locale, new Set()]))
+
+function findRoute(method, documentedPath) {
+ const normalizedPath = normalizePath(documentedPath)
+ const exact = routes.get(`${method} ${normalizedPath}`)
+ if (exact) return exact
+ for (const [candidate, candidateContract] of routes) {
+ const separator = candidate.indexOf(' ')
+ const candidateMethod = candidate.slice(0, separator)
+ const candidatePath = candidate.slice(separator + 1)
+ if (candidateMethod !== method) continue
+ const placeholderPattern =
+ candidatePath.startsWith('/webdav/resources/{}') ||
+ candidatePath.startsWith('/api/v1/system/sync/{}')
+ ? '.+'
+ : '[^/]+'
+ const pattern = candidatePath
+ .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+ .replace(/\\\{\\\}/g, placeholderPattern)
+ if (new RegExp(`^${pattern}$`).test(normalizedPath)) return candidateContract
+ }
+ return undefined
+}
+
+function tableReferences(source) {
+ const references = []
+ for (const line of source.split(/\r?\n/)) {
+ if (!line.startsWith('|')) continue
+ const cells = line.split('|').slice(1, -1).map((cell) => cell.trim())
+ if (cells.length < 2) continue
+ const methodCell = cells[0].replaceAll('`', '')
+ const methods = Array.from(
+ methodCell.matchAll(new RegExp(`\\b(${httpMethods})\\b`, 'g')),
+ (match) => match[1]
+ )
+ const paths = Array.from(
+ cells[1].matchAll(/`(\/[A-Za-z0-9_{}./:-]+)`/g),
+ (match) => match[1]
+ )
+ for (const method of methods) {
+ for (const documentedPath of paths) references.push([method, documentedPath])
+ }
+ }
+ return references
+}
function curlReferences(source) {
const references = []
@@ -132,7 +214,7 @@ function curlReferences(source) {
if (!url) continue
const explicitMethod = command.match(
- /(?:-X|--request)\s+(GET|POST|PUT|PATCH|DELETE)\b/
+ new RegExp(`(?:-X|--request)\\s+(${httpMethods})\\b`)
)?.[1]
const method = explicitMethod ?? 'GET'
let documentedPath = url[1]
@@ -162,31 +244,27 @@ function curlReferences(source) {
for (const file of apiDocs) {
const source = fs.readFileSync(file, 'utf8')
const relative = path.relative(repoRoot, file)
+ const locale = relative.split(path.sep)[1]
const httpReferences = [
...Array.from(
- source.matchAll(/^\s*(GET|POST|PUT|PATCH|DELETE)\s+(\/[A-Za-z0-9_{}?=&./:-]+)/gm),
+ source.matchAll(
+ new RegExp(
+ `\\b(${httpMethods})\\s+((?:\\/api\\/|\\/webdav\\/|\\/bot\\/|\\/(?:health|ready|metrics)\\b)` +
+ `[A-Za-z0-9_{}?=&./:-]*)`,
+ 'g'
+ )
+ ),
(match) => [match[1], match[2]]
),
- ...curlReferences(source)
+ ...curlReferences(source),
+ ...tableReferences(source),
]
for (const [method, documentedPath] of httpReferences) {
const normalizedPath = normalizePath(documentedPath)
const route = `${method} ${normalizedPath}`
+ detailCoverage.get(locale).add(route)
httpExamples++
- let contract = routes.get(route)
- if (!contract) {
- for (const [candidate, candidateContract] of routes) {
- const [candidateMethod, candidatePath] = candidate.split(' ', 2)
- if (candidateMethod !== method) continue
- const pattern = candidatePath
- .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
- .replace(/\\\{\\\}/g, '[^/]+')
- if (new RegExp(`^${pattern}$`).test(normalizedPath)) {
- contract = candidateContract
- break
- }
- }
- }
+ const contract = findRoute(method, documentedPath)
if (!contract) {
errors.push(`${relative}: unknown HTTP route ${route}`)
continue
@@ -257,12 +335,109 @@ for (const file of apiDocs) {
}
}
+function routeIsCovered(route, coverage) {
+ if (coverage.has(route)) return true
+ const separator = route.indexOf(' ')
+ const method = route.slice(0, separator)
+ const routePath = route.slice(separator + 1)
+ const pattern = routePath
+ .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+ .replace(
+ /\\\{\\\}/g,
+ routePath.startsWith('/webdav/resources/{}') ||
+ routePath.startsWith('/api/v1/system/sync/{}')
+ ? '.+'
+ : '[^/]+'
+ )
+ for (const reference of coverage) {
+ const referenceSeparator = reference.indexOf(' ')
+ if (reference.slice(0, referenceSeparator) !== method) continue
+ if (new RegExp(`^${pattern}$`).test(reference.slice(referenceSeparator + 1))) return true
+ }
+ return false
+}
+
+const overviewCoverage = new Map()
+for (const file of overviewDocs) {
+ const source = fs.readFileSync(file, 'utf8')
+ const relative = path.relative(repoRoot, file)
+ const locale = relative.split(path.sep)[1]
+ const coverage = new Set()
+ for (const row of source.matchAll(
+ new RegExp(`^\\|\\s*(${httpMethods})(?:\\s*\\/\\s*(${httpMethods}))?\\s*\\|([^\\n]+)$`, 'gm')
+ )) {
+ const methods = [row[1], row[2]].filter(Boolean)
+ const documentedPaths = Array.from(
+ row[3].matchAll(/`(\/[A-Za-z0-9_{}./:-]+)`/g),
+ (match) => match[1]
+ )
+ for (const method of methods) {
+ for (const documentedPath of documentedPaths) {
+ const route = `${method} ${normalizePath(documentedPath)}`
+ coverage.add(route)
+ if (!findRoute(method, documentedPath)) {
+ errors.push(`${relative}: overview contains unknown HTTP route ${route}`)
+ }
+ }
+ }
+ }
+ overviewCoverage.set(locale, coverage)
+}
+
+for (const locale of locales) {
+ const overview = overviewCoverage.get(locale)
+ const details = detailCoverage.get(locale)
+ for (const route of routes.keys()) {
+ if (!routeIsCovered(route, overview)) {
+ errors.push(`docs/${locale}/api/01-overview.md: mounted route missing from overview: ${route}`)
+ }
+ if (!routeIsCovered(route, details)) {
+ errors.push(`docs/${locale}/api: mounted route has no detailed HTTP reference: ${route}`)
+ }
+ }
+ for (const route of overview) {
+ if (!routeIsCovered(route, details)) {
+ errors.push(`docs/${locale}/api: overview route has no detailed HTTP reference: ${route}`)
+ }
+ }
+}
+
+for (const file of allApiDocs) {
+ const source = fs.readFileSync(file, 'utf8')
+ const relative = path.relative(repoRoot, file)
+ for (const match of source.matchAll(
+ new RegExp(`^#{1,6}\\s+(Python SDK|TypeScript SDK|JavaScript SDK|Go SDK|HTTP API|CLI)[::]?\\s*$`, 'gm')
+ )) {
+ errors.push(
+ `${relative}:${source.slice(0, match.index).split('\\n').length}: ` +
+ `use a bold invocation label (${match[1]}) so examples render as tabs`
+ )
+ }
+ for (const match of source.matchAll(
+ /^\*\*(Python SDK|TypeScript SDK|JavaScript SDK|Go SDK|HTTP API|CLI)\*\*\s*[((]/gm
+ )) {
+ errors.push(
+ `${relative}:${source.slice(0, match.index).split('\n').length}: ` +
+ `put the ${match[1]} qualifier inside the bold label with ASCII parentheses`
+ )
+ }
+ for (const match of source.matchAll(
+ /^\*\*(Python SDK|TypeScript SDK|JavaScript SDK|Go SDK|HTTP API|CLI)\s*([^)]+)\*\*/gm
+ )) {
+ errors.push(
+ `${relative}:${source.slice(0, match.index).split('\n').length}: ` +
+ `use ASCII parentheses in the ${match[1]} invocation label`
+ )
+ }
+}
+
if (errors.length) {
console.error(errors.join('\n'))
process.exitCode = 1
} else {
console.log(
`API reference check passed: ${httpExamples} HTTP examples with query contracts, ` +
- `${typescriptCalls} TypeScript SDK calls with signature contracts`
+ `${typescriptCalls} TypeScript SDK calls with signature contracts, ` +
+ `${routes.size} mounted routes covered by overview and detail docs`
)
}
diff --git a/docs/zh/api/01-overview.md b/docs/zh/api/01-overview.md
index 4c2c195c2..a6a326275 100644
--- a/docs/zh/api/01-overview.md
+++ b/docs/zh/api/01-overview.md
@@ -391,221 +391,185 @@ JSON 输出 - 错误:
## API 端点总览
-以下是 OpenViking 提供的所有 HTTP API 端点,按功能模块分组:
+以下目录以服务端实际挂载路由为准。每组标题会跳转到详细文档;详细页只为真实存在的 HTTP、Python SDK、TypeScript SDK、Go SDK 或 CLI 能力显示对应 Tab,不会用等价的裸 HTTP 调用冒充 SDK。
-### 系统端点
-
-| 方法 | 路径 | 说明 | 认证 |
-|------|------|------|------|
-| GET | `/health` | 健康检查 | 无需认证 |
-| GET | `/ready` | 就绪探针(检查 AGFS、VectorDB、APIKeyManager) | 无需认证 |
-| GET | `/metrics` | Prometheus 指标导出 | 可选 |
-| GET | `/api/v1/system/status` | 系统状态 | 需要 |
-| POST | `/api/v1/system/wait` | 等待处理完成 | 需要 |
-| POST | `/api/v1/system/consistency` | 文件系统和向量索引一致性检查 | 需要 |
-
-### 资源端点
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| POST | `/api/v1/resources/temp_upload` | 临时文件上传(用于后续资源导入) |
-| POST | `/api/v1/resources` | 添加资源(支持 URL 或 temp_file_id) |
-
-### 技能端点
+### [系统状态](07-system.md)
| 方法 | 路径 | 说明 |
|------|------|------|
-| GET | `/api/v1/skills` | 列出已安装技能 |
-| POST | `/api/v1/skills` | 添加技能 |
-| POST | `/api/v1/skills/find` | 搜索已安装技能 |
-| POST | `/api/v1/skills/validate` | 校验技能 payload |
-| GET | `/api/v1/skills/{skill_name}` | 获取技能 |
-| PUT | `/api/v1/skills/{skill_name}` | 更新技能 |
-| DELETE | `/api/v1/skills/{skill_name}` | 删除技能 |
-
-### Watch 端点
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| GET | `/api/v1/watches` | 列出 watch,或按 `to_uri` 查询单个 watch |
-| GET | `/api/v1/watches/{task_id}` | 获取 watch |
-| PATCH | `/api/v1/watches` | 按 `to_uri` 更新 watch |
-| PATCH | `/api/v1/watches/{task_id}` | 按 task ID 更新 watch |
-| DELETE | `/api/v1/watches` | 按 `to_uri` 删除 watch |
-| DELETE | `/api/v1/watches/{task_id}` | 按 task ID 删除 watch |
-| POST | `/api/v1/watches/trigger` | 按 `to_uri` 触发 watch |
-| POST | `/api/v1/watches/{task_id}/trigger` | 按 task ID 触发 watch |
-
-### Pack 端点
-
-| 方法 | 路径 | 说明 | 权限 |
-|------|------|------|------|
-| POST | `/api/v1/pack/export` | 导出 .ovpack 文件 | ROOT/ADMIN/USER,受正常 URI ACL 限制 |
-| POST | `/api/v1/pack/import` | 导入 .ovpack 文件 | ROOT/ADMIN/USER,受正常 URI ACL 限制 |
-| POST | `/api/v1/pack/backup` | 备份公开 scope | ROOT/ADMIN |
-| POST | `/api/v1/pack/restore` | 恢复备份包 | ROOT/ADMIN |
-
-### 文件系统端点
+| GET | `/health` | 基础健康检查(无需认证) |
+| GET | `/ready` | AGFS、VectorDB 和 API Key 管理器就绪检查(无需认证) |
+| GET | `/api/v1/system/status` | 系统状态 |
+| POST | `/api/v1/system/wait` | 等待后台处理完成 |
+| POST | `/api/v1/system/consistency` | 文件系统与向量索引一致性检查 |
+| POST | `/api/v1/system/backend/sync-status` | 查询后端同步状态 |
+| POST | `/api/v1/system/backend/sync-retry` | 重试后端同步 |
+| GET | `/api/v1/system/sync/{sync_path}` | 路径形式的同步状态兼容接口 |
+| POST | `/api/v1/system/sync/{sync_path}/retry` | 路径形式的同步重试兼容接口 |
+
+### [资源](02-resources.md)与[文件系统](03-filesystem.md)
| 方法 | 路径 | 说明 |
|------|------|------|
-| GET | `/api/v1/fs/ls` | 列出目录内容 |
-| GET | `/api/v1/fs/tree` | 获取目录树结构 |
+| POST | `/api/v1/resources/temp_upload` | 上传后续导入所需的临时文件 |
+| POST | `/api/v1/resources` | 从 URL 或临时文件添加资源 |
+| GET | `/api/v1/fs/ls` | 列出目录 |
+| GET | `/api/v1/fs/tree` | 获取目录树 |
| GET | `/api/v1/fs/stat` | 获取资源状态 |
| GET | `/api/v1/fs/attrs` | 获取逻辑扩展属性 |
-| POST | `/api/v1/fs/attrs/set_tags` | 设置检索标签 |
+| POST | `/api/v1/fs/attrs/set_tags` | 设置检索标签(兼容别名) |
| POST | `/api/v1/fs/mkdir` | 创建目录 |
| DELETE | `/api/v1/fs` | 删除资源 |
-| POST | `/api/v1/fs/mv` | 移动/重命名资源 |
+| POST | `/api/v1/fs/mv` | 移动或重命名资源 |
-### 快照端点(多版本管理)
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| POST | `/api/v1/snapshot/commit` | 把当前工作区状态保存成新快照 |
-| GET | `/api/v1/snapshot/log` | 从最新提交开始回溯历史 |
-| GET | `/api/v1/snapshot/show` | 查看提交元数据,或读取提交中某个文件 |
-| GET | `/api/v1/snapshot/diff` | 对比某个文件在两个快照中的内容 |
-| POST | `/api/v1/snapshot/restore` | 恢复目录或整棵账号树到某个历史快照(正向提交) |
-
-### 内容端点
+### [内容](12-content.md)
| 方法 | 路径 | 说明 |
|------|------|------|
| 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` | 重新构建已有内容的语义/向量索引 |
-
-### 搜索端点
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| POST | `/api/v1/search/find` | 语义搜索(无会话上下文) |
-| POST | `/api/v1/search/search` | 上下文感知搜索(支持会话) |
-| POST | `/api/v1/search/grep` | 内容模式搜索 |
-| POST | `/api/v1/search/glob` | 文件模式匹配 |
+| GET | `/api/v1/content/download` | 下载原始文件字节 |
+| POST | `/api/v1/content/write` | 写入内容并刷新语义索引 |
+| POST | `/api/v1/content/set_tags` | 设置检索标签 |
+| POST | `/api/v1/content/reindex` | 重建语义或向量索引 |
-### 关系端点(实验特性,可能在后续版本中改变)
+### [技能](04-skills.md)
| 方法 | 路径 | 说明 |
|------|------|------|
-| GET | `/api/v1/relations` | 获取资源关联 |
-| POST | `/api/v1/relations/link` | 创建资源链接 |
-| DELETE | `/api/v1/relations/link` | 删除资源链接 |
+| GET | `/api/v1/skills` | 列出技能 |
+| POST | `/api/v1/skills` | 添加技能 |
+| POST | `/api/v1/skills/find` | 搜索技能 |
+| POST | `/api/v1/skills/validate` | 校验技能数据 |
+| GET | `/api/v1/skills/{skill_name}` | 获取技能 |
+| PUT | `/api/v1/skills/{skill_name}` | 更新技能 |
+| DELETE | `/api/v1/skills/{skill_name}` | 删除技能 |
-### 会话端点
+### [会话](05-sessions.md)与[记忆](16-memory.md)
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/sessions` | 创建会话 |
| GET | `/api/v1/sessions` | 列出会话 |
| GET | `/api/v1/sessions/{session_id}` | 获取会话 |
-| GET | `/api/v1/sessions/{session_id}/context` | 获取组装后的会话上下文 |
-| GET | `/api/v1/sessions/{session_id}/archives/{archive_id}` | 获取特定会话归档 |
+| GET | `/api/v1/sessions/{session_id}/tool-results` | 列出工具结果 |
+| GET | `/api/v1/sessions/{session_id}/tool-results/{tool_result_id}` | 读取工具结果 |
+| GET | `/api/v1/sessions/{session_id}/tool-results/{tool_result_id}/search` | 在工具结果内搜索 |
+| GET | `/api/v1/sessions/{session_id}/context` | 获取组装后的上下文 |
+| GET | `/api/v1/sessions/{session_id}/archives/{archive_id}` | 获取会话归档 |
| DELETE | `/api/v1/sessions/{session_id}` | 删除会话 |
-| POST | `/api/v1/sessions/{session_id}/commit` | 提交会话(归档并提取记忆) |
-| POST | `/api/v1/sessions/{session_id}/extract` | 从会话提取记忆 |
-| POST | `/api/v1/sessions/{session_id}/messages` | 添加消息 |
-| POST | `/api/v1/sessions/{session_id}/used` | 记录实际使用的上下文 / 技能 |
+| POST | `/api/v1/sessions/{session_id}/commit` | 归档会话并提取记忆 |
+| POST | `/api/v1/sessions/{session_id}/extract` | 提取记忆 |
+| POST | `/api/v1/sessions/{session_id}/messages` | 添加单条消息 |
+| POST | `/api/v1/sessions/{session_id}/messages/batch` | 批量添加消息 |
+| POST | `/api/v1/sessions/{session_id}/used` | 记录实际使用的上下文或技能 |
+| POST | `/api/v1/search/recall` | 召回记忆并返回可直接注入的上下文 |
-### 隐私配置
+### [检索](06-retrieval.md)、[代码检索](21-code.md)与[关系](13-relations.md)
| 方法 | 路径 | 说明 |
|------|------|------|
-| GET | `/api/v1/privacy-configs` | 列出隐私配置分类 |
-| GET | `/api/v1/privacy-configs/{category}` | 列出分类下目标 |
-| GET | `/api/v1/privacy-configs/{category}/{target_key}` | 获取当前生效配置(meta + current) |
-| POST | `/api/v1/privacy-configs/{category}/{target_key}` | 写入新版本并激活 |
-| GET | `/api/v1/privacy-configs/{category}/{target_key}/versions` | 列出版本号 |
-| GET | `/api/v1/privacy-configs/{category}/{target_key}/versions/{version}` | 获取指定版本详情 |
-| POST | `/api/v1/privacy-configs/{category}/{target_key}/activate` | 激活指定版本 |
+| POST | `/api/v1/search/find` | 语义搜索 |
+| POST | `/api/v1/search/search` | 上下文感知搜索 |
+| POST | `/api/v1/search/grep` | 内容模式搜索 |
+| POST | `/api/v1/search/glob` | 文件模式匹配 |
+| POST | `/api/v1/code/outline` | 提取代码结构 |
+| POST | `/api/v1/code/search` | 代码搜索 |
+| POST | `/api/v1/code/expand` | 展开代码上下文 |
+| GET | `/api/v1/relations` | 获取资源关系 |
+| POST | `/api/v1/relations/link` | 创建资源链接 |
+| DELETE | `/api/v1/relations/link` | 删除资源链接 |
+| POST | `/api/v1/relations/build_graph` | 构建关系图 |
-### 任务端点
+### [Watch](15-watches.md)、[快照](11-snapshot.md)与 [OVPack](14-ovpack.md)
| 方法 | 路径 | 说明 |
|------|------|------|
-| GET | `/api/v1/tasks/{task_id}` | 获取单个后台任务状态 |
-| GET | `/api/v1/tasks` | 列出后台任务(支持按类型、状态、资源过滤) |
-
-### 观测端点
+| GET | `/api/v1/watches` | 列出 watch,或按 `to_uri` 查询 |
+| GET | `/api/v1/watches/{task_id}` | 按任务 ID 获取 watch |
+| PATCH | `/api/v1/watches` | 按 `to_uri` 更新 watch |
+| PATCH | `/api/v1/watches/{task_id}` | 按任务 ID 更新 watch |
+| DELETE | `/api/v1/watches` | 按 `to_uri` 删除 watch |
+| DELETE | `/api/v1/watches/{task_id}` | 按任务 ID 删除 watch |
+| POST | `/api/v1/watches/trigger` | 按 `to_uri` 触发 watch |
+| POST | `/api/v1/watches/{task_id}/trigger` | 按任务 ID 触发 watch |
+| POST | `/api/v1/snapshot/commit` | 创建快照 |
+| GET | `/api/v1/snapshot/log` | 查看快照历史 |
+| POST | `/api/v1/snapshot/restore` | 恢复历史快照 |
+| GET | `/api/v1/snapshot/show` | 查看快照或其中的文件 |
+| GET | `/api/v1/snapshot/diff` | 对比快照 |
+| GET | `/api/v1/snapshot/ignore` | 读取快照忽略规则 |
+| PUT | `/api/v1/snapshot/ignore` | 替换快照忽略规则 |
+| DELETE | `/api/v1/snapshot/ignore` | 清空快照忽略规则 |
+| POST | `/api/v1/pack/export` | 导出 `.ovpack` |
+| POST | `/api/v1/pack/import` | 导入 `.ovpack` |
+| POST | `/api/v1/pack/backup` | 备份公开作用域 |
+| POST | `/api/v1/pack/restore` | 恢复备份包 |
+
+### [后台任务](17-tasks.md)、[运行观测](18-observer.md)与 [Metrics](09-metrics.md)
| 方法 | 路径 | 说明 |
|------|------|------|
-| GET | `/api/v1/observer/queue` | 队列系统状态 |
+| GET | `/api/v1/tasks/{task_id}` | 获取后台任务 |
+| GET | `/api/v1/tasks` | 列出后台任务 |
+| GET | `/api/v1/observer/queue` | 队列状态 |
| GET | `/api/v1/observer/vikingdb` | VikingDB 状态 |
-| 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` | 统计向量记录数量 |
+| GET | `/api/v1/observer/models` | 模型状态 |
+| GET | `/api/v1/observer/lock` | 锁状态 |
+| GET | `/api/v1/observer/retrieval` | 检索状态 |
+| GET | `/api/v1/observer/filesystem` | 文件系统状态 |
+| GET | `/api/v1/observer/system` | 聚合运行状态 |
+| GET | `/metrics` | Prometheus 指标 |
-### 统计端点
+### [管理员](08-admin.md)与[隐私配置](10-privacy.md)
| 方法 | 路径 | 说明 |
|------|------|------|
-| GET | `/api/v1/stats/memories` | 获取记忆健康统计(支持按类别过滤) |
-| GET | `/api/v1/stats/sessions/{session_id}` | 获取会话提取统计 |
-
-### 管理员端点(多租户)
-
-| 方法 | 路径 | 说明 | 权限 |
-|------|------|------|------|
-| POST | `/api/v1/admin/accounts` | 创建工作区 + 首个 admin | ROOT |
-| GET | `/api/v1/admin/accounts` | 列出所有工作区 | ROOT |
-| DELETE | `/api/v1/admin/accounts/{account_id}` | 删除工作区(级联清理数据) | ROOT |
-| POST | `/api/v1/admin/accounts/{account_id}/users` | 注册用户 | ROOT/ADMIN |
-| GET | `/api/v1/admin/accounts/{account_id}/users` | 列出用户 | ROOT/ADMIN |
-| DELETE | `/api/v1/admin/accounts/{account_id}/users/{user_id}` | 移除用户 | ROOT/ADMIN |
-| PUT | `/api/v1/admin/accounts/{account_id}/users/{user_id}/role` | 修改用户角色 | ROOT |
-| POST | `/api/v1/admin/accounts/{account_id}/users/{user_id}/key` | 重新生成 User Key | ROOT/ADMIN |
-
-### VikingBot 交互端点(可选)
-
-VikingBot API 需要服务器启动时指定 `--with-bot` 选项:
-
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| GET | `/health` | Bot 健康检查(与系统 /health 复用) |
-| POST | `/chat` | 发送消息给 Bot |
-| POST | `/chat/stream` | Bot 流式响应 |
+| POST | `/api/v1/admin/accounts` | 创建账号及首个管理员 |
+| GET | `/api/v1/admin/accounts` | 列出账号 |
+| POST | `/api/v1/admin/migrate` | 迁移旧版身份数据 |
+| DELETE | `/api/v1/admin/accounts/{account_id}` | 删除账号 |
+| POST | `/api/v1/admin/accounts/{account_id}/users` | 注册用户 |
+| GET | `/api/v1/admin/accounts/{account_id}/users` | 列出用户 |
+| DELETE | `/api/v1/admin/accounts/{account_id}/users/{user_id}` | 移除用户 |
+| PUT | `/api/v1/admin/accounts/{account_id}/users/{user_id}/role` | 修改用户角色 |
+| POST | `/api/v1/admin/accounts/{account_id}/users/{user_id}/key` | 重新生成用户 Key |
+| GET | `/api/v1/privacy-configs` | 列出隐私配置分类 |
+| GET | `/api/v1/privacy-configs/{category}` | 列出分类目标 |
+| GET | `/api/v1/privacy-configs/{category}/{target_key}` | 获取生效配置 |
+| GET | `/api/v1/privacy-configs/{category}/{target_key}/versions` | 列出配置版本 |
+| GET | `/api/v1/privacy-configs/{category}/{target_key}/versions/{version}` | 获取指定版本 |
+| POST | `/api/v1/privacy-configs/{category}/{target_key}` | 写入并激活新版本 |
+| POST | `/api/v1/privacy-configs/{category}/{target_key}/activate` | 激活指定版本 |
-### WebDAV 端点
+### [WebDAV](20-webdav.md) 与 [VikingBot API](24-vikingbot.md)
| 方法 | 路径 | 说明 |
|------|------|------|
-| OPTIONS | `/webdav/resources`, `/webdav/resources/{path}` | WebDAV 选项查询 |
-| PROPFIND | `/webdav/resources`, `/webdav/resources/{path}` | WebDAV 属性查询 |
-| GET/HEAD | `/webdav/resources/{path}` | 读取文件 |
-| PUT | `/webdav/resources/{path}` | 上传/创建文件(仅 UTF-8 文本) |
-| DELETE | `/webdav/resources/{path}` | 删除文件/目录 |
-| MKCOL | `/webdav/resources/{path}` | 创建目录 |
-| MOVE | `/webdav/resources/{path}` | 移动/重命名资源 |
+| OPTIONS | `/webdav/resources`、`/webdav/resources/{resource_path}` | 查询 WebDAV 能力 |
+| PROPFIND | `/webdav/resources`、`/webdav/resources/{resource_path}` | 查询资源属性 |
+| GET / HEAD | `/webdav/resources`、`/webdav/resources/{resource_path}` | 读取文件或目录 |
+| PUT | `/webdav/resources`、`/webdav/resources/{resource_path}` | 写入 UTF-8 文本文件 |
+| DELETE | `/webdav/resources`、`/webdav/resources/{resource_path}` | 删除文件或目录 |
+| MKCOL | `/webdav/resources`、`/webdav/resources/{resource_path}` | 创建目录 |
+| MOVE | `/webdav/resources`、`/webdav/resources/{resource_path}` | 移动或重命名资源 |
+| GET | `/bot/v1/health` | VikingBot 健康检查 |
+| POST | `/bot/v1/chat` | VikingBot 非流式对话 |
+| POST | `/bot/v1/chat/stream` | VikingBot 流式对话 |
+| POST | `/bot/v1/feedback` | 提交 VikingBot 回答反馈 |
---
## 文档阅读计划
-后续 API 文档按功能模块组织如下:
+左侧导航按职责而不是按历史文件体积组织:
-| 文档 | 内容 |
-|------|------|
-| [资源管理](02-resources.md) | 资源和技能的添加、导入、导出 |
-| [文件系统](03-filesystem.md) | 目录操作、内容读写 |
-| [多版本管理](11-snapshot.md) | 快照提交、历史回溯、单文件差异、版本恢复 |
-| [技能](04-skills.md) | 技能管理 API |
-| [会话管理](05-sessions.md) | 会话创建、消息管理、记忆提取 |
-| [检索](06-retrieval.md) | 搜索、关联、上下文获取 |
-| [系统](07-system.md) | 系统状态、监控、调试 API |
-| [隐私配置](10-privacy.md) | 隐私配置版本管理与切换 |
-| [指标与 Metrics](09-metrics.md) | Prometheus 指标导出与抓取说明 |
-| [管理员](08-admin.md) | 多租户账号和用户管理 |
+| 分组 | 适合查找的内容 |
+|------|----------------|
+| 核心数据 | 资源、内容、文件系统、技能、会话、记忆 |
+| 检索与关系 | 语义检索、代码检索、资源关系 |
+| 数据生命周期 | Watch、快照、OVPack |
+| 运维与观测 | 系统、任务、Observer、Metrics |
+| 身份与治理 | 管理员、隐私配置 |
+| 协议与扩展 | WebDAV、VikingBot API |
diff --git a/docs/zh/api/02-resources.md b/docs/zh/api/02-resources.md
index be41bf2d2..f3e0d8064 100644
--- a/docs/zh/api/02-resources.md
+++ b/docs/zh/api/02-resources.md
@@ -528,310 +528,9 @@ task_id uuid-xxx
---
-### Watch Management(监控任务管理)
+<a id="watch-management监控任务管理"></a>
-列出、查看、更新和触发通过 [`add_resource`](#add_resource) 配合 `watch_interval > 0` 创建的监控任务。控制面在 REST(`/api/v1/watches`)、`ov task watch` CLI 子命令组以及面向 Agent 的最小闭包 MCP 接口(`list_watches` / `cancel_watch`)三处镜像。
-
-#### 1. API 实现介绍
-
-此控制面封装了 `WatchManager` 原语,未改动任何服务端行为。每个端点和 CLI 命令都支持通过 `task_id`(路径)或 `to_uri`(查询参数)定位目标任务,两种键可以互换;如果同时提供,二者必须指向同一任务,否则返回 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` 可在不丢失配置周期的前提下暂停/恢复任务。
-- **删除**(`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),重新摄取在后台异步执行
-
-**代码入口**:
-- `openviking/server/routers/watches.py` — `/api/v1/watches` REST 路由
-- `crates/ov_cli/src/commands/watch.rs` — `ov task watch` CLI 子命令组
-- `openviking/server/mcp_endpoint.py` — MCP `list_watches` / `cancel_watch` 工具,以及 `add_resource` 上的 `watch_interval` / `to` 参数
-- `openviking/resource/watch_manager.py:WatchManager` — 任务持久化与调度原语
-
-#### 2. 接口和参数说明
-
-对每个单任务端点,路径中的 `{task_id}` 都可用查询参数 `?to_uri=` 替代。CLI 的 `<key>` 参数会自动分类:任何以 `viking://` 开头的值走 by-URI 路径,其他值视为 task_id(其它 scheme 如 `http://` 会在本地直接报错,避免静默 404)。
-
-**`PATCH /watches` 请求体**(字段均可选,至少需提供一个)
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| watch_interval | float | 新的检查周期(分钟),必须 `> 0`;如需暂停而保留周期请改用 `is_active=false`。 |
-| is_active | bool | 切换激活状态而保留配置周期(暂停 / 恢复)。 |
-| reason | string | 更新该监控任务的记录原因。 |
-| instruction | string | 更新语义处理指令。 |
-
-未识别字段会被 422 拒绝(`extra="forbid"`)。未传字段保留原值。
-
-#### 3. 使用示例
-
-**HTTP API**
-
-```bash
-# 列出活跃监控任务(去掉 ?active_only 可同时包含已暂停的任务)
-curl -s "http://localhost:1933/api/v1/watches?active_only=true" \
- -H "X-API-Key: your-key"
-
-# 暂停一个监控任务而保留其检查周期
-curl -X PATCH "http://localhost:1933/api/v1/watches/<task_id>" \
- -H "X-API-Key: your-key" -H "Content-Type: application/json" \
- -d '{"is_active": false}'
-
-# 触发一次立即刷新(fire-and-forget,立即返回,再次摄取在后台执行)
-curl -X POST "http://localhost:1933/api/v1/watches/<task_id>/trigger" \
- -H "X-API-Key: your-key"
-
-# 按 URI 而非 task_id 定位任务
-curl -X DELETE "http://localhost:1933/api/v1/watches?to_uri=viking://resources/guide.md" \
- -H "X-API-Key: your-key"
-```
-
-**Python SDK**
-
-```python
-watches = client.list_watches(active_only=True)
-client.update_watch(to_uri="viking://resources/guide.md", is_active=False)
-client.trigger_watch(to_uri="viking://resources/guide.md")
-client.delete_watch(to_uri="viking://resources/guide.md")
-```
-
-**Go SDK**
-
-```go
-watches, err := client.ListWatches(ctx, &openviking.ListWatchesOptions{
- ActiveOnly: true,
-})
-updated, err := client.UpdateWatch(ctx, openviking.UpdateWatchOptions{
- ToURI: "viking://resources/guide.md",
- IsActive: openviking.Bool(false),
-})
-triggered, err := client.TriggerWatch(ctx, openviking.WatchRef{
- ToURI: "viking://resources/guide.md",
-})
-deleted, err := client.DeleteWatch(ctx, openviking.WatchRef{
- ToURI: "viking://resources/guide.md",
-})
-_, _, _, _ = watches, updated, triggered, deleted
-```
-
-**CLI**(`ov task watch` 子命令)
-
-```bash
-# 列出活跃监控任务(去掉 --active-only 可同时包含已暂停的任务)
-ov task watch ls --active-only
-
-# 查看单个监控任务(key 可以是 viking:// URI 或 task_id)
-ov task watch show viking://resources/guide.md
-
-# 暂停 / 恢复,不丢失配置周期
-ov task watch pause viking://resources/guide.md
-ov task watch resume viking://resources/guide.md
-
-# 更新周期(或 --active / --reason / --instruction 的任意组合)
-ov task watch update viking://resources/guide.md --interval 30
-
-# 触发一次立即刷新(fire-and-forget)
-ov task watch trigger viking://resources/guide.md
-
-# 删除监控任务
-ov task watch rm viking://resources/guide.md
-```
-
-**MCP**(Agent 控制面——仅最小闭包)
-
-```text
-list_watches() # 每个任务一行;只暴露 URI,不暴露 task_id
-cancel_watch(to_uri="viking://resources/guide.md") # 按 URI 幂等删除
-```
-
-暂停 / 恢复 / 触发 / 更新故意不通过 MCP 暴露——这些 power-user 操作放在 CLI/REST 一侧,以保持 Agent 系统提示词的紧凑。Agent 侧若需创建监控任务或调整周期,仍走 [`add_resource`](#add_resource) 配合 `watch_interval`;可显式传 `to`,也可让系统绑定本次导入返回的 `root_uri`。
-
----
-
-### add_skill
-
-向知识库添加技能。
-
-#### 1. API 实现介绍
-
-技能是一种特殊的资源,用于定义智能体可以执行的操作或工具。
-
-**处理流程**:
-1. 接收技能数据或上传的临时文件
-2. 解析技能定义
-3. 存储到技能目录
-4. 如指定 `wait=true`,等待技能处理完成
-
-**代码入口**:
-- `openviking/client/local.py:LocalClient.add_skill` - SDK 入口(嵌入式)
-- `openviking_cli/client/http.py:AsyncHTTPClient.add_skill` - SDK 入口(HTTP)
-- `openviking/server/routers/resources.py:add_skill` - HTTP 路由
-- `openviking/service/resource_service.py` - 核心服务实现
-- `crates/ov_cli/src/handlers.rs:handle_add_skill` - CLI 处理
-
-#### 2. 接口和参数说明
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| data | Any | 否 | - | 内联技能内容或结构化数据。与 `temp_file_id` 二选一 |
-| temp_file_id | string | 否 | - | 临时上传文件 ID(通过 [temp_upload](#temp_upload) 获取)。与 `data` 二选一 |
-| target_uri | string | 否 | - | 技能添加根目录覆盖值。显式值优先于用户默认值和部署默认值 |
-| wait | bool | 否 | False | 是否等待技能处理完成 |
-| timeout | float | 否 | None | 超时时间(秒),仅 `wait=true` 时生效 |
-| telemetry | TelemetryRequest | 否 | False | 是否返回遥测数据 |
-
-未传 `target_uri` 时,服务端会先尝试使用当前用户的 `add_targets.skill_uri` 覆盖配置,
-再使用 `server.user_config_defaults.add_targets.skill_uri`。两者都没有配置时,保持旧行为,
-安装到当前用户的 skills 根。公共短写 `viking://user/skills` 会解析为
-`viking://user/{user_id}/skills`。v1 API 只允许 `viking://user/skills` 和
-`viking://agent/skills` 作为技能添加根目录。
-
-#### 3. 使用示例
-
-**HTTP API**
-
-```
-POST /api/v1/skills
-Content-Type: application/json
-```
-
-```bash
-# 使用内联数据
-curl -X POST http://localhost:1933/api/v1/skills \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d '{
- "data": {
- "name": "my-skill",
- "description": "My custom skill",
- "steps": []
- }
- }'
-
-# 使用本地文件(需先使用 temp_upload 上传)
-TEMP_FILE_ID=$(
- curl -s -X POST http://localhost:1933/api/v1/resources/temp_upload \
- -H "X-API-Key: your-key" \
- -F "file=@./skills/my-skill.json" \
- | jq -r '.result.temp_file_id'
-)
-
-curl -X POST http://localhost:1933/api/v1/skills \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d "{
- \"temp_file_id\": \"$TEMP_FILE_ID\"
- }"
-```
-
-**Python SDK**
-
-```python
-import openviking as ov
-
-client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-key")
-client.initialize()
-
-# 从本地文件添加技能
-result = client.add_skill("./skills/my-skill.json")
-
-# 等待处理完成
-client.wait_processed()
-```
-
-**TypeScript SDK**
-
-```typescript
-const task = await client.addSkill("./my-skill", { wait: true });
-console.log(task);
-```
-
-**Go SDK**
-
-```go
-result, err := client.AddSkill(ctx, "./skills/my-skill.json", &openviking.AddSkillOptions{
- Wait: true,
-})
-if err != nil {
- return err
-}
-fmt.Println(result["uri"])
-```
-
-**CLI**
-
-```bash
-# 添加技能
-ov add-skill ./skills/my-skill.json
-
-# 等待处理完成
-ov add-skill ./skills/my-skill.json --wait
-```
-
-#### 4. 响应示例
-
-**HTTP API 响应 (JSON)**
-
-```json
-{
- "status": "ok",
- "result": {
- "status": "success",
- "root_uri": "viking://user/alice/skills/my-skill",
- "uri": "viking://user/alice/skills/my-skill",
- "name": "my-skill",
- "auxiliary_files": 2,
- "queue_status": {
- "pending": 0,
- "processing": 0,
- "completed": 1
- }
- },
- "telemetry": {
- "operation_id": "550e8400-e29b-41d4-a716-446655440000"
- }
-}
-```
-
-**CLI 响应 (默认表格格式)**
-
-```
-Note: Skill is being processed in the background.
-Use 'ov wait' to wait for completion, or 'ov observer queue' to check status.
-status success
-root_uri viking://user/alice/skills/my-skill
-uri viking://user/alice/skills/my-skill
-name my-skill
-auxiliary_files 2
-```
-
-**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
-}
-```
-
-**字段说明**
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `status` | string | 处理状态:"success" 成功,"error" 失败 |
-| `root_uri` | string | 技能在 OpenViking 中的 canonical 最终 URI(同 `uri`) |
-| `uri` | string | 技能在 OpenViking 中的 canonical 最终 URI(同 `root_uri`) |
-| `name` | string | 技能名称 |
-| `auxiliary_files` | number | 技能附带的辅助文件数量 |
-| `queue_status` | object | (可选,仅当 `wait=true` 时)队列处理状态,包含 `pending`、`processing`、`completed` 计数 |
-
----
+<a id="add_skill"></a>
### temp_upload
diff --git a/docs/zh/api/03-filesystem.md b/docs/zh/api/03-filesystem.md
index 6a99e3610..7793b7a67 100644
--- a/docs/zh/api/03-filesystem.md
+++ b/docs/zh/api/03-filesystem.md
@@ -2,352 +2,11 @@
OpenViking 提供类 Unix 的文件系统操作来管理上下文。
-## WebDAV(Phase 1)
-
-OpenViking Server 也提供了一个面向资源文件的精简 WebDAV 适配层:
-
-```text
-/webdav/resources
-```
-
-Phase 1 有意把范围控制得比较小:
-
-- 仅开放 `resources` 命名空间,不暴露 memories、skills、sessions 等其他空间。
-- 以文本写入为主,当前 `PUT` 只接受 UTF-8 文本内容。
-- 只实现一小部分 WebDAV 方法:`OPTIONS`、`PROPFIND`、`GET`、`HEAD`、`PUT`、`DELETE`、`MKCOL`、`MOVE`。
-- 语义侧边文件和系统内部文件保持内部可见。`.abstract.md`、`.overview.md`、`.relations.json`、`.path.ovlock`、`.redirect.json`、`.sync_log.json` 这些派生或内部文件不会出现在 WebDAV 列表中,也不能被直接访问。
-
-行为说明:
-
-- 通过 WebDAV 新建文件时,会对该文件路径触发 OpenViking 的语义生成。
-- 通过 WebDAV 覆盖已有文件时,会像 `write()` 一样刷新相关语义和向量。
-- `PUT` 不会自动创建父目录。缺失的目录需要先用 `MKCOL` 创建。
-- 用户自己创建的点目录或点文件仍然可见,只有上面列出的保留内部文件名会被隐藏。
-- 启用多写存储时,被 redirect 到 backup 的文件仍会通过文件系统 API 呈现为普通文件;内部 redirect 和同步元数据不会暴露给调用方。
+<a id="webdav"></a><a id="webdav-phase-1"></a>
## API 参考
-### abstract()
-
-读取 L0 摘要(约 100 token 的概要)。
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| uri | str | 是 | - | Viking URI(必须是目录) |
-
-
-**Python SDK (Embedded / HTTP)**
-
-```python
-abstract = client.abstract("viking://resources/docs/")
-print(f"Abstract: {abstract}")
-# Output: "Documentation for the project API, covering authentication, endpoints..."
-```
-
-**TypeScript SDK**
-
-```typescript
-const abstract = await client.abstract("viking://resources/docs/");
-console.log(abstract);
-```
-
-**Go SDK**
-
-```go
-abstract, err := client.Abstract(ctx, "viking://resources/docs/")
-if err != nil {
- return err
-}
-fmt.Println(abstract)
-```
-
-**HTTP API**
-
-```
-GET /api/v1/content/abstract?uri={uri}
-```
-
-```bash
-curl -X GET "http://localhost:1933/api/v1/content/abstract?uri=viking://resources/docs/" \
- -H "X-API-Key: your-key"
-```
-
-**CLI**
-
-```bash
-openviking abstract viking://resources/docs/
-```
-
-
-**响应**
-
-```json
-{
- "status": "ok",
- "result": "Documentation for the project API, covering authentication, endpoints...",
- "time": 0.1
-}
-```
-
----
-
-### overview()
-
-读取 L1 概览,适用于目录。
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| uri | str | 是 | - | Viking URI(必须是目录) |
-
-
-**Python SDK (Embedded / HTTP)**
-
-```python
-overview = client.overview("viking://resources/docs/")
-print(f"Overview:\n{overview}")
-```
-
-**TypeScript SDK**
-
-```typescript
-const overview = await client.overview("viking://resources/docs/");
-console.log(overview);
-```
-
-**Go SDK**
-
-```go
-overview, err := client.Overview(ctx, "viking://resources/docs/")
-if err != nil {
- return err
-}
-fmt.Println(overview)
-```
-
-**HTTP API**
-
-```
-GET /api/v1/content/overview?uri={uri}
-```
-
-```bash
-curl -X GET "http://localhost:1933/api/v1/content/overview?uri=viking://resources/docs/" \
- -H "X-API-Key: your-key"
-```
-
-**CLI**
-
-```bash
-openviking overview viking://resources/docs/
-```
-
-
-**响应**
-
-```json
-{
- "status": "ok",
- "result": "## docs/\n\nContains API documentation and guides...",
- "time": 0.1
-}
-```
-
----
-
-### read()
-
-读取 L2 完整内容。
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| uri | str | 是 | - | Viking URI |
-| offset | int | 否 | 0 | 起始行号(0 开始) |
-| limit | int | 否 | -1 | 读取的行数,`-1` 表示读到结尾 |
-| raw | bool | 否 | false | 返回未过滤 MEMORY_FIELDS 的原始存储内容(仅 HTTP API,Python SDK 暂未暴露)。 |
-
-**说明**
-
-- `read()` 只接受文件 URI。传入已存在的目录 URI 时返回 `INVALID_ARGUMENT`(`400`),而不是 `NOT_FOUND`。该错误会携带结构化的 `details` 字段——`details.expected` 为 `"file"`,`details.actual` 为 `"directory"`,`details.resource` 为出错的 URI(HTTP 路径上会带上)——客户端据此即可以编程方式判断"文件 vs 目录"不匹配(例如回退到 `list`),而无需对错误消息做字符串匹配。
-- 公开 URI 参数接受 `resources` 和 `user` 作用域。访问 session 文件时,使用 `viking://user/{user_id}/sessions/{session_id}`,也可以使用向后兼容的 `viking://session/{session_id}` 别名。`temp`、`queue` 等内部作用域会返回 `INVALID_URI`。
-
-
-**Python SDK (Embedded / HTTP)**
-
-```python
-content = client.read("viking://resources/docs/api.md")
-print(f"Content:\n{content}")
-```
-
-**TypeScript SDK**
-
-```typescript
-const content = await client.read("viking://resources/docs/api.md", 0, -1);
-console.log(content);
-```
-
-**Go SDK**
-
-```go
-content, err := client.Read(ctx, "viking://resources/docs/api.md", 0, -1)
-if err != nil {
- return err
-}
-fmt.Println(content)
-```
-
-**HTTP API**
-
-```
-GET /api/v1/content/read?uri={uri}
-```
-
-```bash
-curl -X GET "http://localhost:1933/api/v1/content/read?uri=viking://resources/docs/api.md" \
- -H "X-API-Key: your-key"
-```
-
-**CLI**
-
-```bash
-openviking read viking://resources/docs/api.md
-```
-
-
-**响应**
-
-```json
-{
- "status": "ok",
- "result": "# API Documentation\n\nFull content of the file...",
- "time": 0.1
-}
-```
-
----
-
-### write()
-
-修改一个已存在的文件,或在 `mode="create"` 时创建新文件,并自动刷新相关语义与向量。
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| uri | str | 是 | - | 要写入的文件 URI。`mode="create"` 时目标文件必须不存在 |
-| content | str | 是 | - | 要写入的新内容 |
-| mode | str | 否 | `replace` | `replace`、`append` 或 `create` |
-| wait | bool | 否 | `false` | 是否等待后台语义/向量刷新完成 |
-| timeout | float | 否 | `null` | 当 `wait=true` 时的超时时间(秒) |
-
-**说明**
-
-- `replace` 和 `append` 要求文件已存在;`create` 仅用于创建新文件,目标路径已存在时返回 `409 Conflict`。目录始终会被拒绝。
-- `create` 只允许以下文本类扩展名:`.md`、`.txt`、`.json`、`.yaml`、`.yml`、`.toml`、`.py`、`.js`、`.ts`。父目录会自动创建。
-- 不允许直接写入派生语义文件:`.abstract.md`、`.overview.md`、`.relations.json`。
-- 文件内容会在 API 返回前完成更新;`wait` 只控制是否等待语义/向量刷新完成。
-- 公共 API 已不再接受 `regenerate_semantics` 或 `revectorize`;写入后一定会自动刷新相关语义与向量。
-
-
-**Python SDK (Embedded / HTTP)**
-
-```python
-result = client.write(
- "viking://resources/docs/api.md",
- "# Updated API\n\nFresh content.",
- mode="replace",
- wait=True,
-)
-print(result["root_uri"])
-```
-
-**TypeScript SDK**
-
-```typescript
-await client.write("viking://resources/docs/new.md", "# New document\n", { wait: true });
-```
-
-**Go SDK**
-
-```go
-result, err := client.Write(
- ctx,
- "viking://resources/docs/api.md",
- "# Updated API\n\nFresh content.",
- &openviking.WriteOptions{
- Mode: "replace",
- Wait: true,
- },
-)
-if err != nil {
- return err
-}
-fmt.Println(result["root_uri"])
-```
-
-**HTTP API**
-
-```
-POST /api/v1/content/write
-```
-
-```bash
-curl -X POST "http://localhost:1933/api/v1/content/write" \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d '{
- "uri": "viking://resources/docs/api.md",
- "content": "# Updated API\n\nFresh content.",
- "mode": "replace",
- "wait": true
- }'
-```
-
-**CLI**
-
-```bash
-openviking write viking://resources/docs/api.md \
- --content "# Updated API\n\nFresh content." \
- --wait
-```
-
-
-**响应**
-
-```json
-{
- "status": "ok",
- "result": {
- "uri": "viking://resources/docs/api.md",
- "root_uri": "viking://resources/docs",
- "context_type": "resource",
- "mode": "replace",
- "written_bytes": 29,
- "content_updated": true,
- "semantic_status": "complete",
- "vector_status": "complete",
- "queue_status": {
- "Semantic": {
- "processed": 1,
- "error_count": 0,
- "errors": []
- },
- "Embedding": {
- "processed": 2,
- "error_count": 0,
- "errors": []
- }
- }
- }
-}
-```
-
----
+<a id="abstract"></a><a id="overview"></a><a id="read"></a><a id="write"></a>
### ls()
@@ -1003,799 +662,11 @@ openviking mv viking://resources/old-name/ viking://resources/new-name/
}
```
----
-
-### grep()
-
-按模式搜索内容。
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| uri | str | 是 | - | 要搜索的 Viking URI |
-| pattern | str | 是 | - | 搜索模式(正则表达式) |
-| case_insensitive | bool | 否 | False | 忽略大小写 |
-| exclude_uri | str | 否 | None | 搜索时要排除的 URI 前缀 |
-| node_limit | int | 否 | 256 | 最大返回节点数。省略时默认使用 256;如需更多结果,请显式传入更大的整数 |
-| level_limit | int | 否 | Python SDK: 5;HTTP API / CLI / Go SDK: 10 | 最大目录遍历深度。Go SDK 当前使用 HTTP API 默认值。 |
-
-
-**Python SDK (Embedded / HTTP)**
-
-```python
-results = client.grep(
- "viking://resources/",
- "authentication",
- case_insensitive=True,
- node_limit=1024,
-)
-
-print(f"Found {results['count']} matches")
-for match in results['matches']:
- print(f" {match['uri']}:{match['line']}")
- print(f" {match['content']}")
-```
-
-**TypeScript SDK**
-
-```typescript
-const matches = await client.grep("viking://resources/docs/", "authentication");
-console.log(matches);
-```
+<a id="grep"></a><a id="glob"></a>
-**Go SDK**
+<a id="link"></a><a id="relations"></a><a id="unlink"></a>
-```go
-nodeLimit := 1024
-result, err := client.Grep(ctx, "viking://resources/", "authentication", &openviking.GrepOptions{
- CaseInsensitive: true,
- NodeLimit: &nodeLimit,
-})
-if err != nil {
- return err
-}
-fmt.Println(result["matches"])
-```
-
-**HTTP API**
-
-```
-POST /api/v1/search/grep
-```
-
-```bash
-curl -X POST http://localhost:1933/api/v1/search/grep \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d '{
- "uri": "viking://resources/",
- "pattern": "authentication",
- "case_insensitive": true
- }'
-```
-
-**CLI**
-
-```bash
-openviking grep "authentication" --uri viking://resources/ [--ignore-case]
-```
-
-
-**响应**
-
-```json
-{
- "status": "ok",
- "result": {
- "matches": [
- {
- "uri": "viking://resources/docs/auth.md",
- "line": 15,
- "content": "User authentication is handled by..."
- }
- ],
- "count": 1
- },
- "time": 0.1
-}
-```
-
----
-
-### glob()
-
-按模式匹配文件。
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| pattern | str | 是 | - | Glob 模式(例如 `**/*.md`) |
-| uri | str | 否 | "viking://" | 起始 URI |
-| node_limit | int | 否 | 256 | 最大返回匹配数。省略时默认使用 256;如需更多结果,请显式传入更大的整数 |
-
-
-**Python SDK (Embedded / HTTP)**
-
-```python
-# 查找所有 Markdown 文件
-results = client.glob("**/*.md", "viking://resources/")
-print(f"Found {results['count']} markdown files:")
-for uri in results['matches']:
- print(f" {uri}")
-
-# 查找所有 Python 文件
-results = client.glob("**/*.py", "viking://resources/")
-print(f"Found {results['count']} Python files")
-```
-
-**TypeScript SDK**
-
-```typescript
-const matches = await client.glob("**/*.md", "viking://resources/docs/");
-console.log(matches);
-```
-
-**Go SDK**
-
-```go
-result, err := client.Glob(ctx, "**/*.md", "viking://resources/", &openviking.GlobOptions{
- NodeLimit: openviking.Int(1024),
-})
-if err != nil {
- return err
-}
-fmt.Println(result["matches"])
-```
-
-**HTTP API**
-
-```
-POST /api/v1/search/glob
-```
-
-```bash
-curl -X POST http://localhost:1933/api/v1/search/glob \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d '{
- "pattern": "**/*.md",
- "uri": "viking://resources/"
- }'
-```
-
-**CLI**
-
-```bash
-openviking glob "**/*.md" [--uri viking://resources/]
-```
-
-
-**响应**
-
-```json
-{
- "status": "ok",
- "result": {
- "matches": [
- "viking://resources/docs/api.md",
- "viking://resources/docs/guide.md"
- ],
- "count": 2
- },
- "time": 0.1
-}
-```
-
----
-
-### link()
-
-创建资源之间的关联。
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| from_uri | str | 是 | - | 源 URI |
-| to_uris | str 或 List[str] | 是 | - | 目标 URI |
-| reason | str | 否 | "" | 关联原因 |
-
-
-**Python SDK (Embedded / HTTP)**
-
-```python
-# 单个关联
-client.link(
- "viking://resources/docs/auth/",
- "viking://resources/docs/security/",
- reason="Security best practices for authentication"
-)
-
-# 多个关联
-client.link(
- "viking://resources/docs/api/",
- [
- "viking://resources/docs/auth/",
- "viking://resources/docs/errors/"
- ],
- reason="Related documentation"
-)
-```
-
-**TypeScript SDK**
-
-```typescript
-await client.link(
- "viking://resources/docs/api/",
- [
- "viking://resources/docs/auth/",
- "viking://resources/docs/errors/",
- ],
- "Related documentation",
-);
-```
-
-**HTTP API**
-
-```
-POST /api/v1/relations/link
-```
-
-```bash
-# 单个关联
-curl -X POST http://localhost:1933/api/v1/relations/link \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d '{
- "from_uri": "viking://resources/docs/auth/",
- "to_uris": "viking://resources/docs/security/",
- "reason": "Security best practices for authentication"
- }'
-
-# 多个关联
-curl -X POST http://localhost:1933/api/v1/relations/link \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d '{
- "from_uri": "viking://resources/docs/api/",
- "to_uris": ["viking://resources/docs/auth/", "viking://resources/docs/errors/"],
- "reason": "Related documentation"
- }'
-```
-
-**CLI**
-
-```bash
-openviking link viking://resources/docs/auth/ viking://resources/docs/security/ --reason "Security best practices"
-```
-
-
-**响应**
-
-```json
-{
- "status": "ok",
- "result": {
- "from": "viking://resources/docs/auth/",
- "to": "viking://resources/docs/security/"
- },
- "time": 0.1
-}
-```
-
----
-
-### relations()
-
-获取资源的关联关系。
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| uri | str | 是 | - | Viking URI |
-
-
-**Python SDK (Embedded / HTTP)**
-
-```python
-relations = client.relations("viking://resources/docs/auth/")
-for rel in relations:
- print(f"Related: {rel['uri']}")
- print(f" Reason: {rel['reason']}")
-```
-
-**TypeScript SDK**
-
-```typescript
-const relations = await client.relations("viking://resources/docs/auth/");
-console.log(relations);
-```
-
-**HTTP API**
-
-```
-GET /api/v1/relations?uri={uri}
-```
-
-```bash
-curl -X GET "http://localhost:1933/api/v1/relations?uri=viking://resources/docs/auth/" \
- -H "X-API-Key: your-key"
-```
-
-**CLI**
-
-```bash
-openviking relations viking://resources/docs/auth/
-```
-
-
-**响应**
-
-```json
-{
- "status": "ok",
- "result": [
- {"uri": "viking://resources/docs/security/", "reason": "Security best practices"},
- {"uri": "viking://resources/docs/errors/", "reason": "Error handling"}
- ],
- "time": 0.1
-}
-```
-
----
-
-### unlink()
-
-移除关联关系。
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| from_uri | str | 是 | - | 源 URI |
-| to_uri | str | 是 | - | 要取消关联的目标 URI |
-
-
-**Python SDK (Embedded / HTTP)**
-
-```python
-client.unlink(
- "viking://resources/docs/auth/",
- "viking://resources/docs/security/"
-)
-```
-
-**TypeScript SDK**
-
-```typescript
-await client.unlink(
- "viking://resources/docs/auth/",
- "viking://resources/docs/security/",
-);
-```
-
-**HTTP API**
-
-```
-DELETE /api/v1/relations/link
-```
-
-```bash
-curl -X DELETE http://localhost:1933/api/v1/relations/link \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d '{
- "from_uri": "viking://resources/docs/auth/",
- "to_uri": "viking://resources/docs/security/"
- }'
-```
-
-**CLI**
-
-```bash
-openviking unlink viking://resources/docs/auth/ viking://resources/docs/security/
-```
-
-
-**响应**
-
-```json
-{
- "status": "ok",
- "result": {
- "from": "viking://resources/docs/auth/",
- "to": "viking://resources/docs/security/"
- },
- "time": 0.1
-}
-```
-
----
-
-### export_ovpack
-
-将资源树导出为 `.ovpack` 文件。
-
-#### 1. API 实现介绍
-
-将指定 URI 下的所有资源打包成 `.ovpack` 格式文件,用于备份或迁移。ROOT、ADMIN 和 USER 角色均可使用,仍受常规 URI 访问控制约束。
-
-**处理流程**:
-1. 验证用户权限
-2. 遍历指定 URI 下的资源
-3. 写入内容文件和 OVPack manifest
-4. 打包成 zip 格式(.ovpack)
-5. 以文件流形式返回
-
-**格式说明**:
-- 导出的 ZIP 会把用户内容原样放在 `<root>/files/` 下,并把内部元数据放在 `<root>/_ovpack/` 下。
-- manifest 位于 `<root>/_ovpack/manifest.json`。
-- `entries[].path` 是相对导出 root 的路径;`""` 表示 root 目录本身。
-- 文件条目包含 `size` 和 `sha256`;`content_sha256` 覆盖按路径排序后的文件列表(`path`、`size`、`sha256`)。
-- `_ovpack/index_records.jsonl` 保存可迁移的索引标量。`include_vectors=true` 时,`_ovpack/dense.f32` 保存纯 dense float32 向量快照和 embedding 元数据;底层 `VectorIndex.IndexType` 为 hybrid 时不支持向量快照导出。
-- `id`、`uri`、`account_id`、`created_at`、`updated_at`、`active_count` 等运行态字段会在目标环境重新生成,不从包内恢复。
-- OVPack 不额外设置包大小、文件数量或目录深度上限;实际可处理规模由 ZIP、存储后端和运行环境决定。
-
-**代码入口**:
-- `openviking/server/routers/pack.py:export_ovpack` - HTTP 路由
-- `openviking/service/pack_service.py` - 核心服务实现
-- `crates/ov_cli/src/handlers.rs:handle_export` - CLI 处理
-
-#### 2. 接口和参数说明
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| uri | string | 是 | - | 要导出的 Viking URI |
-| include_vectors | boolean | 否 | false | 导出纯 dense 向量快照;底层 index type 为 hybrid 时会拒绝 |
-
-**权限要求**:ROOT、ADMIN 或 USER
-
-#### 3. 使用示例
-
-
-**HTTP API**
-
-```
-POST /api/v1/pack/export
-Content-Type: application/json
-```
-
-```bash
-curl -X POST http://localhost:1933/api/v1/pack/export \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-admin-key" \
- -d '{
- "uri": "viking://resources/my-project/",
- "include_vectors": false
- }' \
- --output my-project.ovpack
-```
-
-**Python SDK**
-
-```python
-import openviking as ov
-
-client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-admin-key")
-client.initialize()
-
-# 导出到本地文件(HTTP SDK 会自动处理下载)
-# 注意:导出功能主要通过 CLI 使用
-```
-
-**TypeScript SDK**
-
-```typescript
-const outputPath = await client.exportOVPack(
- "viking://resources/docs/",
- "./exports/docs.ovpack",
- true,
-);
-console.log(outputPath);
-```
-
-**Go SDK**
-
-```go
-outPath, err := client.ExportOVPack(
- ctx,
- "viking://resources/my-project/",
- "./exports/my-project.ovpack",
- &openviking.PackOptions{IncludeVectors: false},
-)
-if err != nil {
- return err
-}
-fmt.Println(outPath)
-```
-
-**CLI**
-
-```bash
-# 导出资源
-ov export viking://resources/my-project/ ./exports/my-project.ovpack
-
-# 导出 dense 向量快照
-ov export viking://resources/my-project/ ./exports/my-project.ovpack --include-vectors
-```
-
-
-**响应示例**
-
-此接口直接返回文件流(`Content-Type: application/zip`),不返回 JSON 包装体。
-
----
-
-### import_ovpack
-
-导入 `.ovpack` 文件。
-
-#### 1. API 实现介绍
-
-将 `.ovpack` 文件导入到指定位置,用于恢复或迁移数据。ROOT、ADMIN 和 USER 角色均可使用,仍受常规 URI 访问控制约束。
-
-**处理流程**:
-1. 验证用户权限
-2. 解析上传的 `.ovpack` 文件
-3. 校验 manifest 元数据、路径、文件和目录集合、文件大小和 checksum
-4. 应用 `on_conflict`
-5. 导入资源到目标位置,并重建向量
-
-**代码入口**:
-- `openviking/server/routers/pack.py:import_ovpack` - HTTP 路由
-- `openviking/service/pack_service.py` - 核心服务实现
-- `crates/ov_cli/src/handlers.rs:handle_import` - CLI 处理
-
-#### 2. 接口和参数说明
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| temp_file_id | string | 是 | - | 临时上传文件 ID(通过 [temp_upload](02-resources.md#temp_upload) 获取) |
-| parent | string | 是 | - | 目标父级 URI(导入到此处) |
-| on_conflict | string | 否 | fail | 冲突策略:`fail`、`overwrite` 或 `skip` |
-| vector_mode | string | 否 | auto | 向量处理方式:`auto`、`recompute` 或 `require` |
-
-**权限要求**:ROOT、ADMIN 或 USER
-
-**行为说明**:
-- API 已不再接受 `vectorize` 或 `force`。
-- `vector_mode=auto` 会在存在兼容 dense 快照时直接恢复,否则重新向量化;`recompute` 总是忽略包内向量;`require` 要求必须存在兼容 dense 快照,否则导入失败。
-- dense 快照兼容性会比较 embedding provider、model、input、query/document 参数和维度。
-- Session 文件属于 user 命名空间(`viking://user/{user_id}/sessions/...`),恢复后不触发向量化。
-- `on_conflict=fail` 且目标 root 已存在时,会返回结构化的 `409 CONFLICT`。
-- `on_conflict=overwrite` 会替换已有目标 root。`on_conflict=skip` 会保留已有目标 root,并直接返回该路径,不写入包内容。`skip` 是 root 级跳过,不是文件级补齐。
-- 默认拒绝没有 manifest 的包,因为这类包无法提供内容完整性校验。
-- 带 manifest entries 的包如果缺少内容文件或目录、混入额外文件或目录、文件大小不同、单文件 `sha256` 不同,或整体 `content_sha256` 缺失/不匹配,都会被拒绝导入。
-- manifest `format_version` 不是当前支持版本(`3`)的包会被拒绝。
-- `.abstract.md` 和 `.overview.md` 会作为语义侧边文件恢复;`.relations.json` 和 OVPack 内部文件会被排除。
-- manifest index 标量中的 `context_type` 如果存在,必须和最终导入路径语义一致。
-- `viking://resources/` 这类顶级 scope 包必须导入到 `viking://`。
-- OVPack 不额外设置导入包大小、文件数量或目录深度上限;实际可处理规模由 ZIP、存储后端和运行环境决定。
-
-#### 3. 使用示例
-
-
-**HTTP API**
-
-```
-POST /api/v1/pack/import
-Content-Type: application/json
-```
-
-```bash
-# 第一步:上传 .ovpack 文件
-TEMP_FILE_ID=$(
- curl -s -X POST http://localhost:1933/api/v1/resources/temp_upload \
- -H "X-API-Key: your-admin-key" \
- -F "file=@./exports/my-project.ovpack" \
- | jq -r '.result.temp_file_id'
-)
-
-# 第二步:导入
-curl -X POST http://localhost:1933/api/v1/pack/import \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-admin-key" \
- -d "{
- \"temp_file_id\": \"$TEMP_FILE_ID\",
- \"parent\": \"viking://resources/imported/\",
- \"on_conflict\": \"overwrite\",
- \"vector_mode\": \"auto\"
- }"
-```
-
-**Python SDK**
-
-```python
-import openviking as ov
-
-client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-admin-key")
-client.initialize()
-
-# 导入 .ovpack 文件(HTTP SDK 会自动处理上传)
-# 注意:导入功能主要通过 CLI 使用
-```
-
-**TypeScript SDK**
-
-```typescript
-const uri = await client.importOVPack(
- "./exports/docs.ovpack",
- "viking://resources/",
- {
- onConflict: "overwrite",
- vectorMode: "auto",
- },
-);
-console.log(uri);
-```
-
-**Go SDK**
-
-```go
-uri, err := client.ImportOVPack(
- ctx,
- "./exports/my-project.ovpack",
- "viking://resources/imported/",
- &openviking.ImportPackOptions{
- OnConflict: "overwrite",
- VectorMode: "auto",
- },
-)
-if err != nil {
- return err
-}
-fmt.Println(uri)
-```
-
-**CLI**
-
-```bash
-# 导入 .ovpack 文件
-ov import ./exports/my-project.ovpack viking://resources/imported/
-
-# 显式冲突策略
-ov import ./exports/my-project.ovpack viking://resources/imported/ --on-conflict overwrite
-
-# 要求恢复兼容 dense 向量快照
-ov import ./exports/my-project.ovpack viking://resources/imported/ --vector-mode require
-```
-
-
-**响应示例**
-
-```json
-{
- "status": "ok",
- "result": {
- "uri": "viking://resources/imported/my-project/"
- },
- "telemetry": {
- "operation_id": "550e8400-e29b-41d4-a716-446655440000"
- }
-}
-```
-
-**冲突错误示例**
-
-```json
-{
- "status": "error",
- "error": {
- "code": "CONFLICT",
- "message": "Resource already exists at viking://resources/imported/my-project. Use on_conflict='overwrite' to replace it.",
- "details": {
- "resource": "viking://resources/imported/my-project"
- }
- }
-}
-```
-
----
-
-### backup_ovpack
-
-将公开 scope root 备份为只能通过 restore 恢复的 `.ovpack` 文件。备份包含
-`resources` 和 `user`;session 会通过 user 命名空间下的 `user/{user_id}/sessions`
-一起包含,不包含 `temp`、`queue` 等内部运行态数据。
-设置 `include_vectors=true` 时,会额外导出兼容的纯 dense 向量快照;底层 index type 为 hybrid 时会拒绝导出向量快照。
-
-```
-POST /api/v1/pack/backup
-```
-
-```bash
-curl -X POST http://localhost:1933/api/v1/pack/backup \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-admin-key" \
- -d '{"include_vectors":false}' \
- --output openviking-backup.ovpack
-```
-
-Go SDK:
-
-```go
-outPath, err := client.BackupOVPack(
- ctx,
- "./backups/openviking.ovpack",
- &openviking.PackOptions{IncludeVectors: true},
-)
-if err != nil {
- return err
-}
-fmt.Println(outPath)
-```
-
-CLI:
-
-```bash
-ov backup ./backups/openviking.ovpack
-ov backup ./backups/openviking.ovpack --include-vectors
-```
-
----
-
-### restore_ovpack
-
-恢复 `backup_ovpack` 生成的备份包到原始公开 scope root。普通 import 不接受备份包。
-向量处理遵循 `vector_mode`;user 命名空间下的 session 文件只恢复文件状态,不触发向量化。
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| temp_file_id | string | 是 | - | 临时上传文件 ID |
-| on_conflict | string | 否 | fail | 冲突策略:`fail`、`overwrite` 或 `skip` |
-| vector_mode | string | 否 | auto | 向量处理方式:`auto`、`recompute` 或 `require` |
-
-```
-POST /api/v1/pack/restore
-Content-Type: application/json
-```
-
-```bash
-TEMP_FILE_ID=$(
- curl -s -X POST http://localhost:1933/api/v1/resources/temp_upload \
- -H "X-API-Key: your-admin-key" \
- -F "file=@./backups/openviking.ovpack" \
- | jq -r '.result.temp_file_id'
-)
-
-curl -X POST http://localhost:1933/api/v1/pack/restore \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-admin-key" \
- -d "{\"temp_file_id\":\"$TEMP_FILE_ID\",\"on_conflict\":\"overwrite\",\"vector_mode\":\"auto\"}"
-```
-
-Go SDK:
-
-```go
-uri, err := client.RestoreOVPack(
- ctx,
- "./backups/openviking.ovpack",
- &openviking.ImportPackOptions{
- OnConflict: "overwrite",
- VectorMode: "require",
- },
-)
-if err != nil {
- return err
-}
-fmt.Println(uri)
-```
-
-CLI:
-
-```bash
-ov restore ./backups/openviking.ovpack --on-conflict overwrite
-ov restore ./backups/openviking.ovpack --on-conflict overwrite --vector-mode require
-```
-
----
+<a id="export_ovpack"></a><a id="import_ovpack"></a><a id="backup_ovpack"></a><a id="restore_ovpack"></a>
## 相关文档
diff --git a/docs/zh/api/04-skills.md b/docs/zh/api/04-skills.md
index f71c2012f..5385796ba 100644
--- a/docs/zh/api/04-skills.md
+++ b/docs/zh/api/04-skills.md
@@ -577,10 +577,24 @@ _, _ = validated, updated
**HTTP API**:
```bash
+# 校验技能数据
curl -X POST http://localhost:1933/api/v1/skills/validate \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{"data": {"name": "search-web", "description": "..."}}'
+
+# 使用新的技能内容替换现有技能
+curl -X PUT http://localhost:1933/api/v1/skills/search-web \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "data": {
+ "name": "search-web",
+ "description": "Search the web for current information",
+ "content": "# search-web\n\nUpdated instructions."
+ },
+ "wait": true
+ }'
```
### 删除技能
@@ -611,6 +625,82 @@ curl -X DELETE "http://localhost:1933/api/v1/skills/old-skill" \
-H "X-API-Key: your-key"
```
+### 技能管理响应
+
+列出和搜索都返回 `skills` 数组与 `total`。未指定 `target_uri` 时使用 `root_uris` 表示用户私有与 Agent 共享两个检索根;指定后返回单个 `root_uri`。
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "root_uris": [
+ "viking://user/default/skills",
+ "viking://agent/skills"
+ ],
+ "skills": [
+ {
+ "type": "skill",
+ "name": "search-web",
+ "uri": "viking://user/default/skills/search-web",
+ "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",
+ "tags": [],
+ "allowed_tools": [],
+ "score": 0.87,
+ "match_reason": "semantic",
+ "level": 0
+ }
+ ],
+ "total": 1
+ }
+}
+```
+
+读取单个技能时,`result` 返回上述技能元数据,并按 `level` 与 `include_*` 参数补充 `abstract`、`overview`、`content`、`files` 和 `source`。
+
+校验返回 `valid`、`strict`、规范化后的元数据、`body_lines`、`errors` 和 `warnings`。校验不通过时仍返回成功响应包,但 `valid=false`:
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "valid": false,
+ "strict": false,
+ "name": "search-web",
+ "description": "",
+ "tags": [],
+ "allowed_tools": [],
+ "body_lines": 0,
+ "errors": [
+ {
+ "rule": "description_required",
+ "message": "description is required",
+ "field": "description"
+ }
+ ],
+ "warnings": []
+ }
+}
+```
+
+更新成功时返回与 `add_skill` 相同的处理结果,并额外包含 `"action": "update"`。删除成功返回:
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "name": "old-skill",
+ "uri": "viking://user/default/skills/old-skill",
+ "root_uri": "viking://user/default/skills/old-skill",
+ "estimated_deleted_count": 4,
+ "privacy_deleted": false
+ }
+}
+```
+
+`estimated_deleted_count` 仅在底层文件系统提供删除数量估算时出现。
+
## 最佳实践
### 清晰的描述
diff --git a/docs/zh/api/05-sessions.md b/docs/zh/api/05-sessions.md
index d0ada4ff7..ac0006937 100644
--- a/docs/zh/api/05-sessions.md
+++ b/docs/zh/api/05-sessions.md
@@ -1,4 +1,4 @@
-# 会话和记忆管理
+# 会话
会话用于管理对话状态、跟踪上下文使用情况,并提取长期记忆。会话采用分层存储(L0/L1/L2)来优化 token 使用:
- L0(abstract): 会话概览摘要
@@ -350,6 +350,145 @@ ov session get a1b2c3d4
---
+### list_tool_results()
+
+列出会话中因体积较大而外置保存的工具结果。
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `session_id` | string | 是 | - | 会话 ID |
+| `tool_name` | string | 否 | - | 按工具名过滤 |
+| `limit` | integer | 否 | `50` | 最大返回数量 |
+
+**HTTP API**
+
+```http
+GET /api/v1/sessions/{session_id}/tool-results
+```
+
+```bash
+curl --get http://localhost:1933/api/v1/sessions/session-id/tool-results \
+ -H "X-API-Key: your-key" \
+ --data-urlencode "tool_name=search" \
+ --data-urlencode "limit=50"
+```
+
+**响应示例**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "tool_results": [
+ {
+ "tool_result_id": "tr_search_a1b2c3",
+ "tool_name": "search",
+ "original_chars": 48210,
+ "preview_chars": 2000,
+ "mime_type": "text/plain",
+ "synopsis_kind": "text",
+ "storage_uri": "viking://user/default/sessions/session-id/tool-results/tr_search_a1b2c3",
+ "offset_unit": "unicode_code_point"
+ }
+ ]
+ }
+}
+```
+
+### read_tool_result()
+
+按 Unicode 字符范围读取一个外置工具结果。
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `session_id` | string | 是 | - | 会话 ID |
+| `tool_result_id` | string | 是 | - | 工具结果 ID |
+| `offset` | integer | 否 | `0` | 起始字符位置 |
+| `limit` | integer | 否 | `20000` | 最大字符数;`-1` 表示读取到结尾 |
+| `include_metadata` | boolean | 否 | `true` | 是否返回元数据 |
+
+**HTTP API**
+
+```http
+GET /api/v1/sessions/{session_id}/tool-results/{tool_result_id}
+```
+
+```bash
+curl --get http://localhost:1933/api/v1/sessions/session-id/tool-results/tool-result-id \
+ -H "X-API-Key: your-key" \
+ --data-urlencode "offset=0" \
+ --data-urlencode "limit=20000"
+```
+
+**响应示例**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "tool_result_id": "tr_search_a1b2c3",
+ "content": "工具返回的文本片段……",
+ "offset": 0,
+ "limit": 20000,
+ "offset_unit": "unicode_code_point",
+ "total_chars": 48210,
+ "has_more": true,
+ "metadata": {
+ "tool_name": "search",
+ "mime_type": "text/plain",
+ "sha256": "..."
+ }
+ }
+}
+```
+
+`include_metadata=false` 时省略 `metadata`。继续读取时,将下一次请求的 `offset` 设为当前 `offset` 加上 `content` 的 Unicode 字符数。
+
+### search_tool_result()
+
+在一个外置工具结果中搜索文本,并返回命中位置附近的上下文。
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `q` | string | 是 | - | 搜索文本 |
+| `limit` | integer | 否 | `20` | 最大命中数 |
+| `context_chars` | integer | 否 | `300` | 每个命中前后的上下文字符数 |
+
+**HTTP API**
+
+```http
+GET /api/v1/sessions/{session_id}/tool-results/{tool_result_id}/search?q={query}
+```
+
+```bash
+curl --get http://localhost:1933/api/v1/sessions/session-id/tool-results/tool-result-id/search \
+ -H "X-API-Key: your-key" \
+ --data-urlencode "q=authentication" \
+ --data-urlencode "limit=20"
+```
+
+**响应示例**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "tool_result_id": "tr_search_a1b2c3",
+ "matches": [
+ {
+ "offset": 1284,
+ "offset_unit": "unicode_code_point",
+ "snippet": "...authentication failed because..."
+ }
+ ]
+ }
+}
+```
+
+外置工具结果端点当前由 Server 和 Web Studio 使用,公共 SDK 与 CLI 暂未提供封装,因此以上小节只展示 HTTP Tab。
+
+---
+
### get_session_context()
#### 1. API 实现介绍
@@ -1191,226 +1330,7 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/extract \
该接口会直接返回本次提取产生的记忆写入结果列表。列表项的具体结构取决于该会话实际提取出了哪些记忆。
----
-
-### get_task()
-
-#### 1. API 实现介绍
-
-查询返回 `task_id` 的后台任务状态,例如 session commit、`add_resource` 和 admin reindex。
-
-**任务状态**:
-- `pending`: 任务等待执行
-- `running`: 任务执行中
-- `completed`: 任务成功完成
-- `failed`: 任务失败
-
-**代码入口**:
-- `openviking/server/routers/tasks.py:get_task()` - HTTP 路由
-
-任务记录会持久化到 AGFS,服务重启后仍可查询,但仍受任务保留清理策略影响。
-
-#### 2. 接口和参数说明
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| task_id | str | 是 | - | 后台 API 返回的任务 ID |
-
-#### 3. 使用示例
-
-**HTTP API**
-
-```http
-GET /api/v1/tasks/{task_id}
-```
-
-```bash
-curl -X GET http://localhost:1933/api/v1/tasks/uuid-xxx \
- -H "X-API-Key: your-key"
-```
-
-**Python SDK**
-
-```python
-import openviking as ov
-
-client = ov.Client(base_url="http://localhost:1933", api_key="your-key")
-
-task = await client.get_task(task_id="uuid-xxx")
-print(f"Status: {task['status']}")
-```
-
-**TypeScript SDK**
-
-```typescript
-console.log(await client.getTask("task-id"));
-```
-
-**Go SDK**
-
-```go
-task, err := client.GetTask(ctx, "uuid-xxx")
-if err != nil {
- return err
-}
-if task != nil {
- fmt.Println(task["status"])
-}
-```
-
-**响应示例(资源导入进行中)**
-
-```json
-{
- "status": "ok",
- "result": {
- "task_id": "uuid-xxx",
- "task_type": "add_resource",
- "status": "running",
- "resource_id": "viking://resources/guide",
- "stage": "processing_queue"
- }
-}
-```
-
-`stage` 可以为 `null`。Git 仓库资源导入任务可能报告 `queued`、`fetching`、`parsing`、`finalizing`、`processing_queue`;其他任务类型可能将其留空。实时队列计数不会出现在任务状态中;需要实时数量时使用 observer queue,任务完成后可读取 `result.queue_status`。
-
-**响应示例(完成)**
-
-```json
-{
- "status": "ok",
- "result": {
- "task_id": "uuid-xxx",
- "task_type": "session_commit",
- "status": "completed",
- "result": {
- "session_id": "a1b2c3d4",
- "archive_uri": "viking://user/alice/sessions/a1b2c3d4/history/archive_001",
- "memory_diff_uri": "viking://user/alice/sessions/a1b2c3d4/history/archive_001/memory_diff.json",
- "memories_extracted": {
- "profile": 1,
- "preferences": 2,
- "entities": 1,
- "cases": 1
- },
- "active_count_updated": 2,
- "token_usage": {
- "llm": {
- "prompt_tokens": 5200,
- "completion_tokens": 1800,
- "total_tokens": 7000
- },
- "embedding": {
- "total_tokens": 1500
- },
- "total": {
- "total_tokens": 8500
- }
- }
- }
- }
-}
-```
-
----
-
-### list_tasks()
-
-#### 1. API 实现介绍
-
-列出当前调用方可见的后台任务,支持按类型、状态、资源过滤。
-
-**代码入口**:
-- `openviking/server/routers/tasks.py:list_tasks()` - HTTP 路由
-- `openviking_cli/client/base.py:BaseClient.list_tasks()` - Python SDK
-
-#### 2. 接口和参数说明
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| task_type | str | 否 | None | 按任务类型过滤,例如 `session_commit` |
-| status | str | 否 | None | 按任务状态过滤:`pending`、`running`、`completed`、`failed` |
-| resource_id | str | 否 | None | 按资源 ID 过滤,例如会话 ID |
-| limit | int | 否 | 50 | 最多返回的任务条数 |
-
-#### 3. 使用示例
-
-**HTTP API**
-
-```http
-GET /api/v1/tasks?task_type=session_commit&status=running&limit=20
-```
-
-```bash
-curl -X GET "http://localhost:1933/api/v1/tasks?task_type=session_commit&status=running&limit=20" \
- -H "X-API-Key: your-key"
-```
-
-**Python SDK**
-
-```python
-import openviking as ov
-
-client = ov.Client(base_url="http://localhost:1933", api_key="your-key")
-
-tasks = await client.list_tasks(
- task_type="session_commit",
- status="running",
- limit=20,
-)
-for task in tasks:
- print(task["task_id"], task["status"])
-```
-
-**TypeScript SDK**
-
-```typescript
-console.log(await client.listTasks());
-```
-
-**Go SDK**
-
-```go
-tasks, err := client.ListTasks(ctx, &openviking.ListTasksOptions{
- TaskType: "session_commit",
- Status: "running",
- Limit: 20,
-})
-if err != nil {
- return err
-}
-for _, task := range tasks {
- fmt.Println(task)
-}
-```
-
-**响应示例**
-
-```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,
- "stage": null
- }
- ]
-}
-```
-
----
+<a id="get_task"></a><a id="list_tasks"></a>
## 会话属性
@@ -1501,27 +1421,7 @@ viking://user/{user_id}/sessions/{session_id}/
如果长记忆抽取已运行但没有产生记忆操作,也会写入空结构的 `memory_diff.json`(所有计数为零)。
----
-
-## 内置记忆类型
-
-| 分类 | 位置 | 说明 |
-|------|------|------|
-| 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/` | 技能执行经验与工作流策略 |
-
-以上是当前启用的内置类型;部署可以通过自定义记忆模板扩展或覆盖。
-
----
+<a id="内置记忆类型"></a>
## 完整示例
@@ -1642,5 +1542,7 @@ results = await client.search(query, session_id=session_id)
## 相关文档
- [上下文类型](../concepts/02-context-types.md) - 记忆类型
+- [记忆](16-memory.md) - 记忆类型与类型配额召回
- [检索](06-retrieval.md) - 结合会话进行搜索
- [资源管理](02-resources.md) - 资源管理
+- [后台任务](17-tasks.md) - 跟踪 commit 任务
diff --git a/docs/zh/api/07-system.md b/docs/zh/api/07-system.md
index 50fab2dcf..3a930b154 100644
--- a/docs/zh/api/07-system.md
+++ b/docs/zh/api/07-system.md
@@ -1,6 +1,6 @@
-# 系统与监控
+# 系统状态
-OpenViking 提供系统健康检查、可观测性和调试 API,用于监控各组件状态。
+OpenViking 系统 API 提供健康检查、就绪检查、一致性检查和多写后端同步状态。组件级观测和 Prometheus 指标分别提供独立文档。
## API 参考
@@ -420,582 +420,78 @@ ov system wait --timeout 60
---
-### reindex()
+### backend_sync_status()
-对已经存储在 OpenViking 中的现有内容,重新构建语义产物和/或向量索引。这是一个运维维护接口,适用于 embedding 模型更换、VLM 更换、向量库重刷、版本升级后修复历史索引等场景。
-
-这个接口面向已有的 `viking://...` 内容,不负责导入新文件。常规导入请使用 [Resources](02-resources.md)。
-
-**认证**
-
-- HTTP 端点:在开启认证时要求 admin/root 角色。`api_key` 模式下,租户内容重建请使用 admin key;裸 root key 不能访问租户级数据。
-- Python embedded 模式:使用当前 service context
-- Python HTTP client / CLI:使用当前认证身份发起请求
-
-**参数**
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| uri | str | 是 | - | 要重新索引的 Viking URI |
-| mode | str | 否 | `vectors_only` | 重建模式:`vectors_only`、`semantic_and_vectors` 或 `prune_orphans` |
-| wait | bool | 否 | `true` | 是否等待任务完成 |
-| dry_run | bool | 否 | `false` | 仅适用于 `mode="prune_orphans"`;只报告 orphan 向量记录,不实际删除 |
-
-HTTP 请求体不接受未知字段。`uri` 可以使用其他 content API 支持的 OpenViking 路径变量,服务端会先解析再校验。
-
-**支持的 URI 范围**
-
-- `viking://`
-- `viking://user`
-- `viking://user/<user_id>`
-- `viking://resources`
-- `viking://resources/...`
-- `viking://user/<user_id>/memories/...`
-- `viking://user/<user_id>/skills`
-- `viking://user/<user_id>/skills/<skill_name>`
-
-`reindex()` 不支持会话命名空间。请求 `viking://session/...` 或
-`viking://user/<user_id>/sessions/...` 会被拒绝;重建更大的 user 命名空间时,
-session 子树会被跳过。
-
-**模式说明**
-
-- `vectors_only`:基于当前仍可恢复的源数据重建向量库记录,不会重写 `.abstract.md` 和 `.overview.md`
-- `semantic_and_vectors`:先重新生成语义产物,再基于新的语义结果重建向量
-- `prune_orphans`:删除请求 URI 范围内源文件已不存在的向量库记录。设置 `dry_run=true` 时,只报告会删除多少记录,不实际删除。
-
-对于 `resource` 和 `skill`,`semantic_and_vectors` 会刷新目录/文件语义产物,包括 `.abstract.md` 和 `.overview.md`。对于 `memory`,它会重建当前已持久化 memory 子树的语义和向量,但不会回放历史记忆抽取顺序。
-
-对于 `semantic_and_vectors`,语义刷新和向量重建由 reindex executor 串行编排。语义刷新阶段不会再额外向后台 embedding queue 投递自己的向量化任务;向量由 reindex 阶段统一重建,因此 `wait=true` 表示等待 reindex 操作本身完成。
-
-对于 `prune_orphans`,源文件是否存在以当前文件系统为准。如果整个目录已经不存在,该目录下的正文文件向量和语义 sidecar 向量(例如 `.abstract.md`、`.overview.md`)会一起清理。`dry_run` 用在其他模式时会被拒绝。
-
-**Python SDK (Embedded / HTTP)**
-
-```python
-result = client.reindex(
- uri="viking://resources",
- mode="vectors_only",
- wait=True,
-)
-print(result)
-```
-
-```python
-result = client.reindex(
- uri="viking://user/default/skills",
- mode="semantic_and_vectors",
- wait=False,
-)
-print(result["status"])
-```
-
-```python
-result = client.reindex(
- uri="viking://resources",
- mode="prune_orphans",
- dry_run=True,
-)
-print(result["would_delete_records"])
-```
-
-**TypeScript SDK**
-
-```typescript
-console.log(await client.reindex("viking://resources/docs/"));
-```
-
-**Go SDK**
-
-```go
-result, err := client.Reindex(ctx, "viking://resources", &openviking.ReindexOptions{
- Mode: "vectors_only",
- Wait: true,
-})
-if err != nil {
- return err
-}
-fmt.Println(result["status"])
-```
-
-```go
-result, err := client.Reindex(ctx, "viking://resources", &openviking.ReindexOptions{
- Mode: "prune_orphans",
- Wait: true,
- DryRun: true,
-})
-if err != nil {
- return err
-}
-fmt.Println(result["would_delete_records"])
-```
+查询指定 Viking URI 子树在多写存储后端之间的同步状态。该接口要求 ROOT 或 ADMIN 权限。
**HTTP API**
+```http
+POST /api/v1/system/backend/sync-status
+Content-Type: application/json
```
-POST /api/v1/content/reindex
-```
-
-不存在 `/api/v1/maintenance/reindex` 端点。请使用 `/api/v1/content/reindex`。
```bash
-curl -X POST http://localhost:1933/api/v1/content/reindex \
+curl -X POST http://localhost:1933/api/v1/system/backend/sync-status \
-H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -H "X-OpenViking-Account: default" \
- -d '{
- "uri": "viking://resources",
- "mode": "prune_orphans",
- "wait": true,
- "dry_run": true
- }'
-```
-
-**CLI**
-
-```bash
-openviking reindex viking://resources --mode vectors_only
-```
-
-```bash
-openviking reindex viking://user/default/skills --mode semantic_and_vectors --wait false
-```
-
-```bash
-openviking reindex viking://resources --mode prune_orphans --dry-run
-```
-
-**同步响应(`wait=true`)**
-
-```json
-{
- "status": "ok",
- "result": {
- "uri": "viking://resources",
- "mode": "vectors_only",
- "status": "completed",
- "object_type": "resource",
- "scanned_records": 120,
- "rebuilt_records": 118,
- "deleted_records": 0,
- "would_delete_records": 0,
- "unsupported_records": 2,
- "failed_records": 0,
- "duration_ms": 1284,
- "warnings": []
- },
- "time": 0.1
-}
-```
-
-**异步响应(`wait=false`)**
-
-```json
-{
- "status": "ok",
- "result": {
- "uri": "viking://resources",
- "mode": "vectors_only",
- "object_type": "resource",
- "status": "accepted",
- "task_id": "task_xxx"
- },
- "time": 0.1
-}
-```
-
-使用返回的 task 查询后台任务:
-
-```bash
-curl -X GET http://localhost:1933/api/v1/tasks/task_xxx \
- -H "X-API-Key: your-key" \
- -H "X-OpenViking-Account: default"
-```
-
-Reindex 后台任务的 `task_type` 为 `admin_reindex`,`resource_id` 等于请求中的 `uri`,也可以这样列出:
-
-```text
-GET /api/v1/tasks?task_type=admin_reindex&resource_id=viking://resources
-```
-
-任务记录持久化在 `/local/{account_id}/_system/tasks/{user_id}/{task_id}.json`,服务重启后仍可查询。
-
-**结果字段**
-
-| 字段 | 说明 |
-|------|------|
-| status | 同步完成时为 `completed`,后台执行时为 `accepted` |
-| uri | 解析路径变量后的请求 URI |
-| object_type | 推断出的目标类型,例如 `resource`、`skill`、`memory`、`user_namespace`、`skill_namespace` 或 `global_namespace` |
-| mode | 实际执行的 reindex 模式 |
-| scanned_records | 被检查的记录或语义源数量 |
-| rebuilt_records | 成功重建的向量记录数量 |
-| deleted_records | `prune_orphans` 实际删除的向量记录数量;`dry_run=true` 时为 `0` |
-| would_delete_records | `prune_orphans` dry-run 模式下将会删除的向量记录数量 |
-| unsupported_records | 因没有可用向量来源而跳过的记录数量 |
-| failed_records | 重建失败的记录数量 |
-| duration_ms | 同步执行耗时,单位毫秒 |
-| warnings | 可恢复的单条记录级 warning |
-| task_id | 后台任务 ID,仅 `wait=false` 时返回 |
-
-**行为说明**
-
-- `vectors_only` 和 `semantic_and_vectors` 是非破坏式的,采用重建/覆盖写入,不需要先 drop 向量集合。
-- `prune_orphans` 除非设置 `dry_run=true`,否则会删除源文件已经不存在的向量记录。
-- 对 `viking://` 发起 reindex 时,会向下分发到支持的顶层命名空间,并显式排除 `session`。
-- 命名空间级 reindex,例如 `viking://user`,会继续传播到其支持的子内容类型。
-- 如果只是 embedding 模型或向量索引需要刷新,应使用 `vectors_only`。
-- 如果语义产物本身也需要重建,再做重向量化,应使用 `semantic_and_vectors`。
-- 如果文件系统曾绕过正常 API 发生删除,向量库可能还残留已删除路径的记录,应使用 `prune_orphans`。
-- 同一个 URI 和 owner 同时只能运行一个 reindex 任务。对同一目标的并发请求会返回 conflict。
-- 对 resource 文件,文本文件在没有 summary 时可以使用文件正文;非文本文件需要已生成的 summary 或已有向量记录 fallback,否则会计为 unsupported。
-
-**当前限制**
-
-- Reindex 会使用当前系统中“尽可能可恢复”的输入进行重建,不保证所有场景都能逐字节回放历史当时的 embedding 输入。
-- Memory 的 semantic reindex 基于当前已持久化的 memory 树,不会重建最初按时间顺序执行的记忆抽取流水线。
-
----
-
-## Observer API
-
-Observer API 提供详细的组件级监控。
-
-### observer.queue
-
-#### 1. API 实现介绍
-
-获取队列系统状态(embedding 和语义处理队列)。显示各队列的待处理、进行中、已完成和错误数量。
-
-**代码入口**:
-- `openviking/server/routers/observer.py:observer_queue` - HTTP 路由
-- `openviking/service/debug_service.py:ObserverService.queue` - 核心实现
-- `openviking/storage/observers/queue_observer.py` - 队列观察者
-
-#### 2. 接口和参数说明
-
-无参数。
-
-#### 3. 使用示例
-
-**HTTP API**
-
-```
-GET /api/v1/observer/queue
-```
-
-```bash
-curl -X GET http://localhost:1933/api/v1/observer/queue \
- -H "X-API-Key: your-key"
-```
-
-**Python SDK**
-
-```python
-print(client.observer.queue)
-# 输出:
-# [queue] (healthy)
-# Queue Pending In Progress Processed Errors Total
-# Embedding 0 0 10 0 10
-# Semantic 0 0 10 0 10
-# TOTAL 0 0 20 0 20
-```
-
-**TypeScript SDK**
-
-```typescript
-console.log(await client.queueStatus());
-```
-
-**Go SDK**
-
-```go
-status, err := client.QueueStatus(ctx)
-if err != nil {
- return err
-}
-fmt.Println(status["is_healthy"])
-```
-
-**CLI**
-
-```bash
-ov observer queue
-```
-
-**响应示例**
-
-```json
-{
- "status": "ok",
- "result": {
- "name": "queue",
- "is_healthy": true,
- "has_errors": false,
- "status": "Queue Pending In Progress Processed Errors Total\nEmbedding 0 0 10 0 10\nSemantic 0 0 10 0 10\nTOTAL 0 0 20 0 20"
- },
- "time": 0.1
-}
-```
-
----
-
-### observer.vikingdb
-
-#### 1. API 实现介绍
-
-获取 VikingDB 状态(集合、索引、向量数量)。
-
-**代码入口**:
-- `openviking/server/routers/observer.py:observer_vikingdb` - HTTP 路由
-- `openviking/service/debug_service.py:ObserverService.vikingdb` - 核心实现
-- `openviking/storage/observers/vikingdb_observer.py` - VikingDB 观察者
-- `crates/ov_cli/src/commands/observer.rs` - CLI 命令
-
-#### 2. 接口和参数说明
-
-无参数。
-
-#### 3. 使用示例
-
-**HTTP API**
-
-```
-GET /api/v1/observer/vikingdb
-```
-
-```bash
-curl -X GET http://localhost:1933/api/v1/observer/vikingdb \
- -H "X-API-Key: your-key"
-```
-
-**Python SDK**
-
-```python
-print(client.observer.vikingdb())
-# 输出:
-# [vikingdb] (healthy)
-# Collection Index Count Vector Count Status
-# context 1 55 OK
-# TOTAL 1 55
-
-# 访问特定属性
-print(client.observer.vikingdb().is_healthy) # True
-print(client.observer.vikingdb().status) # 状态表字符串
-```
-
-**TypeScript SDK**
-
-```typescript
-console.log(await client.vikingDBStatus());
-```
-
-**Go SDK**
-
-```go
-status, err := client.VikingDBStatus(ctx)
-if err != nil {
- return err
-}
-fmt.Println(status["is_healthy"])
-```
-
-**CLI**
-
-```bash
-ov observer vikingdb
-```
-
-**响应示例**
-
-```json
-{
- "status": "ok",
- "result": {
- "name": "vikingdb",
- "is_healthy": true,
- "has_errors": false,
- "status": "Collection Index Count Vector Count Status\ncontext 1 55 OK\nTOTAL 1 55"
- },
- "time": 0.1
-}
+ -H "X-API-Key: your-admin-key" \
+ -d '{"uri":"viking://resources"}'
```
----
-
-### observer.models
-
-#### 1. API 实现介绍
-
-获取模型子系统的聚合状态(VLM、embedding、rerank)。检查各模型提供者是否健康可用。
-
-**代码入口**:
-- `openviking/server/routers/observer.py:observer_models` - HTTP 路由
-- `openviking/service/debug_service.py:ObserverService.models` - 核心实现
-- `openviking/storage/observers/models_observer.py` - 模型观察者
-- `crates/ov_cli/src/commands/observer.rs` - CLI 命令
-
-#### 2. 接口和参数说明
-
-无参数。
-
-#### 3. 使用示例
+也可以使用 URI 路径形式:
-**HTTP API**
-
-```
-GET /api/v1/observer/models
-```
-
-```bash
-curl -X GET http://localhost:1933/api/v1/observer/models \
- -H "X-API-Key: your-key"
-```
-
-**Python SDK**
-
-```python
-print(client.observer.models)
-# 输出:
-# [models] (healthy)
-# provider_model healthy detail
-# dense_embedding yes ...
-# rerank yes ...
-# vlm yes ...
-```
-
-**TypeScript SDK**
-
-```typescript
-console.log(await client.modelsStatus());
-```
-
-**Go SDK**
-
-```go
-status, err := client.ModelsStatus(ctx)
-if err != nil {
- return err
-}
-fmt.Println(status["is_healthy"])
+```http
+GET /api/v1/system/sync/{sync_path}
```
**CLI**
```bash
-ov observer models
-```
-
-**响应示例**
-
-```json
-{
- "status": "ok",
- "result": {
- "name": "models",
- "is_healthy": true,
- "has_errors": false,
- "status": "provider_model healthy detail\ndense_embedding yes ...\nrerank yes ...\nvlm yes ..."
- },
- "time": 0.1
-}
-```
-
----
-
-### observer.lock
-
-#### 1. API 实现介绍
-
-获取分布式锁系统状态。
-
-**代码入口**:
-- `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. 接口和参数说明
-
-无参数。
-
-#### 3. 使用示例
-
-**HTTP API**
-
-```
-GET /api/v1/observer/lock
-```
-
-```bash
-curl -X GET http://localhost:1933/api/v1/observer/lock \
- -H "X-API-Key: your-key"
-```
-
-**Python SDK**
-
-```python
-print(client.observer.lock)
+ov system backend sync-status viking://resources
```
-CLI 目前没有单独的 lock observer 子命令。请使用 HTTP API 或 Python SDK 查询该组件;`ov observer system` 会在汇总状态中包含它。
-
**响应示例**
```json
{
"status": "ok",
"result": {
- "name": "lock",
- "is_healthy": true,
- "has_errors": false,
- "status": "..."
- },
- "time": 0.1
+ "path": "viking://resources",
+ "entry_count": 12
+ }
}
```
----
+`result` 由当前文件系统后端返回;`path` 标识查询范围,`entry_count` 表示该范围内的同步记录数。具体后端可能附加待同步、失败记录等诊断字段。
-### observer.retrieval
+### backend_sync_retry()
-#### 1. API 实现介绍
-
-获取检索质量指标。
-
-**代码入口**:
-- `openviking/server/routers/observer.py:observer_retrieval` - HTTP 路由
-- `openviking/service/debug_service.py:ObserverService.retrieval` - 核心实现
-- `openviking/storage/observers/retrieval_observer.py` - 检索观察者
-- `crates/ov_cli/src/commands/observer.rs` - CLI 命令
-
-#### 2. 接口和参数说明
-
-无参数。
-
-#### 3. 使用示例
+重试指定 URI 子树中尚未完成的多写后端同步工作。该接口要求 ROOT 或 ADMIN 权限。
**HTTP API**
-```
-GET /api/v1/observer/retrieval
+```http
+POST /api/v1/system/backend/sync-retry
+Content-Type: application/json
```
```bash
-curl -X GET http://localhost:1933/api/v1/observer/retrieval \
- -H "X-API-Key: your-key"
+curl -X POST http://localhost:1933/api/v1/system/backend/sync-retry \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-admin-key" \
+ -d '{"uri":"viking://resources"}'
```
-**Python SDK**
+URI 路径形式为:
-```python
-print(client.observer.retrieval)
+```http
+POST /api/v1/system/sync/{sync_path}/retry
```
**CLI**
```bash
-ov observer retrieval
+ov system backend sync-retry viking://resources
```
**响应示例**
@@ -1004,185 +500,25 @@ ov observer retrieval
{
"status": "ok",
"result": {
- "name": "retrieval",
- "is_healthy": true,
- "has_errors": false,
- "status": "..."
- },
- "time": 0.1
+ "path": "viking://resources",
+ "retried": 2,
+ "failed": 0
+ }
}
```
----
-
-### observer.filesystem
-
-#### 1. API 实现介绍
-
-获取文件系统操作指标。
-
-**代码入口**:
-- `openviking/server/routers/observer.py:observer_filesystem` - HTTP 路由
-- `openviking/service/debug_service.py:ObserverService.filesystem` - 核心实现
-- `openviking/storage/observers/filesystem_observer.py` - 文件系统观察者
-- `crates/ov_cli/src/commands/observer.rs` - CLI 命令
-
-#### 2. 接口和参数说明
-
-无参数。
+`retried` 是本次重新调度的记录数,`failed` 是重试调度失败的记录数;具体后端可能附加额外诊断字段。
-#### 3. 使用示例
-
-**HTTP API**
-
-```
-GET /api/v1/observer/filesystem
-```
-
-```bash
-curl -X GET http://localhost:1933/api/v1/observer/filesystem \
- -H "X-API-Key: your-key"
-```
-
-**Python SDK**
-
-```python
-print(client.observer.filesystem)
-```
-
-**CLI**
-
-```bash
-ov observer filesystem
-```
-
-**响应示例**
-
-```json
-{
- "status": "ok",
- "result": {
- "name": "filesystem",
- "is_healthy": true,
- "has_errors": false,
- "status": "..."
- },
- "time": 0.1
-}
-```
+公共 Python、TypeScript 和 Go SDK 当前没有多写后端同步方法,因此以上小节只展示 HTTP 和 CLI Tab。
---
-### observer.system
-
-#### 1. API 实现介绍
-
-获取整体系统状态,包括所有组件(queue、vikingdb、models、lock、retrieval)。
-
-**代码入口**:
-- `openviking/server/routers/observer.py:observer_system` - HTTP 路由
-- `openviking/service/debug_service.py:ObserverService.system` - 核心实现
-- `crates/ov_cli/src/commands/observer.rs` - CLI 命令
-
-#### 2. 接口和参数说明
-
-无参数。
-
-#### 3. 使用示例
-
-**HTTP API**
-
-```
-GET /api/v1/observer/system
-```
-
-```bash
-curl -X GET http://localhost:1933/api/v1/observer/system \
- -H "X-API-Key: your-key"
-```
-
-**Python SDK**
-
-```python
-print(client.observer.system())
-# 输出:
-# [queue] (healthy)
-# ...
-#
-# [vikingdb] (healthy)
-# ...
-#
-# [models] (healthy)
-# ...
-#
-# [system] (healthy)
-```
-
-**Go SDK**
-
-```go
-status, err := client.GetStatus(ctx)
-if err != nil {
- return err
-}
-fmt.Println(status["is_healthy"])
-```
-
-**CLI**
-
-```bash
-ov observer system
-```
-
-**响应示例**
-
-```json
-{
- "status": "ok",
- "result": {
- "is_healthy": true,
- "errors": [],
- "components": {
- "queue": {
- "name": "queue",
- "is_healthy": true,
- "has_errors": false,
- "status": "..."
- },
- "vikingdb": {
- "name": "vikingdb",
- "is_healthy": true,
- "has_errors": false,
- "status": "..."
- },
- "models": {
- "name": "models",
- "is_healthy": true,
- "has_errors": false,
- "status": "..."
- },
- "lock": {
- "name": "lock",
- "is_healthy": true,
- "has_errors": false,
- "status": "..."
- },
- "retrieval": {
- "name": "retrieval",
- "is_healthy": true,
- "has_errors": false,
- "status": "..."
- }
- }
- },
- "time": 0.1
-}
-```
-
----
+<a id="reindex"></a><a id="observer-api"></a>
## 相关文档
- [Resources](02-resources.md) - 资源管理
- [Retrieval](06-retrieval.md) - 搜索与检索
- [Sessions](05-sessions.md) - 会话管理
+- [运行观测](18-observer.md) - 组件即时状态
+- [Metrics](09-metrics.md) - Prometheus 指标
diff --git a/docs/zh/api/08-admin.md b/docs/zh/api/08-admin.md
index d73a66d9b..947fee47f 100644
--- a/docs/zh/api/08-admin.md
+++ b/docs/zh/api/08-admin.md
@@ -1049,44 +1049,7 @@ ov --sudo admin migrate --cleanup --output json
---
-### 用户添加位置设置
-
-个人添加默认值作为用户配置存储在
-`viking://user/{user_id}/settings/user_config.json`。它只影响没有显式传目标的添加请求:
-
-1. `add_resource`:显式 `to` / `parent` 优先,然后是用户
- `add_targets.resource_uri`,再是
- `server.user_config_defaults.add_targets.resource_uri`,最后保持旧行为。
-2. `add_skill`:显式 `target_uri` 优先,然后是用户
- `add_targets.skill_uri`,再是
- `server.user_config_defaults.add_targets.skill_uri`,最后保持旧行为。
-
-#### HTTP API
-
-```
-GET /api/v1/user-settings/add-locations
-PATCH /api/v1/user-settings/add-locations
-DELETE /api/v1/user-settings/add-locations
-```
-
-`PATCH` 直接接收 add-target 字段。传 `null` 会清除单个字段;删除设置会清除整个个人覆盖配置。
-
-```bash
-curl -X PATCH http://localhost:1933/api/v1/user-settings/add-locations \
- -H "Content-Type: application/json" \
- -H "X-API-Key: <user-key>" \
- -d '{"resource_uri": "viking://user/resources/project-a"}'
-```
-
-`resource_uri` 必须是可写资源目录 URI:`viking://resources` 或
-`viking://resources/...`、`viking://user/resources` 或
-`viking://user/resources/...`、`viking://user/{user_id}/resources` 或
-`viking://user/{user_id}/resources/...`、`viking://user/{user_id}/peers/{peer_id}/resources`
-或 `viking://user/{user_id}/peers/{peer_id}/resources/...`。`skill_uri` 只能是
-`viking://user/skills` 或 `viking://agent/skills`;v1 不支持显式写成
-`viking://user/{user_id}/skills`。配置值非法时会直接报错,不会静默回退到其它目标。
-
----
+<a id="用户添加位置设置"></a>
## 完整示例
diff --git a/docs/zh/api/09-metrics.md b/docs/zh/api/09-metrics.md
index d30eef25d..37659f923 100644
--- a/docs/zh/api/09-metrics.md
+++ b/docs/zh/api/09-metrics.md
@@ -2,7 +2,7 @@
OpenViking 提供 `/metrics` 端点,用于向 Prometheus、Grafana Agent 等监控系统导出运行时指标。
-与 `/api/v1/observer/*` 和 `/api/v1/stats/*` 不同,`/metrics` 的定位是:
+与 `/api/v1/observer/*` 不同,`/metrics` 的定位是:
- 面向机器抓取,而不是面向人工阅读
- 返回 Prometheus exposition 文本,而不是统一 JSON 包装
@@ -78,7 +78,6 @@ scrape_configs:
- `/metrics` 适合高频抓取,因此其中的指标应保持低基数、低成本。
- `/metrics` 返回的是 Prometheus 文本,不是标准 OpenViking API 的 `{status, result, time}` JSON 结构。
-- 业务分析类统计(如 memory health、staleness、session extraction)应继续使用 `/api/v1/stats/*`,而不是迁移到 `/metrics`。
- 人工查看组件瞬时状态更适合使用 `/api/v1/observer/*`。
- `/metrics` 现在也包含 VikingBot feedback observability 指标,这些指标来自对持久化 session 数据的 scrape-time 聚合;具体指标族与示例可参见 Metrics 概念文档中的 feedback 章节。
diff --git a/docs/zh/api/11-snapshot.md b/docs/zh/api/11-snapshot.md
index a005389f8..1a4ff5cfc 100644
--- a/docs/zh/api/11-snapshot.md
+++ b/docs/zh/api/11-snapshot.md
@@ -347,7 +347,22 @@ ov snapshot diff viking://resources/my_project/guide.md \
--to 9a0b1c2d
```
-响应包含 `path`、解析后的 `from_commit` 和 `to_commit`、`change_type`(`added`、`deleted`、`modified` 或 `unchanged`)以及 `diff_text`。参与对比的单侧文件上限为 10 MiB 和 100,000 行,生成的 diff 上限为 20 MiB;超限时返回 `RESOURCE_EXHAUSTED`,不会返回被截断的 diff。
+**响应**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "path": "viking://resources/my_project/guide.md",
+ "from_commit": "3f2a1b9c...",
+ "to_commit": "9a0b1c2d...",
+ "change_type": "modified",
+ "diff_text": "--- a/guide.md\n+++ b/guide.md\n@@ -1 +1 @@\n-old line\n+new line\n"
+ }
+}
+```
+
+`change_type` 为 `added`、`deleted`、`modified` 或 `unchanged`。参与对比的单侧文件上限为 10 MiB 和 100,000 行,生成的 diff 上限为 20 MiB;超限时返回 `RESOURCE_EXHAUSTED`,不会返回被截断的 diff。
---
diff --git a/docs/zh/api/12-content.md b/docs/zh/api/12-content.md
new file mode 100644
index 000000000..eb48d2571
--- /dev/null
+++ b/docs/zh/api/12-content.md
@@ -0,0 +1,702 @@
+# 内容
+
+内容 API 负责读取 L0/L1/L2 内容、写入文本,以及维护内容对应的语义和向量索引。
+
+## API 参考
+
+### abstract()
+
+读取 L0 摘要(约 100 token 的概要)。
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| uri | str | 是 | - | Viking URI(必须是目录) |
+
+
+**Python SDK**
+
+```python
+abstract = client.abstract("viking://resources/docs/")
+print(f"Abstract: {abstract}")
+# Output: "Documentation for the project API, covering authentication, endpoints..."
+```
+
+**TypeScript SDK**
+
+```typescript
+const abstract = await client.abstract("viking://resources/docs/");
+console.log(abstract);
+```
+
+**Go SDK**
+
+```go
+abstract, err := client.Abstract(ctx, "viking://resources/docs/")
+if err != nil {
+ return err
+}
+fmt.Println(abstract)
+```
+
+**HTTP API**
+
+```
+GET /api/v1/content/abstract?uri={uri}
+```
+
+```bash
+curl -X GET "http://localhost:1933/api/v1/content/abstract?uri=viking://resources/docs/" \
+ -H "X-API-Key: your-key"
+```
+
+**CLI**
+
+```bash
+openviking abstract viking://resources/docs/
+```
+
+
+**响应**
+
+```json
+{
+ "status": "ok",
+ "result": "Documentation for the project API, covering authentication, endpoints...",
+ "time": 0.1
+}
+```
+
+---
+
+### overview()
+
+读取 L1 概览,适用于目录。
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| uri | str | 是 | - | Viking URI(必须是目录) |
+
+
+**Python SDK**
+
+```python
+overview = client.overview("viking://resources/docs/")
+print(f"Overview:\n{overview}")
+```
+
+**TypeScript SDK**
+
+```typescript
+const overview = await client.overview("viking://resources/docs/");
+console.log(overview);
+```
+
+**Go SDK**
+
+```go
+overview, err := client.Overview(ctx, "viking://resources/docs/")
+if err != nil {
+ return err
+}
+fmt.Println(overview)
+```
+
+**HTTP API**
+
+```
+GET /api/v1/content/overview?uri={uri}
+```
+
+```bash
+curl -X GET "http://localhost:1933/api/v1/content/overview?uri=viking://resources/docs/" \
+ -H "X-API-Key: your-key"
+```
+
+**CLI**
+
+```bash
+openviking overview viking://resources/docs/
+```
+
+
+**响应**
+
+```json
+{
+ "status": "ok",
+ "result": "## docs/\n\nContains API documentation and guides...",
+ "time": 0.1
+}
+```
+
+---
+
+### read()
+
+读取 L2 完整内容。
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| uri | str | 是 | - | Viking URI |
+| offset | int | 否 | 0 | 起始行号(0 开始) |
+| limit | int | 否 | -1 | 读取的行数,`-1` 表示读到结尾 |
+| raw | bool | 否 | false | 返回未过滤 MEMORY_FIELDS 的原始存储内容(仅 HTTP API,Python SDK 暂未暴露)。 |
+
+**说明**
+
+- `read()` 只接受文件 URI。传入已存在的目录 URI 时返回 `INVALID_ARGUMENT`(`400`),而不是 `NOT_FOUND`。该错误会携带结构化的 `details` 字段——`details.expected` 为 `"file"`,`details.actual` 为 `"directory"`,`details.resource` 为出错的 URI(HTTP 路径上会带上)——客户端据此即可以编程方式判断"文件 vs 目录"不匹配(例如回退到 `list`),而无需对错误消息做字符串匹配。
+- 公开 URI 参数接受 `resources` 和 `user` 作用域。访问 session 文件时,使用 `viking://user/{user_id}/sessions/{session_id}`,也可以使用向后兼容的 `viking://session/{session_id}` 别名。`temp`、`queue` 等内部作用域会返回 `INVALID_URI`。
+
+
+**Python SDK**
+
+```python
+content = client.read("viking://resources/docs/api.md")
+print(f"Content:\n{content}")
+```
+
+**TypeScript SDK**
+
+```typescript
+const content = await client.read("viking://resources/docs/api.md", 0, -1);
+console.log(content);
+```
+
+**Go SDK**
+
+```go
+content, err := client.Read(ctx, "viking://resources/docs/api.md", 0, -1)
+if err != nil {
+ return err
+}
+fmt.Println(content)
+```
+
+**HTTP API**
+
+```
+GET /api/v1/content/read?uri={uri}
+```
+
+```bash
+curl -X GET "http://localhost:1933/api/v1/content/read?uri=viking://resources/docs/api.md" \
+ -H "X-API-Key: your-key"
+```
+
+**CLI**
+
+```bash
+openviking read viking://resources/docs/api.md
+```
+
+
+**响应**
+
+```json
+{
+ "status": "ok",
+ "result": "# API Documentation\n\nFull content of the file...",
+ "time": 0.1
+}
+```
+
+---
+
+### write()
+
+修改一个已存在的文件,或在 `mode="create"` 时创建新文件,并自动刷新相关语义与向量。
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| uri | str | 是 | - | 要写入的文件 URI。`mode="create"` 时目标文件必须不存在 |
+| content | str | 是 | - | 要写入的新内容 |
+| mode | str | 否 | `replace` | `replace`、`append` 或 `create` |
+| wait | bool | 否 | `false` | 是否等待后台语义/向量刷新完成 |
+| timeout | float | 否 | `null` | 当 `wait=true` 时的超时时间(秒) |
+
+**说明**
+
+- `replace` 和 `append` 要求文件已存在;`create` 仅用于创建新文件,目标路径已存在时返回 `409 Conflict`。目录始终会被拒绝。
+- `create` 只允许以下文本类扩展名:`.md`、`.txt`、`.json`、`.yaml`、`.yml`、`.toml`、`.py`、`.js`、`.ts`。父目录会自动创建。
+- 不允许直接写入派生语义文件:`.abstract.md`、`.overview.md`、`.relations.json`。
+- 文件内容会在 API 返回前完成更新;`wait` 只控制是否等待语义/向量刷新完成。
+- 公共 API 已不再接受 `regenerate_semantics` 或 `revectorize`;写入后一定会自动刷新相关语义与向量。
+
+
+**Python SDK**
+
+```python
+result = client.write(
+ "viking://resources/docs/api.md",
+ "# Updated API\n\nFresh content.",
+ mode="replace",
+ wait=True,
+)
+print(result["root_uri"])
+```
+
+**TypeScript SDK**
+
+```typescript
+await client.write("viking://resources/docs/new.md", "# New document\n", { wait: true });
+```
+
+**Go SDK**
+
+```go
+result, err := client.Write(
+ ctx,
+ "viking://resources/docs/api.md",
+ "# Updated API\n\nFresh content.",
+ &openviking.WriteOptions{
+ Mode: "replace",
+ Wait: true,
+ },
+)
+if err != nil {
+ return err
+}
+fmt.Println(result["root_uri"])
+```
+
+**HTTP API**
+
+```
+POST /api/v1/content/write
+```
+
+```bash
+curl -X POST "http://localhost:1933/api/v1/content/write" \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "uri": "viking://resources/docs/api.md",
+ "content": "# Updated API\n\nFresh content.",
+ "mode": "replace",
+ "wait": true
+ }'
+```
+
+**CLI**
+
+```bash
+openviking write viking://resources/docs/api.md \
+ --content "# Updated API\n\nFresh content." \
+ --wait
+```
+
+
+**响应**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "uri": "viking://resources/docs/api.md",
+ "root_uri": "viking://resources/docs",
+ "context_type": "resource",
+ "mode": "replace",
+ "written_bytes": 29,
+ "content_updated": true,
+ "semantic_status": "complete",
+ "vector_status": "complete",
+ "queue_status": {
+ "Semantic": {
+ "processed": 1,
+ "error_count": 0,
+ "errors": []
+ },
+ "Embedding": {
+ "processed": 2,
+ "error_count": 0,
+ "errors": []
+ }
+ }
+ }
+}
+```
+
+---
+
+### download()
+
+以原始字节流下载文件,适用于图片、PDF 和其他非文本内容。响应使用 `application/octet-stream`,并通过 `Content-Disposition` 返回文件名。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `uri` | string | 是 | 要下载的文件 URI |
+
+**HTTP API**
+
+```http
+GET /api/v1/content/download?uri={uri}
+```
+
+```bash
+curl --get http://localhost:1933/api/v1/content/download \
+ -H "X-API-Key: your-key" \
+ --data-urlencode "uri=viking://resources/images/logo.png" \
+ --output logo.png
+```
+
+**响应**
+
+成功时返回 HTTP `200` 和文件原始字节,不使用标准 JSON 响应包:
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/octet-stream
+Content-Disposition: attachment; filename*=UTF-8''logo.png
+
+<binary body>
+```
+
+公共 SDK 和 CLI 当前没有独立的原始字节下载方法,因此本节只展示 HTTP Tab。
+
+---
+
+### set_tags()
+
+设置用于检索过滤的显式 `k=v` 标签。`replace` 替换已有标签,`append` 追加标签;对目录设置 `recursive=true` 时会更新目录下的文件。
+
+**Python SDK**
+
+```python
+result = client.set_tags(
+ "viking://resources/project/",
+ ["team=search", "env=prod"],
+ mode="replace",
+ recursive=True,
+)
+```
+
+**TypeScript SDK**
+
+```typescript
+const result = await client.setTags(
+ "viking://resources/project/",
+ ["team=search", "env=prod"],
+ { mode: "replace", recursive: true },
+);
+```
+
+**Go SDK**
+
+```go
+result, err := client.SetTags(
+ ctx,
+ "viking://resources/project/",
+ []string{"team=search", "env=prod"},
+ &openviking.SetTagsOptions{Mode: "replace", Recursive: true},
+)
+```
+
+**HTTP API**
+
+```http
+POST /api/v1/content/set_tags
+Content-Type: application/json
+```
+
+```bash
+curl -X POST http://localhost:1933/api/v1/content/set_tags \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "uri":"viking://resources/project/",
+ "tags":["team=search","env=prod"],
+ "mode":"replace",
+ "recursive":true
+ }'
+```
+
+`POST /api/v1/fs/attrs/set_tags` 是等价兼容路径,当前 Python、TypeScript、Go SDK 和 CLI 使用该路径。
+
+**CLI**
+
+```bash
+ov set-tags viking://resources/project/ \
+ --tags team=search,env=prod \
+ --mode replace \
+ --recursive
+```
+
+**响应**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "uri": "viking://resources/project/",
+ "updated_uris": [
+ "viking://resources/project/guide.md"
+ ],
+ "root_uri": "viking://resources/project/",
+ "context_type": "resource",
+ "tags": [
+ "team=search",
+ "env=prod"
+ ],
+ "mode": "replace",
+ "success_count": 1,
+ "skipped_count": 0,
+ "failed_count": 0,
+ "tags_updated": true
+ }
+}
+```
+
+`updated_uris` 是实际更新的语义记录 URI;目录递归更新时,`success_count`、`skipped_count` 和 `failed_count` 汇总各目标的处理结果。
+
+---
+
+### reindex()
+
+对已经存储在 OpenViking 中的现有内容,重新构建语义产物和/或向量索引。这是一个运维维护接口,适用于 embedding 模型更换、VLM 更换、向量库重刷、版本升级后修复历史索引等场景。
+
+这个接口面向已有的 `viking://...` 内容,不负责导入新文件。常规导入请使用 [Resources](02-resources.md)。
+
+**认证**
+
+- HTTP 端点:在开启认证时要求 admin/root 角色。`api_key` 模式下,租户内容重建请使用 admin key;裸 root key 不能访问租户级数据。
+- Python embedded 模式:使用当前 service context
+- Python HTTP client / CLI:使用当前认证身份发起请求
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| uri | str | 是 | - | 要重新索引的 Viking URI |
+| mode | str | 否 | `vectors_only` | 重建模式:`vectors_only`、`semantic_and_vectors` 或 `prune_orphans` |
+| wait | bool | 否 | `true` | 是否等待任务完成 |
+| dry_run | bool | 否 | `false` | 仅适用于 `mode="prune_orphans"`;只报告 orphan 向量记录,不实际删除 |
+
+HTTP 请求体不接受未知字段。`uri` 可以使用其他 content API 支持的 OpenViking 路径变量,服务端会先解析再校验。
+
+**支持的 URI 范围**
+
+- `viking://`
+- `viking://user`
+- `viking://user/<user_id>`
+- `viking://resources`
+- `viking://resources/...`
+- `viking://user/<user_id>/memories/...`
+- `viking://user/<user_id>/skills`
+- `viking://user/<user_id>/skills/<skill_name>`
+
+`reindex()` 不支持会话命名空间。请求 `viking://session/...` 或
+`viking://user/<user_id>/sessions/...` 会被拒绝;重建更大的 user 命名空间时,
+session 子树会被跳过。
+
+**模式说明**
+
+- `vectors_only`:基于当前仍可恢复的源数据重建向量库记录,不会重写 `.abstract.md` 和 `.overview.md`
+- `semantic_and_vectors`:先重新生成语义产物,再基于新的语义结果重建向量
+- `prune_orphans`:删除请求 URI 范围内源文件已不存在的向量库记录。设置 `dry_run=true` 时,只报告会删除多少记录,不实际删除。
+
+对于 `resource` 和 `skill`,`semantic_and_vectors` 会刷新目录/文件语义产物,包括 `.abstract.md` 和 `.overview.md`。对于 `memory`,它会重建当前已持久化 memory 子树的语义和向量,但不会回放历史记忆抽取顺序。
+
+对于 `semantic_and_vectors`,语义刷新和向量重建由 reindex executor 串行编排。语义刷新阶段不会再额外向后台 embedding queue 投递自己的向量化任务;向量由 reindex 阶段统一重建,因此 `wait=true` 表示等待 reindex 操作本身完成。
+
+对于 `prune_orphans`,源文件是否存在以当前文件系统为准。如果整个目录已经不存在,该目录下的正文文件向量和语义 sidecar 向量(例如 `.abstract.md`、`.overview.md`)会一起清理。`dry_run` 用在其他模式时会被拒绝。
+
+**Python SDK**
+
+```python
+result = client.reindex(
+ uri="viking://resources",
+ mode="vectors_only",
+ wait=True,
+)
+print(result)
+```
+
+```python
+result = client.reindex(
+ uri="viking://user/default/skills",
+ mode="semantic_and_vectors",
+ wait=False,
+)
+print(result["status"])
+```
+
+```python
+result = client.reindex(
+ uri="viking://resources",
+ mode="prune_orphans",
+ dry_run=True,
+)
+print(result["would_delete_records"])
+```
+
+**TypeScript SDK**
+
+```typescript
+console.log(await client.reindex("viking://resources/docs/"));
+```
+
+**Go SDK**
+
+```go
+result, err := client.Reindex(ctx, "viking://resources", &openviking.ReindexOptions{
+ Mode: "vectors_only",
+ Wait: true,
+})
+if err != nil {
+ return err
+}
+fmt.Println(result["status"])
+```
+
+```go
+result, err := client.Reindex(ctx, "viking://resources", &openviking.ReindexOptions{
+ Mode: "prune_orphans",
+ Wait: true,
+ DryRun: true,
+})
+if err != nil {
+ return err
+}
+fmt.Println(result["would_delete_records"])
+```
+
+**HTTP API**
+
+```
+POST /api/v1/content/reindex
+```
+
+不存在 `/api/v1/maintenance/reindex` 端点。请使用 `/api/v1/content/reindex`。
+
+```bash
+curl -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" \
+ -d '{
+ "uri": "viking://resources",
+ "mode": "prune_orphans",
+ "wait": true,
+ "dry_run": true
+ }'
+```
+
+**CLI**
+
+```bash
+openviking reindex viking://resources --mode vectors_only
+```
+
+```bash
+openviking reindex viking://user/default/skills --mode semantic_and_vectors --wait false
+```
+
+```bash
+openviking reindex viking://resources --mode prune_orphans --dry-run
+```
+
+**同步响应(`wait=true`)**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "uri": "viking://resources",
+ "mode": "vectors_only",
+ "status": "completed",
+ "object_type": "resource",
+ "scanned_records": 120,
+ "rebuilt_records": 118,
+ "deleted_records": 0,
+ "would_delete_records": 0,
+ "unsupported_records": 2,
+ "failed_records": 0,
+ "duration_ms": 1284,
+ "warnings": []
+ },
+ "time": 0.1
+}
+```
+
+**异步响应(`wait=false`)**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "uri": "viking://resources",
+ "mode": "vectors_only",
+ "object_type": "resource",
+ "status": "accepted",
+ "task_id": "task_xxx"
+ },
+ "time": 0.1
+}
+```
+
+使用返回的 task 查询后台任务:
+
+```bash
+curl -X GET http://localhost:1933/api/v1/tasks/task_xxx \
+ -H "X-API-Key: your-key" \
+ -H "X-OpenViking-Account: default"
+```
+
+Reindex 后台任务的 `task_type` 为 `admin_reindex`,`resource_id` 等于请求中的 `uri`,也可以这样列出:
+
+```text
+GET /api/v1/tasks?task_type=admin_reindex&resource_id=viking://resources
+```
+
+任务记录持久化在 `/local/{account_id}/_system/tasks/{user_id}/{task_id}.json`,服务重启后仍可查询。
+
+**结果字段**
+
+| 字段 | 说明 |
+|------|------|
+| status | 同步完成时为 `completed`,后台执行时为 `accepted` |
+| uri | 解析路径变量后的请求 URI |
+| object_type | 推断出的目标类型,例如 `resource`、`skill`、`memory`、`user_namespace`、`skill_namespace` 或 `global_namespace` |
+| mode | 实际执行的 reindex 模式 |
+| scanned_records | 被检查的记录或语义源数量 |
+| rebuilt_records | 成功重建的向量记录数量 |
+| deleted_records | `prune_orphans` 实际删除的向量记录数量;`dry_run=true` 时为 `0` |
+| would_delete_records | `prune_orphans` dry-run 模式下将会删除的向量记录数量 |
+| unsupported_records | 因没有可用向量来源而跳过的记录数量 |
+| failed_records | 重建失败的记录数量 |
+| duration_ms | 同步执行耗时,单位毫秒 |
+| warnings | 可恢复的单条记录级 warning |
+| task_id | 后台任务 ID,仅 `wait=false` 时返回 |
+
+**行为说明**
+
+- `vectors_only` 和 `semantic_and_vectors` 是非破坏式的,采用重建/覆盖写入,不需要先 drop 向量集合。
+- `prune_orphans` 除非设置 `dry_run=true`,否则会删除源文件已经不存在的向量记录。
+- 对 `viking://` 发起 reindex 时,会向下分发到支持的顶层命名空间,并显式排除 `session`。
+- 命名空间级 reindex,例如 `viking://user`,会继续传播到其支持的子内容类型。
+- 如果只是 embedding 模型或向量索引需要刷新,应使用 `vectors_only`。
+- 如果语义产物本身也需要重建,再做重向量化,应使用 `semantic_and_vectors`。
+- 如果文件系统曾绕过正常 API 发生删除,向量库可能还残留已删除路径的记录,应使用 `prune_orphans`。
+- 同一个 URI 和 owner 同时只能运行一个 reindex 任务。对同一目标的并发请求会返回 conflict。
+- 对 resource 文件,文本文件在没有 summary 时可以使用文件正文;非文本文件需要已生成的 summary 或已有向量记录 fallback,否则会计为 unsupported。
+
+**当前限制**
+
+- Reindex 会使用当前系统中“尽可能可恢复”的输入进行重建,不保证所有场景都能逐字节回放历史当时的 embedding 输入。
+- Memory 的 semantic reindex 基于当前已持久化的 memory 树,不会重建最初按时间顺序执行的记忆抽取流水线。
+
+---
+
+## 相关文档
+
+- [文件系统](03-filesystem.md) - 目录与文件操作
+- [检索](06-retrieval.md) - 语义搜索与模式搜索
+- [后台任务](17-tasks.md) - 跟踪异步 reindex 任务
diff --git a/docs/zh/api/13-relations.md b/docs/zh/api/13-relations.md
new file mode 100644
index 000000000..6ae56f5ad
--- /dev/null
+++ b/docs/zh/api/13-relations.md
@@ -0,0 +1,282 @@
+# 关系
+
+关系 API 用于创建、读取和删除 Viking URI 之间的显式关联。
+
+## API 参考
+
+### link()
+
+创建资源之间的关联。
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| from_uri | str | 是 | - | 源 URI |
+| to_uris | str 或 List[str] | 是 | - | 目标 URI |
+| reason | str | 否 | "" | 关联原因 |
+
+
+**Python SDK**
+
+```python
+# 单个关联
+client.link(
+ "viking://resources/docs/auth/",
+ "viking://resources/docs/security/",
+ reason="Security best practices for authentication"
+)
+
+# 多个关联
+client.link(
+ "viking://resources/docs/api/",
+ [
+ "viking://resources/docs/auth/",
+ "viking://resources/docs/errors/"
+ ],
+ reason="Related documentation"
+)
+```
+
+**TypeScript SDK**
+
+```typescript
+await client.link(
+ "viking://resources/docs/api/",
+ [
+ "viking://resources/docs/auth/",
+ "viking://resources/docs/errors/",
+ ],
+ "Related documentation",
+);
+```
+
+**HTTP API**
+
+```
+POST /api/v1/relations/link
+```
+
+```bash
+# 单个关联
+curl -X POST http://localhost:1933/api/v1/relations/link \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "from_uri": "viking://resources/docs/auth/",
+ "to_uris": "viking://resources/docs/security/",
+ "reason": "Security best practices for authentication"
+ }'
+
+# 多个关联
+curl -X POST http://localhost:1933/api/v1/relations/link \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "from_uri": "viking://resources/docs/api/",
+ "to_uris": ["viking://resources/docs/auth/", "viking://resources/docs/errors/"],
+ "reason": "Related documentation"
+ }'
+```
+
+**CLI**
+
+```bash
+openviking link viking://resources/docs/auth/ viking://resources/docs/security/ --reason "Security best practices"
+```
+
+
+**响应**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "from": "viking://resources/docs/auth/",
+ "to": "viking://resources/docs/security/"
+ },
+ "time": 0.1
+}
+```
+
+---
+
+### relations()
+
+获取资源的关联关系。
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| uri | str | 是 | - | Viking URI |
+
+
+**Python SDK**
+
+```python
+relations = client.relations("viking://resources/docs/auth/")
+for rel in relations:
+ print(f"Related: {rel['uri']}")
+ print(f" Reason: {rel['reason']}")
+```
+
+**TypeScript SDK**
+
+```typescript
+const relations = await client.relations("viking://resources/docs/auth/");
+console.log(relations);
+```
+
+**HTTP API**
+
+```
+GET /api/v1/relations?uri={uri}
+```
+
+```bash
+curl -X GET "http://localhost:1933/api/v1/relations?uri=viking://resources/docs/auth/" \
+ -H "X-API-Key: your-key"
+```
+
+**CLI**
+
+```bash
+openviking relations viking://resources/docs/auth/
+```
+
+
+**响应**
+
+```json
+{
+ "status": "ok",
+ "result": [
+ {"uri": "viking://resources/docs/security/", "reason": "Security best practices"},
+ {"uri": "viking://resources/docs/errors/", "reason": "Error handling"}
+ ],
+ "time": 0.1
+}
+```
+
+---
+
+### unlink()
+
+移除关联关系。
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| from_uri | str | 是 | - | 源 URI |
+| to_uri | str | 是 | - | 要取消关联的目标 URI |
+
+
+**Python SDK**
+
+```python
+client.unlink(
+ "viking://resources/docs/auth/",
+ "viking://resources/docs/security/"
+)
+```
+
+**TypeScript SDK**
+
+```typescript
+await client.unlink(
+ "viking://resources/docs/auth/",
+ "viking://resources/docs/security/",
+);
+```
+
+**HTTP API**
+
+```
+DELETE /api/v1/relations/link
+```
+
+```bash
+curl -X DELETE http://localhost:1933/api/v1/relations/link \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "from_uri": "viking://resources/docs/auth/",
+ "to_uri": "viking://resources/docs/security/"
+ }'
+```
+
+**CLI**
+
+```bash
+openviking unlink viking://resources/docs/auth/ viking://resources/docs/security/
+```
+
+
+**响应**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "from": "viking://resources/docs/auth/",
+ "to": "viking://resources/docs/security/"
+ },
+ "time": 0.1
+}
+```
+
+---
+
+### build_graph()
+
+从多个记忆根目录生成一个自包含的 HTML 关系图,并把结果写入指定 Viking URI。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `space_uris` | string[] | 是 | 要合并的记忆根目录 |
+| `output_uri` | string | 是 | 输出 HTML 文件的 Viking URI |
+
+**HTTP API**
+
+```http
+POST /api/v1/relations/build_graph
+Content-Type: application/json
+```
+
+```bash
+curl -X POST http://localhost:1933/api/v1/relations/build_graph \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "space_uris":[
+ "viking://user/default/memories",
+ "viking://user/default/peers/project-a/memories"
+ ],
+ "output_uri":"viking://user/default/memories/.graph.html"
+ }'
+```
+
+**响应**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "graph_uri": "viking://user/default/memories/.graph.html"
+ }
+}
+```
+
+`graph_uri` 是已写入的自包含 HTML 文件 URI,可通过内容或文件系统 API 读取。
+
+该端点当前没有公共 SDK 或 CLI 封装,因此本节只展示 HTTP Tab。
+
+---
+
+## 相关文档
+
+- [检索](06-retrieval.md) - 检索并使用关联内容
+- [文件系统](03-filesystem.md) - 管理关联目标
+- [记忆](16-memory.md) - 记忆命名空间和类型
diff --git a/docs/zh/api/14-ovpack.md b/docs/zh/api/14-ovpack.md
new file mode 100644
index 000000000..92e278654
--- /dev/null
+++ b/docs/zh/api/14-ovpack.md
@@ -0,0 +1,420 @@
+# OVPack
+
+OVPack API 用于导入、导出、备份和恢复 OpenViking 数据。
+
+## API 参考
+
+### export_ovpack
+
+将资源树导出为 `.ovpack` 文件。
+
+#### 1. API 实现介绍
+
+将指定 URI 下的所有资源打包成 `.ovpack` 格式文件,用于备份或迁移。ROOT、ADMIN 和 USER 角色均可使用,仍受常规 URI 访问控制约束。
+
+**处理流程**:
+1. 验证用户权限
+2. 遍历指定 URI 下的资源
+3. 写入内容文件和 OVPack manifest
+4. 打包成 zip 格式(.ovpack)
+5. 以文件流形式返回
+
+**格式说明**:
+- 导出的 ZIP 会把用户内容原样放在 `<root>/files/` 下,并把内部元数据放在 `<root>/_ovpack/` 下。
+- manifest 位于 `<root>/_ovpack/manifest.json`。
+- `entries[].path` 是相对导出 root 的路径;`""` 表示 root 目录本身。
+- 文件条目包含 `size` 和 `sha256`;`content_sha256` 覆盖按路径排序后的文件列表(`path`、`size`、`sha256`)。
+- `_ovpack/index_records.jsonl` 保存可迁移的索引标量。`include_vectors=true` 时,`_ovpack/dense.f32` 保存纯 dense float32 向量快照和 embedding 元数据;底层 `VectorIndex.IndexType` 为 hybrid 时不支持向量快照导出。
+- `id`、`uri`、`account_id`、`created_at`、`updated_at`、`active_count` 等运行态字段会在目标环境重新生成,不从包内恢复。
+- OVPack 不额外设置包大小、文件数量或目录深度上限;实际可处理规模由 ZIP、存储后端和运行环境决定。
+
+**代码入口**:
+- `openviking/server/routers/pack.py:export_ovpack` - HTTP 路由
+- `openviking/service/pack_service.py` - 核心服务实现
+- `crates/ov_cli/src/handlers.rs:handle_export` - CLI 处理
+
+#### 2. 接口和参数说明
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| uri | string | 是 | - | 要导出的 Viking URI |
+| include_vectors | boolean | 否 | false | 导出纯 dense 向量快照;底层 index type 为 hybrid 时会拒绝 |
+
+**权限要求**:ROOT、ADMIN 或 USER
+
+#### 3. 使用示例
+
+
+**HTTP API**
+
+```
+POST /api/v1/pack/export
+Content-Type: application/json
+```
+
+```bash
+curl -X POST http://localhost:1933/api/v1/pack/export \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-admin-key" \
+ -d '{
+ "uri": "viking://resources/my-project/",
+ "include_vectors": false
+ }' \
+ --output my-project.ovpack
+```
+
+**Python SDK**
+
+```python
+import openviking as ov
+
+client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-admin-key")
+client.initialize()
+
+# 导出到本地文件(HTTP SDK 会自动处理下载)
+# 注意:导出功能主要通过 CLI 使用
+```
+
+**TypeScript SDK**
+
+```typescript
+const outputPath = await client.exportOVPack(
+ "viking://resources/docs/",
+ "./exports/docs.ovpack",
+ true,
+);
+console.log(outputPath);
+```
+
+**Go SDK**
+
+```go
+outPath, err := client.ExportOVPack(
+ ctx,
+ "viking://resources/my-project/",
+ "./exports/my-project.ovpack",
+ &openviking.PackOptions{IncludeVectors: false},
+)
+if err != nil {
+ return err
+}
+fmt.Println(outPath)
+```
+
+**CLI**
+
+```bash
+# 导出资源
+ov export viking://resources/my-project/ ./exports/my-project.ovpack
+
+# 导出 dense 向量快照
+ov export viking://resources/my-project/ ./exports/my-project.ovpack --include-vectors
+```
+
+
+**响应示例**
+
+此接口直接返回文件流(`Content-Type: application/zip`),不返回 JSON 包装体。
+
+---
+
+### import_ovpack
+
+导入 `.ovpack` 文件。
+
+#### 1. API 实现介绍
+
+将 `.ovpack` 文件导入到指定位置,用于恢复或迁移数据。ROOT、ADMIN 和 USER 角色均可使用,仍受常规 URI 访问控制约束。
+
+**处理流程**:
+1. 验证用户权限
+2. 解析上传的 `.ovpack` 文件
+3. 校验 manifest 元数据、路径、文件和目录集合、文件大小和 checksum
+4. 应用 `on_conflict`
+5. 导入资源到目标位置,并重建向量
+
+**代码入口**:
+- `openviking/server/routers/pack.py:import_ovpack` - HTTP 路由
+- `openviking/service/pack_service.py` - 核心服务实现
+- `crates/ov_cli/src/handlers.rs:handle_import` - CLI 处理
+
+#### 2. 接口和参数说明
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| temp_file_id | string | 是 | - | 临时上传文件 ID(通过 [temp_upload](02-resources.md#temp_upload) 获取) |
+| parent | string | 是 | - | 目标父级 URI(导入到此处) |
+| on_conflict | string | 否 | fail | 冲突策略:`fail`、`overwrite` 或 `skip` |
+| vector_mode | string | 否 | auto | 向量处理方式:`auto`、`recompute` 或 `require` |
+
+**权限要求**:ROOT、ADMIN 或 USER
+
+**行为说明**:
+- API 已不再接受 `vectorize` 或 `force`。
+- `vector_mode=auto` 会在存在兼容 dense 快照时直接恢复,否则重新向量化;`recompute` 总是忽略包内向量;`require` 要求必须存在兼容 dense 快照,否则导入失败。
+- dense 快照兼容性会比较 embedding provider、model、input、query/document 参数和维度。
+- Session 文件属于 user 命名空间(`viking://user/{user_id}/sessions/...`),恢复后不触发向量化。
+- `on_conflict=fail` 且目标 root 已存在时,会返回结构化的 `409 CONFLICT`。
+- `on_conflict=overwrite` 会替换已有目标 root。`on_conflict=skip` 会保留已有目标 root,并直接返回该路径,不写入包内容。`skip` 是 root 级跳过,不是文件级补齐。
+- 默认拒绝没有 manifest 的包,因为这类包无法提供内容完整性校验。
+- 带 manifest entries 的包如果缺少内容文件或目录、混入额外文件或目录、文件大小不同、单文件 `sha256` 不同,或整体 `content_sha256` 缺失/不匹配,都会被拒绝导入。
+- manifest `format_version` 不是当前支持版本(`3`)的包会被拒绝。
+- `.abstract.md` 和 `.overview.md` 会作为语义侧边文件恢复;`.relations.json` 和 OVPack 内部文件会被排除。
+- manifest index 标量中的 `context_type` 如果存在,必须和最终导入路径语义一致。
+- `viking://resources/` 这类顶级 scope 包必须导入到 `viking://`。
+- OVPack 不额外设置导入包大小、文件数量或目录深度上限;实际可处理规模由 ZIP、存储后端和运行环境决定。
+
+#### 3. 使用示例
+
+
+**HTTP API**
+
+```
+POST /api/v1/pack/import
+Content-Type: application/json
+```
+
+```bash
+# 第一步:上传 .ovpack 文件
+TEMP_FILE_ID=$(
+ curl -s -X POST http://localhost:1933/api/v1/resources/temp_upload \
+ -H "X-API-Key: your-admin-key" \
+ -F "file=@./exports/my-project.ovpack" \
+ | jq -r '.result.temp_file_id'
+)
+
+# 第二步:导入
+curl -X POST http://localhost:1933/api/v1/pack/import \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-admin-key" \
+ -d "{
+ \"temp_file_id\": \"$TEMP_FILE_ID\",
+ \"parent\": \"viking://resources/imported/\",
+ \"on_conflict\": \"overwrite\",
+ \"vector_mode\": \"auto\"
+ }"
+```
+
+**Python SDK**
+
+```python
+import openviking as ov
+
+client = ov.SyncHTTPClient(url="http://localhost:1933", api_key="your-admin-key")
+client.initialize()
+
+# 导入 .ovpack 文件(HTTP SDK 会自动处理上传)
+# 注意:导入功能主要通过 CLI 使用
+```
+
+**TypeScript SDK**
+
+```typescript
+const uri = await client.importOVPack(
+ "./exports/docs.ovpack",
+ "viking://resources/",
+ {
+ onConflict: "overwrite",
+ vectorMode: "auto",
+ },
+);
+console.log(uri);
+```
+
+**Go SDK**
+
+```go
+uri, err := client.ImportOVPack(
+ ctx,
+ "./exports/my-project.ovpack",
+ "viking://resources/imported/",
+ &openviking.ImportPackOptions{
+ OnConflict: "overwrite",
+ VectorMode: "auto",
+ },
+)
+if err != nil {
+ return err
+}
+fmt.Println(uri)
+```
+
+**CLI**
+
+```bash
+# 导入 .ovpack 文件
+ov import ./exports/my-project.ovpack viking://resources/imported/
+
+# 显式冲突策略
+ov import ./exports/my-project.ovpack viking://resources/imported/ --on-conflict overwrite
+
+# 要求恢复兼容 dense 向量快照
+ov import ./exports/my-project.ovpack viking://resources/imported/ --vector-mode require
+```
+
+
+**响应示例**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "uri": "viking://resources/imported/my-project/"
+ },
+ "telemetry": {
+ "operation_id": "550e8400-e29b-41d4-a716-446655440000"
+ }
+}
+```
+
+**冲突错误示例**
+
+```json
+{
+ "status": "error",
+ "error": {
+ "code": "CONFLICT",
+ "message": "Resource already exists at viking://resources/imported/my-project. Use on_conflict='overwrite' to replace it.",
+ "details": {
+ "resource": "viking://resources/imported/my-project"
+ }
+ }
+}
+```
+
+---
+
+### backup_ovpack
+
+将公开 scope root 备份为只能通过 restore 恢复的 `.ovpack` 文件。备份包含
+`resources` 和 `user`;session 会通过 user 命名空间下的 `user/{user_id}/sessions`
+一起包含,不包含 `temp`、`queue` 等内部运行态数据。
+设置 `include_vectors=true` 时,会额外导出兼容的纯 dense 向量快照;底层 index type 为 hybrid 时会拒绝导出向量快照。
+
+```
+POST /api/v1/pack/backup
+```
+
+```bash
+curl -X POST http://localhost:1933/api/v1/pack/backup \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-admin-key" \
+ -d '{"include_vectors":false}' \
+ --output openviking-backup.ovpack
+```
+
+Go SDK:
+
+```go
+outPath, err := client.BackupOVPack(
+ ctx,
+ "./backups/openviking.ovpack",
+ &openviking.PackOptions{IncludeVectors: true},
+)
+if err != nil {
+ return err
+}
+fmt.Println(outPath)
+```
+
+CLI:
+
+```bash
+ov backup ./backups/openviking.ovpack
+ov backup ./backups/openviking.ovpack --include-vectors
+```
+
+**响应**
+
+HTTP 成功时返回 `application/zip` 字节流,不使用标准 JSON 响应包:
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/zip
+Content-Disposition: attachment; filename="openviking-backup.ovpack"
+
+<ovpack binary body>
+```
+
+Go SDK 和 CLI 将字节流写入指定路径,并返回或输出该本地路径。
+
+---
+
+### restore_ovpack
+
+恢复 `backup_ovpack` 生成的备份包到原始公开 scope root。普通 import 不接受备份包。
+向量处理遵循 `vector_mode`;user 命名空间下的 session 文件只恢复文件状态,不触发向量化。
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| temp_file_id | string | 是 | - | 临时上传文件 ID |
+| on_conflict | string | 否 | fail | 冲突策略:`fail`、`overwrite` 或 `skip` |
+| vector_mode | string | 否 | auto | 向量处理方式:`auto`、`recompute` 或 `require` |
+
+```
+POST /api/v1/pack/restore
+Content-Type: application/json
+```
+
+```bash
+TEMP_FILE_ID=$(
+ curl -s -X POST http://localhost:1933/api/v1/resources/temp_upload \
+ -H "X-API-Key: your-admin-key" \
+ -F "file=@./backups/openviking.ovpack" \
+ | jq -r '.result.temp_file_id'
+)
+
+curl -X POST http://localhost:1933/api/v1/pack/restore \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-admin-key" \
+ -d "{\"temp_file_id\":\"$TEMP_FILE_ID\",\"on_conflict\":\"overwrite\",\"vector_mode\":\"auto\"}"
+```
+
+Go SDK:
+
+```go
+uri, err := client.RestoreOVPack(
+ ctx,
+ "./backups/openviking.ovpack",
+ &openviking.ImportPackOptions{
+ OnConflict: "overwrite",
+ VectorMode: "require",
+ },
+)
+if err != nil {
+ return err
+}
+fmt.Println(uri)
+```
+
+CLI:
+
+```bash
+ov restore ./backups/openviking.ovpack --on-conflict overwrite
+ov restore ./backups/openviking.ovpack --on-conflict overwrite --vector-mode require
+```
+
+**响应**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "uri": "viking://"
+ }
+}
+```
+
+`uri` 是备份恢复到的公开 scope root。
+
+---
+
+## 相关文档
+
+- [OVPack 指南](../guides/09-ovpack.md) - 格式、迁移和操作流程
+- [快照](11-snapshot.md) - 工作区版本管理
+- [临时上传](02-resources.md#temp_upload) - 上传待导入的包
diff --git a/docs/zh/api/15-watches.md b/docs/zh/api/15-watches.md
new file mode 100644
index 000000000..15dd713e0
--- /dev/null
+++ b/docs/zh/api/15-watches.md
@@ -0,0 +1,205 @@
+# 资源 Watch
+
+Watch API 管理资源的周期检查、暂停、恢复和手动触发。
+
+## 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`)三处镜像。
+
+#### 1. API 实现介绍
+
+此控制面封装了 `WatchManager` 原语,未改动任何服务端行为。每个端点和 CLI 命令都支持通过 `task_id`(路径)或 `to_uri`(查询参数)定位目标任务,两种键可以互换;如果同时提供,二者必须指向同一任务,否则返回 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` 可在不丢失配置周期的前提下暂停/恢复任务。
+- **删除**(`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),重新摄取在后台异步执行
+
+**代码入口**:
+- `openviking/server/routers/watches.py` — `/api/v1/watches` REST 路由
+- `crates/ov_cli/src/commands/watch.rs` — `ov task watch` CLI 子命令组
+- `openviking/server/mcp_endpoint.py` — MCP `list_watches` / `cancel_watch` 工具,以及 `add_resource` 上的 `watch_interval` / `to` 参数
+- `openviking/resource/watch_manager.py:WatchManager` — 任务持久化与调度原语
+
+#### 2. 接口和参数说明
+
+对每个单任务端点,路径中的 `{task_id}` 都可用查询参数 `?to_uri=` 替代。CLI 的 `<key>` 参数会自动分类:任何以 `viking://` 开头的值走 by-URI 路径,其他值视为 task_id(其它 scheme 如 `http://` 会在本地直接报错,避免静默 404)。
+
+**`PATCH /watches` 请求体**(字段均可选,至少需提供一个)
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| watch_interval | float | 新的检查周期(分钟),必须 `> 0`;如需暂停而保留周期请改用 `is_active=false`。 |
+| is_active | bool | 切换激活状态而保留配置周期(暂停 / 恢复)。 |
+| reason | string | 更新该监控任务的记录原因。 |
+| instruction | string | 更新语义处理指令。 |
+
+未识别字段会被拒绝,并返回 HTTP `400` 和 `INVALID_ARGUMENT`(请求模型使用 `extra="forbid"`)。未传字段保留原值。
+
+#### 3. 使用示例
+
+**HTTP API**
+
+```bash
+# 列出活跃监控任务(去掉 ?active_only 可同时包含已暂停的任务)
+curl -s "http://localhost:1933/api/v1/watches?active_only=true" \
+ -H "X-API-Key: your-key"
+
+# 暂停一个监控任务而保留其检查周期
+curl -X PATCH "http://localhost:1933/api/v1/watches/<task_id>" \
+ -H "X-API-Key: your-key" -H "Content-Type: application/json" \
+ -d '{"is_active": false}'
+
+# 触发一次立即刷新(fire-and-forget,立即返回,再次摄取在后台执行)
+curl -X POST "http://localhost:1933/api/v1/watches/<task_id>/trigger" \
+ -H "X-API-Key: your-key"
+
+# 按 URI 而非 task_id 定位任务
+curl -X DELETE "http://localhost:1933/api/v1/watches?to_uri=viking://resources/guide.md" \
+ -H "X-API-Key: your-key"
+```
+
+**Python SDK**
+
+```python
+watches = client.list_watches(active_only=True)
+client.update_watch(to_uri="viking://resources/guide.md", is_active=False)
+client.trigger_watch(to_uri="viking://resources/guide.md")
+client.delete_watch(to_uri="viking://resources/guide.md")
+```
+
+**TypeScript SDK**
+
+```typescript
+const watches = await client.listWatches({ activeOnly: true });
+await client.updateWatch(
+ { toUri: "viking://resources/guide.md" },
+ { isActive: false },
+);
+await client.triggerWatch({ toUri: "viking://resources/guide.md" });
+await client.deleteWatch({ toUri: "viking://resources/guide.md" });
+```
+
+**Go SDK**
+
+```go
+watches, err := client.ListWatches(ctx, &openviking.ListWatchesOptions{
+ ActiveOnly: true,
+})
+updated, err := client.UpdateWatch(ctx, openviking.UpdateWatchOptions{
+ ToURI: "viking://resources/guide.md",
+ IsActive: openviking.Bool(false),
+})
+triggered, err := client.TriggerWatch(ctx, openviking.WatchRef{
+ ToURI: "viking://resources/guide.md",
+})
+deleted, err := client.DeleteWatch(ctx, openviking.WatchRef{
+ ToURI: "viking://resources/guide.md",
+})
+_, _, _, _ = watches, updated, triggered, deleted
+```
+
+**CLI**
+
+以下示例使用 `ov task watch` 子命令:
+
+```bash
+# 列出活跃监控任务(去掉 --active-only 可同时包含已暂停的任务)
+ov task watch ls --active-only
+
+# 查看单个监控任务(key 可以是 viking:// URI 或 task_id)
+ov task watch show viking://resources/guide.md
+
+# 暂停 / 恢复,不丢失配置周期
+ov task watch pause viking://resources/guide.md
+ov task watch resume viking://resources/guide.md
+
+# 更新周期(或 --active / --reason / --instruction 的任意组合)
+ov task watch update viking://resources/guide.md --interval 30
+
+# 触发一次立即刷新(fire-and-forget)
+ov task watch trigger viking://resources/guide.md
+
+# 删除监控任务
+ov task watch rm viking://resources/guide.md
+```
+
+**响应**
+
+列出任务时返回:
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "tasks": [
+ {
+ "task_id": "7f02e980-8df9-4f27-a570-4d8428cbed8a",
+ "path": "https://example.com/guide.md",
+ "to_uri": "viking://resources/guide.md",
+ "parent_uri": "viking://resources",
+ "reason": "keep documentation current",
+ "instruction": "",
+ "watch_interval": 30,
+ "build_index": true,
+ "summarize": false,
+ "processor_kwargs": {},
+ "created_at": "2026-07-24T10:00:00",
+ "last_execution_time": null,
+ "next_execution_time": "2026-07-24T10:30:00",
+ "is_active": true,
+ "account_id": "default",
+ "user_id": "default",
+ "original_role": "user"
+ }
+ ],
+ "total": 1
+ }
+}
+```
+
+查看单个任务以及成功更新时,`result` 直接是同一结构的任务对象。删除和触发分别返回:
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "task_id": "7f02e980-8df9-4f27-a570-4d8428cbed8a",
+ "to_uri": "viking://resources/guide.md",
+ "deleted": true
+ }
+}
+```
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "task_id": "7f02e980-8df9-4f27-a570-4d8428cbed8a",
+ "to_uri": "viking://resources/guide.md",
+ "scheduled": true
+ }
+}
+```
+
+`scheduled=true` 只表示后台执行已调度,不表示重新摄取已经完成;应再次查看任务的 `last_execution_time`。
+
+**MCP**(Agent 控制面——仅最小闭包)
+
+```text
+list_watches() # 每个任务一行;只暴露 URI,不暴露 task_id
+cancel_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`。
+
+---
+
+## 相关文档
+
+- [资源](02-resources.md) - 创建带 watch_interval 的资源
+- [后台任务](17-tasks.md) - 查询后台处理状态
diff --git a/docs/zh/api/16-memory.md b/docs/zh/api/16-memory.md
new file mode 100644
index 000000000..3e33e9dc1
--- /dev/null
+++ b/docs/zh/api/16-memory.md
@@ -0,0 +1,147 @@
+# 记忆
+
+记忆由会话提交或显式提取生成,存储在用户记忆命名空间中,并可通过内容、文件系统和检索 API 使用。
+
+## 内置记忆类型
+
+| 分类 | 位置 | 说明 |
+|------|------|------|
+| 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/` | 技能执行经验与工作流策略 |
+
+以上是当前启用的内置类型;部署可以通过自定义记忆模板扩展或覆盖。
+
+---
+
+## API 参考
+
+### recall()
+
+按记忆类型分别检索,并在字符预算内组合成可直接注入 Agent 上下文的记忆块。默认检索 `events`、`entities` 和 `preferences`;`experiences` 默认配额为 `0`,需要时应显式开启。
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `query` | string | 是 | - | 召回查询 |
+| `quotas` | object | 否 | `events=10, entities=10, preferences=3, experiences=0` | 各类型最大返回数 |
+| `max_chars` | integer | 否 | `6500` | 渲染后记忆块的最大字符数 |
+| `min_score` | number | 否 | `0.1` | 最低相关性分数 |
+| `peer_scope` | string | 否 | `all` | `actor` 只检索当前 actor peer;`all` 同时检索用户全局和其他 peer |
+| `other_peer_penalty` | number/object | 否 | 按类型默认值 | 对其他 peer 结果施加的分数折损 |
+| `render` | boolean | 否 | `true` | 是否生成 `rendered` 记忆块 |
+
+**HTTP API**
+
+```http
+POST /api/v1/search/recall
+Content-Type: application/json
+```
+
+```bash
+curl -X POST http://localhost:1933/api/v1/search/recall \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-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"
+)
+```
+
+**响应**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "entries": [
+ {
+ "uri": "viking://user/default/memories/preferences/api-docs.md",
+ "score": 0.82,
+ "type": "preferences",
+ "mode": "full",
+ "rank": 1,
+ "content": "用户偏好在 API 文档中同时提供 HTTP、SDK 和 CLI 示例。",
+ "origin": "self"
+ }
+ ],
+ "rendered": "## Global Memory\n### Preferences\n[1] viking://user/default/memories/preferences/api-docs.md (score=0.8200)\n用户偏好在 API 文档中同时提供 HTTP、SDK 和 CLI 示例。",
+ "stats": {
+ "quotas": {
+ "events": 5,
+ "entities": 5,
+ "preferences": 3,
+ "experiences": 2
+ },
+ "roots": [
+ "viking://user/default/memories"
+ ],
+ "searched": {
+ "events": 2,
+ "entities": 1,
+ "preferences": 1,
+ "experiences": 0
+ },
+ "returned": 1,
+ "dropped": 0,
+ "max_chars": 6500,
+ "min_score": 0.1,
+ "peer_scope": "all",
+ "other_peer_penalties": {
+ "events": 0.1,
+ "entities": 0.1,
+ "preferences": 0.02,
+ "experiences": 0.02
+ },
+ "origins": {
+ "actor_peer": 0,
+ "self": 1,
+ "other_peer": 0
+ }
+ }
+ }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `entries` | object[] | 结构化召回结果,按类型配额和相关性筛选 |
+| `entries[].uri` | string | 记忆条目的 Viking URI |
+| `entries[].score` | number | 原始相关性分数 |
+| `entries[].type` | string | `events`、`entities`、`preferences` 或 `experiences` |
+| `entries[].mode` | string | 渲染方式:`full`、`summary` 或 `uri` |
+| `entries[].rank` | integer | 该记忆类型内的排名,从 `1` 开始 |
+| `entries[].origin` | string | 来源:`actor_peer`、`self` 或 `other_peer` |
+| `entries[].content` | string | `mode=full` 时返回的正文;否则可能省略 |
+| `entries[].summary` | string | 使用摘要降级时返回;否则可能省略 |
+| `entries[].abstract` | string | 检索命中的摘要;没有摘要时省略 |
+| `rendered` | string | 已受 `max_chars` 限制、可直接注入 Agent 上下文的文本;`render=false` 时为空字符串 |
+| `stats` | object | 实际配额、检索根、各类型检索量、返回量、丢弃量、阈值、peer 范围及来源统计 |
+
+公共 Python、TypeScript、Go SDK 和 `ov` CLI 当前尚未封装类型配额召回,因此本节只展示 HTTP Tab,并补充实际存在的 MCP 调用。
+
+## 相关文档
+
+- [会话](05-sessions.md) - commit 与 extract
+- [检索](06-retrieval.md) - 搜索记忆
+- [内容](12-content.md) - 读取记忆内容
diff --git a/docs/zh/api/17-tasks.md b/docs/zh/api/17-tasks.md
new file mode 100644
index 000000000..37dff6130
--- /dev/null
+++ b/docs/zh/api/17-tasks.md
@@ -0,0 +1,250 @@
+# 后台任务
+
+任务 API 用于跟踪资源导入、会话提交、索引维护和快照恢复等异步操作。
+
+## API 参考
+
+### get_task()
+
+#### 1. API 实现介绍
+
+查询返回 `task_id` 的后台任务状态,例如 session commit、`add_resource` 和 admin reindex。
+
+**任务状态**:
+- `pending`: 任务等待执行
+- `running`: 任务执行中
+- `completed`: 任务成功完成
+- `failed`: 任务失败
+
+**代码入口**:
+- `openviking/server/routers/tasks.py:get_task()` - HTTP 路由
+
+任务记录会持久化到 AGFS,服务重启后仍可查询,但仍受任务保留清理策略影响。
+
+#### 2. 接口和参数说明
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| task_id | str | 是 | - | 后台 API 返回的任务 ID |
+
+#### 3. 使用示例
+
+**HTTP API**
+
+```http
+GET /api/v1/tasks/{task_id}
+```
+
+```bash
+curl -X GET http://localhost:1933/api/v1/tasks/uuid-xxx \
+ -H "X-API-Key: your-key"
+```
+
+**Python SDK**
+
+```python
+from openviking_sdk import AsyncHTTPClient
+
+client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")
+await client.initialize()
+
+task = await client.get_task("uuid-xxx")
+print(f"Status: {task['status']}")
+await client.close()
+```
+
+**TypeScript SDK**
+
+```typescript
+console.log(await client.getTask("task-id"));
+```
+
+**Go SDK**
+
+```go
+task, err := client.GetTask(ctx, "uuid-xxx")
+if err != nil {
+ return err
+}
+if task != nil {
+ fmt.Println(task["status"])
+}
+```
+
+**CLI**
+
+```bash
+ov task status uuid-xxx
+```
+
+**响应示例(资源导入进行中)**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "task_id": "uuid-xxx",
+ "task_type": "add_resource",
+ "status": "running",
+ "resource_id": "viking://resources/guide",
+ "stage": "processing_queue"
+ }
+}
+```
+
+`stage` 可以为 `null`。Git 仓库资源导入任务可能报告 `queued`、`fetching`、`parsing`、`finalizing`、`processing_queue`;其他任务类型可能将其留空。实时队列计数不会出现在任务状态中;需要实时数量时使用 observer queue,任务完成后可读取 `result.queue_status`。
+
+**响应示例(完成)**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "task_id": "uuid-xxx",
+ "task_type": "session_commit",
+ "status": "completed",
+ "result": {
+ "session_id": "a1b2c3d4",
+ "archive_uri": "viking://user/alice/sessions/a1b2c3d4/history/archive_001",
+ "memory_diff_uri": "viking://user/alice/sessions/a1b2c3d4/history/archive_001/memory_diff.json",
+ "memories_extracted": {
+ "profile": 1,
+ "preferences": 2,
+ "entities": 1,
+ "cases": 1
+ },
+ "active_count_updated": 2,
+ "token_usage": {
+ "llm": {
+ "prompt_tokens": 5200,
+ "completion_tokens": 1800,
+ "total_tokens": 7000
+ },
+ "embedding": {
+ "total_tokens": 1500
+ },
+ "total": {
+ "total_tokens": 8500
+ }
+ }
+ }
+ }
+}
+```
+
+---
+
+### list_tasks()
+
+#### 1. API 实现介绍
+
+列出当前调用方可见的后台任务,支持按类型、状态、资源过滤。
+
+**代码入口**:
+- `openviking/server/routers/tasks.py:list_tasks()` - HTTP 路由
+- `openviking_cli/client/base.py:BaseClient.list_tasks()` - Python SDK
+
+#### 2. 接口和参数说明
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| task_type | str | 否 | None | 按任务类型过滤,例如 `session_commit` |
+| status | str | 否 | None | 按任务状态过滤:`pending`、`running`、`completed`、`failed` |
+| resource_id | str | 否 | None | 按资源 ID 过滤,例如会话 ID |
+| limit | int | 否 | 50 | 最多返回的任务条数 |
+
+#### 3. 使用示例
+
+**HTTP API**
+
+```http
+GET /api/v1/tasks?task_type=session_commit&status=running&limit=20
+```
+
+```bash
+curl -X GET "http://localhost:1933/api/v1/tasks?task_type=session_commit&status=running&limit=20" \
+ -H "X-API-Key: your-key"
+```
+
+**Python SDK**
+
+```python
+from openviking_sdk import AsyncHTTPClient
+
+client = AsyncHTTPClient(url="http://localhost:1933", api_key="your-key")
+await client.initialize()
+
+tasks = await client.list_tasks(
+ task_type="session_commit",
+ status="running",
+ limit=20,
+)
+for task in tasks:
+ print(task["task_id"], task["status"])
+await client.close()
+```
+
+**TypeScript SDK**
+
+```typescript
+console.log(await client.listTasks());
+```
+
+**Go SDK**
+
+```go
+tasks, err := client.ListTasks(ctx, &openviking.ListTasksOptions{
+ TaskType: "session_commit",
+ Status: "running",
+ Limit: 20,
+})
+if err != nil {
+ return err
+}
+for _, task := range tasks {
+ fmt.Println(task)
+}
+```
+
+**CLI**
+
+```bash
+# 列出任务
+ov task list
+
+# 按任务类型和状态过滤
+ov task list --task-type session_commit --status running
+```
+
+**响应示例**
+
+```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,
+ "stage": null
+ }
+ ]
+}
+```
+
+---
+
+## 相关文档
+
+- [会话](05-sessions.md) - 会话提交任务
+- [资源](02-resources.md) - 资源导入任务
+- [内容](12-content.md) - 异步 reindex 任务
diff --git a/docs/zh/api/18-observer.md b/docs/zh/api/18-observer.md
new file mode 100644
index 000000000..980f94115
--- /dev/null
+++ b/docs/zh/api/18-observer.md
@@ -0,0 +1,520 @@
+# 运行观测
+
+Observer API 提供队列、向量库、模型、锁、检索和文件系统等组件的即时状态。
+
+## Observer API
+
+Observer API 提供详细的组件级监控。
+
+### observer.queue
+
+#### 1. API 实现介绍
+
+获取队列系统状态(embedding 和语义处理队列)。显示各队列的待处理、进行中、已完成和错误数量。
+
+**代码入口**:
+- `openviking/server/routers/observer.py:observer_queue` - HTTP 路由
+- `openviking/service/debug_service.py:ObserverService.queue` - 核心实现
+- `openviking/storage/observers/queue_observer.py` - 队列观察者
+
+#### 2. 接口和参数说明
+
+无参数。
+
+#### 3. 使用示例
+
+**HTTP API**
+
+```
+GET /api/v1/observer/queue
+```
+
+```bash
+curl -X GET http://localhost:1933/api/v1/observer/queue \
+ -H "X-API-Key: your-key"
+```
+
+**Python SDK**
+
+```python
+print(client.observer.queue())
+# 输出:
+# [queue] (healthy)
+# Queue Pending In Progress Processed Errors Total
+# Embedding 0 0 10 0 10
+# Semantic 0 0 10 0 10
+# TOTAL 0 0 20 0 20
+```
+
+**TypeScript SDK**
+
+```typescript
+console.log(await client.queueStatus());
+```
+
+**Go SDK**
+
+```go
+status, err := client.QueueStatus(ctx)
+if err != nil {
+ return err
+}
+fmt.Println(status["is_healthy"])
+```
+
+**CLI**
+
+```bash
+ov observer queue
+```
+
+**响应示例**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "name": "queue",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "Queue Pending In Progress Processed Errors Total\nEmbedding 0 0 10 0 10\nSemantic 0 0 10 0 10\nTOTAL 0 0 20 0 20"
+ },
+ "time": 0.1
+}
+```
+
+---
+
+### observer.vikingdb
+
+#### 1. API 实现介绍
+
+获取 VikingDB 状态(集合、索引、向量数量)。
+
+**代码入口**:
+- `openviking/server/routers/observer.py:observer_vikingdb` - HTTP 路由
+- `openviking/service/debug_service.py:ObserverService.vikingdb` - 核心实现
+- `openviking/storage/observers/vikingdb_observer.py` - VikingDB 观察者
+- `crates/ov_cli/src/commands/observer.rs` - CLI 命令
+
+#### 2. 接口和参数说明
+
+无参数。
+
+#### 3. 使用示例
+
+**HTTP API**
+
+```
+GET /api/v1/observer/vikingdb
+```
+
+```bash
+curl -X GET http://localhost:1933/api/v1/observer/vikingdb \
+ -H "X-API-Key: your-key"
+```
+
+**Python SDK**
+
+```python
+print(client.observer.vikingdb())
+# 输出:
+# [vikingdb] (healthy)
+# Collection Index Count Vector Count Status
+# context 1 55 OK
+# TOTAL 1 55
+
+# 访问特定属性
+print(client.observer.vikingdb().is_healthy) # True
+print(client.observer.vikingdb().status) # 状态表字符串
+```
+
+**TypeScript SDK**
+
+```typescript
+console.log(await client.vikingDBStatus());
+```
+
+**Go SDK**
+
+```go
+status, err := client.VikingDBStatus(ctx)
+if err != nil {
+ return err
+}
+fmt.Println(status["is_healthy"])
+```
+
+**CLI**
+
+```bash
+ov observer vikingdb
+```
+
+**响应示例**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "name": "vikingdb",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "Collection Index Count Vector Count Status\ncontext 1 55 OK\nTOTAL 1 55"
+ },
+ "time": 0.1
+}
+```
+
+---
+
+### observer.models
+
+#### 1. API 实现介绍
+
+获取模型子系统的聚合状态(VLM、embedding、rerank)。检查各模型提供者是否健康可用。
+
+**代码入口**:
+- `openviking/server/routers/observer.py:observer_models` - HTTP 路由
+- `openviking/service/debug_service.py:ObserverService.models` - 核心实现
+- `openviking/storage/observers/models_observer.py` - 模型观察者
+- `crates/ov_cli/src/commands/observer.rs` - CLI 命令
+
+#### 2. 接口和参数说明
+
+无参数。
+
+#### 3. 使用示例
+
+**HTTP API**
+
+```
+GET /api/v1/observer/models
+```
+
+```bash
+curl -X GET http://localhost:1933/api/v1/observer/models \
+ -H "X-API-Key: your-key"
+```
+
+**Python SDK**
+
+```python
+print(client.observer.models())
+# 输出:
+# [models] (healthy)
+# provider_model healthy detail
+# dense_embedding yes ...
+# rerank yes ...
+# vlm yes ...
+```
+
+**TypeScript SDK**
+
+```typescript
+console.log(await client.modelsStatus());
+```
+
+**Go SDK**
+
+```go
+status, err := client.ModelsStatus(ctx)
+if err != nil {
+ return err
+}
+fmt.Println(status["is_healthy"])
+```
+
+**CLI**
+
+```bash
+ov observer models
+```
+
+**响应示例**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "name": "models",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "provider_model healthy detail\ndense_embedding yes ...\nrerank yes ...\nvlm yes ..."
+ },
+ "time": 0.1
+}
+```
+
+---
+
+### observer.lock
+
+#### 1. API 实现介绍
+
+获取分布式锁系统状态。
+
+**代码入口**:
+- `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. 接口和参数说明
+
+无参数。
+
+#### 3. 使用示例
+
+**HTTP API**
+
+```
+GET /api/v1/observer/lock
+```
+
+```bash
+curl -X GET http://localhost:1933/api/v1/observer/lock \
+ -H "X-API-Key: your-key"
+```
+
+公开 SDK 和 CLI 目前没有单独的 lock observer 方法。请使用 HTTP API 查询该组件;`ov observer system` 会在汇总状态中包含它。
+
+**响应示例**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "name": "lock",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "..."
+ },
+ "time": 0.1
+}
+```
+
+---
+
+### observer.retrieval
+
+#### 1. API 实现介绍
+
+获取检索质量指标。
+
+**代码入口**:
+- `openviking/server/routers/observer.py:observer_retrieval` - HTTP 路由
+- `openviking/service/debug_service.py:ObserverService.retrieval` - 核心实现
+- `openviking/storage/observers/retrieval_observer.py` - 检索观察者
+- `crates/ov_cli/src/commands/observer.rs` - CLI 命令
+
+#### 2. 接口和参数说明
+
+无参数。
+
+#### 3. 使用示例
+
+**HTTP API**
+
+```
+GET /api/v1/observer/retrieval
+```
+
+```bash
+curl -X GET http://localhost:1933/api/v1/observer/retrieval \
+ -H "X-API-Key: your-key"
+```
+
+**CLI**
+
+```bash
+ov observer retrieval
+```
+
+**响应示例**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "name": "retrieval",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "..."
+ },
+ "time": 0.1
+}
+```
+
+---
+
+### observer.filesystem
+
+#### 1. API 实现介绍
+
+获取文件系统操作指标。
+
+**代码入口**:
+- `openviking/server/routers/observer.py:observer_filesystem` - HTTP 路由
+- `openviking/service/debug_service.py:ObserverService.filesystem` - 核心实现
+- `openviking/storage/observers/filesystem_observer.py` - 文件系统观察者
+- `crates/ov_cli/src/commands/observer.rs` - CLI 命令
+
+#### 2. 接口和参数说明
+
+无参数。
+
+#### 3. 使用示例
+
+**HTTP API**
+
+```
+GET /api/v1/observer/filesystem
+```
+
+```bash
+curl -X GET http://localhost:1933/api/v1/observer/filesystem \
+ -H "X-API-Key: your-key"
+```
+
+**CLI**
+
+```bash
+ov observer filesystem
+```
+
+**响应示例**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "name": "filesystem",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "..."
+ },
+ "time": 0.1
+}
+```
+
+---
+
+### observer.system
+
+#### 1. API 实现介绍
+
+获取整体系统状态,包括所有组件(queue、vikingdb、models、lock、retrieval)。
+
+**代码入口**:
+- `openviking/server/routers/observer.py:observer_system` - HTTP 路由
+- `openviking/service/debug_service.py:ObserverService.system` - 核心实现
+- `crates/ov_cli/src/commands/observer.rs` - CLI 命令
+
+#### 2. 接口和参数说明
+
+无参数。
+
+#### 3. 使用示例
+
+**HTTP API**
+
+```
+GET /api/v1/observer/system
+```
+
+```bash
+curl -X GET http://localhost:1933/api/v1/observer/system \
+ -H "X-API-Key: your-key"
+```
+
+**Python SDK**
+
+```python
+print(client.observer.system())
+# 输出:
+# [queue] (healthy)
+# ...
+#
+# [vikingdb] (healthy)
+# ...
+#
+# [models] (healthy)
+# ...
+#
+# [system] (healthy)
+```
+
+**TypeScript SDK**
+
+```typescript
+console.log(await client.getStatus());
+```
+
+**Go SDK**
+
+```go
+status, err := client.GetStatus(ctx)
+if err != nil {
+ return err
+}
+fmt.Println(status["is_healthy"])
+```
+
+**CLI**
+
+```bash
+ov observer system
+```
+
+**响应示例**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "is_healthy": true,
+ "errors": [],
+ "components": {
+ "queue": {
+ "name": "queue",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "..."
+ },
+ "vikingdb": {
+ "name": "vikingdb",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "..."
+ },
+ "models": {
+ "name": "models",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "..."
+ },
+ "lock": {
+ "name": "lock",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "..."
+ },
+ "retrieval": {
+ "name": "retrieval",
+ "is_healthy": true,
+ "has_errors": false,
+ "status": "..."
+ }
+ }
+ },
+ "time": 0.1
+}
+```
+
+---
+
+## 相关文档
+
+- [Metrics](09-metrics.md) - Prometheus 指标抓取
+- [系统状态](07-system.md) - 健康检查和一致性检查
diff --git a/docs/zh/api/20-webdav.md b/docs/zh/api/20-webdav.md
new file mode 100644
index 000000000..32e2fe835
--- /dev/null
+++ b/docs/zh/api/20-webdav.md
@@ -0,0 +1,136 @@
+# WebDAV
+
+WebDAV 为 `resources` 命名空间提供文件协议访问。
+
+**代码入口**:`openviking/server/routers/webdav.py`
+
+## WebDAV(Phase 1)
+
+OpenViking Server 也提供了一个面向资源文件的精简 WebDAV 适配层:
+
+```text
+/webdav/resources
+```
+
+Phase 1 有意把范围控制得比较小:
+
+- 仅开放 `resources` 命名空间,不暴露 memories、skills、sessions 等其他空间。
+- 以文本写入为主,当前 `PUT` 只接受 UTF-8 文本内容。
+- 只实现一小部分 WebDAV 方法:`OPTIONS`、`PROPFIND`、`GET`、`HEAD`、`PUT`、`DELETE`、`MKCOL`、`MOVE`。
+- 语义侧边文件和系统内部文件保持内部可见。`.abstract.md`、`.overview.md`、`.relations.json`、`.path.ovlock`、`.redirect.json`、`.sync_log.json` 这些派生或内部文件不会出现在 WebDAV 列表中,也不能被直接访问。
+
+行为说明:
+
+- 通过 WebDAV 新建文件时,会对该文件路径触发 OpenViking 的语义生成。
+- 通过 WebDAV 覆盖已有文件时,会像 `write()` 一样刷新相关语义和向量。
+- `PUT` 不会自动创建父目录。缺失的目录需要先用 `MKCOL` 创建。
+- 用户自己创建的点目录或点文件仍然可见,只有上面列出的保留内部文件名会被隐藏。
+- 启用多写存储时,被 redirect 到 backup 的文件仍会通过文件系统 API 呈现为普通文件;内部 redirect 和同步元数据不会暴露给调用方。
+
+## API 参考
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| `OPTIONS` | `/webdav/resources`、`/webdav/resources/{resource_path}` | 返回支持的方法和 DAV 版本 |
+| `PROPFIND` | `/webdav/resources`、`/webdav/resources/{resource_path}` | 返回目标及一级子项属性 |
+| `GET` / `HEAD` | `/webdav/resources`、`/webdav/resources/{resource_path}` | 读取文件内容或响应头 |
+| `PUT` | `/webdav/resources`、`/webdav/resources/{resource_path}` | 创建或覆盖 UTF-8 文本文件 |
+| `DELETE` | `/webdav/resources`、`/webdav/resources/{resource_path}` | 删除文件或递归删除目录 |
+| `MKCOL` | `/webdav/resources`、`/webdav/resources/{resource_path}` | 创建目录 |
+| `MOVE` | `/webdav/resources`、`/webdav/resources/{resource_path}` | 移动或重命名文件/目录 |
+
+除 `OPTIONS` 外,WebDAV 请求使用与其他 OpenViking API 相同的认证头。路径必须位于 `resources` 下,不能通过 `..`、反斜杠或其他形式逃逸命名空间。
+
+| 请求头 | 使用方法 | 必填 | 说明 |
+|--------|----------|------|------|
+| `X-API-Key` | 除 `OPTIONS` 外 | 是 | OpenViking API Key |
+| `Depth` | `PROPFIND` | 否 | `0` 仅返回目标;其他值按一级深度处理 |
+| `Destination` | `MOVE` | 是 | `/webdav/resources` 下的目标路径 |
+| `Overwrite` | `MOVE` | 否 | 默认 `T`;设为 `F` 时不覆盖已有目标 |
+
+### 查询目录
+
+`Depth` 仅支持 `0` 和一级深度;其他值按一级处理。成功时返回 `207 Multi-Status` 和 DAV XML。
+
+**HTTP API**
+
+```bash
+curl -X PROPFIND http://localhost:1933/webdav/resources/docs \
+ -H "X-API-Key: your-key" \
+ -H "Depth: 1"
+```
+
+**响应示例**
+
+```xml
+<?xml version='1.0' encoding='utf-8'?>
+<d:multistatus xmlns:d="DAV:">
+ <d:response>
+ <d:href>/webdav/resources/docs/</d:href>
+ <d:propstat>
+ <d:prop>
+ <d:displayname>docs</d:displayname>
+ <d:resourcetype><d:collection /></d:resourcetype>
+ <d:getcontenttype>httpd/unix-directory</d:getcontenttype>
+ </d:prop>
+ <d:status>HTTP/1.1 200 OK</d:status>
+ </d:propstat>
+ </d:response>
+</d:multistatus>
+```
+
+### 读取与写入文件
+
+`PUT` 不会创建父目录。创建文件返回 `201`,覆盖文件返回 `204`;非 UTF-8 内容返回 `415`。
+
+**HTTP API**
+
+```bash
+curl http://localhost:1933/webdav/resources/docs/readme.md \
+ -H "X-API-Key: your-key"
+```
+
+```bash
+curl -X PUT http://localhost:1933/webdav/resources/docs/readme.md \
+ -H "X-API-Key: your-key" \
+ -H "Content-Type: text/plain; charset=utf-8" \
+ --data-binary @README.md
+```
+
+### 创建、移动和删除
+
+`MOVE` 必须提供 `Destination` 头,且目标仍位于 `/webdav/resources` 下。目标父目录必须已经存在。
+
+**HTTP API**
+
+```bash
+curl -X MKCOL http://localhost:1933/webdav/resources/archive \
+ -H "X-API-Key: your-key"
+```
+
+```bash
+curl -X MOVE http://localhost:1933/webdav/resources/docs/readme.md \
+ -H "X-API-Key: your-key" \
+ -H "Destination: /webdav/resources/archive/readme.md"
+```
+
+```bash
+curl -X DELETE http://localhost:1933/webdav/resources/archive \
+ -H "X-API-Key: your-key"
+```
+
+**状态码**
+
+| 操作 | 成功状态 | 常见失败 |
+|------|----------|----------|
+| `GET` / `HEAD` | `200` | `404` 不存在;`405` 目标是目录 |
+| `PUT` | `201` 新建;`204` 覆盖 | `409` 父目录不存在;`415` 不是 UTF-8 |
+| `MKCOL` | `201` | `405` 已存在;`409` 父目录不存在 |
+| `MOVE` | `201` 新目标;`204` 覆盖 | `400` 缺少目标;`409` 目标父目录不存在;`412` 禁止覆盖 |
+| `DELETE` | `204` | `404` 不存在;`405` 尝试删除根目录 |
+
+WebDAV 是协议入口,不对应 OpenViking SDK 或 `ov` CLI 方法,因此本页只展示 HTTP Tab。需要 SDK/CLI 文件操作时使用[文件系统](03-filesystem.md)。
+
+## 相关文档
+
+- [文件系统](03-filesystem.md) - 对应的 HTTP、SDK 和 CLI 文件操作
diff --git a/docs/zh/api/21-code.md b/docs/zh/api/21-code.md
new file mode 100644
index 000000000..d58ef90a5
--- /dev/null
+++ b/docs/zh/api/21-code.md
@@ -0,0 +1,119 @@
+# 代码导航
+
+代码导航 API 对已经导入 OpenViking 的源代码执行结构提取、符号搜索和符号展开。所有 `uri` 必须是 `viking://` URI;本地代码需要先通过资源 API 导入。
+
+**代码入口**:
+
+- `openviking/server/routers/code.py` - HTTP 路由与请求模型
+- `openviking/parse/parsers/code/ast/code_tools.py` - 大纲、搜索和符号展开实现
+
+## API 参考
+
+### outline()
+
+提取单个源文件的符号大纲。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `uri` | string | 是 | 已导入源文件的 `viking://` URI |
+
+**HTTP API**
+
+```http
+POST /api/v1/code/outline
+Content-Type: application/json
+```
+
+```bash
+curl -X POST http://localhost:1933/api/v1/code/outline \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{"uri":"viking://resources/project/src/main.py"}'
+```
+
+**响应示例**
+
+`result` 是适合直接展示或注入 Agent 上下文的文本大纲。
+
+```json
+{
+ "status": "ok",
+ "result": "viking://resources/project/src/main.py [python, 24 lines]\n\nclass SessionService L16-24\n\ndef main() L8-12"
+}
+```
+
+### search()
+
+在指定目录下的受支持源文件中搜索符号。一次请求最多扫描 200 个文件;达到上限时,`result` 末尾会提示缩小 URI 范围。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `uri` | string | 是 | 要递归搜索的文件或目录 URI |
+| `query` | string | 是 | 非空的符号名称或搜索词 |
+
+**HTTP API**
+
+```http
+POST /api/v1/code/search
+Content-Type: application/json
+```
+
+```bash
+curl -X POST http://localhost:1933/api/v1/code/search \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{"uri":"viking://resources/project/src","query":"SessionService"}'
+```
+
+**响应示例**
+
+```json
+{
+ "status": "ok",
+ "result": "1 matches for \"SessionService\" (scanned 8 files)\n\nviking://resources/project/src/session.py\n SessionService L16-24"
+}
+```
+
+### expand()
+
+读取单个文件中指定符号的完整代码片段。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `uri` | string | 是 | 包含目标符号的源文件 URI |
+| `symbol` | string | 是 | 要展开的非空符号名称 |
+
+**HTTP API**
+
+```http
+POST /api/v1/code/expand
+Content-Type: application/json
+```
+
+```bash
+curl -X POST http://localhost:1933/api/v1/code/expand \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{"uri":"viking://resources/project/src/main.py","symbol":"main"}'
+```
+
+**响应示例**
+
+```json
+{
+ "status": "ok",
+ "result": "# viking://resources/project/src/main.py L8-10 (main)\n\ndef main():\n service = SessionService()\n service.run()"
+}
+```
+
+当前实现把“非 `viking://` URI”“空查询或空符号”“非文本文件”等业务失败作为 `status="ok"` 返回,错误说明位于以 `Error:` 开头的 `result` 字符串中。请求体缺少必填字段时返回 HTTP `400` 和 `INVALID_ARGUMENT`。
+
+## 当前客户端支持
+
+这些端点当前是 Server HTTP 能力,尚未进入 Python、TypeScript、Go 公共 SDK 或 `ov` CLI,因此本页只展示 HTTP Tab。
+
+## 相关文档
+
+- [资源](02-resources.md) - 导入源代码
+- [检索](06-retrieval.md) - 通用语义与模式检索
+- [内容](12-content.md) - 读取源文件内容
diff --git a/docs/zh/api/24-vikingbot.md b/docs/zh/api/24-vikingbot.md
new file mode 100644
index 000000000..bec925e09
--- /dev/null
+++ b/docs/zh/api/24-vikingbot.md
@@ -0,0 +1,161 @@
+# VikingBot API
+
+OpenViking Server 启用 `--with-bot` 后,会在 `/bot/v1` 下代理 VikingBot 的核心交互接口。未启用 Bot 时,这些端点返回 `503`。
+
+**代码入口**:
+
+- `openviking/server/routers/bot.py` - OpenViking Server 代理与身份转发
+- `bot/vikingbot/channels/openapi.py` - VikingBot Gateway 路由实现
+- `bot/vikingbot/channels/openapi_models.py` - 请求、响应和 SSE 事件模型
+
+## API 参考
+
+### health()
+
+检查 Bot Gateway 是否可用。
+
+**HTTP API**
+
+```bash
+curl http://localhost:1933/bot/v1/health
+```
+
+**响应示例**
+
+```json
+{
+ "status": "healthy",
+ "version": "0.1.0",
+ "timestamp": "2026-07-24T09:00:00"
+}
+```
+
+### chat()
+
+发送一条消息并等待完整回复。`session_id` 可省略;省略时 Gateway 会创建新会话。
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `message` | string | 是 | - | 非空的用户消息 |
+| `session_id` | string | 否 | 自动生成 | 继续已有会话时传入 |
+| `context` | array | 否 | `null` | 额外上下文消息,每项包含 `role` 和 `content` |
+| `need_reply` | boolean | 否 | `true` | 是否需要 Bot 回复 |
+| `disabled_tools` | string[] | 否 | `[]` | 本次请求禁用的工具名 |
+| `channel_id` | string | 否 | `null` | 多 Channel 路由标识 |
+
+**HTTP API**
+
+```bash
+curl -X POST http://localhost:1933/bot/v1/chat \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{"message":"总结我的项目进展","session_id":"optional-session-id"}'
+```
+
+**CLI**
+
+```bash
+ov chat -m "总结我的项目进展"
+```
+
+**响应示例**
+
+```json
+{
+ "session_id": "session-id",
+ "response_id": "response-id",
+ "message": "这是当前项目进展摘要……",
+ "events": null,
+ "relevant_memories": null,
+ "token_usage": {
+ "prompt_tokens": 120,
+ "completion_tokens": 42,
+ "total_tokens": 162
+ },
+ "timestamp": "2026-07-24T09:00:00"
+}
+```
+
+### chat_stream()
+
+以 Server-Sent Events 返回推理、工具调用、增量内容和最终响应事件。请求字段与 `chat()` 相同;Gateway 会自动启用流式模式。
+
+**HTTP API**
+
+```bash
+curl -N -X POST http://localhost:1933/bot/v1/chat/stream \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{"message":"分析当前知识库"}'
+```
+
+**CLI**
+
+```bash
+ov chat -m "分析当前知识库"
+```
+
+**SSE 响应示例**
+
+每条消息使用 `data: <json>` 格式,响应头 `X-VikingBot-Session-ID` 包含本次会话 ID。
+
+```text
+data: {"event":"reasoning_delta","data":"正在检查知识库…","timestamp":"2026-07-24T09:00:00"}
+
+data: {"event":"content_delta","data":"当前知识库包含","timestamp":"2026-07-24T09:00:01"}
+
+data: {"event":"response","data":{"content":"当前知识库包含……","response_id":"response-id"},"timestamp":"2026-07-24T09:00:02"}
+```
+
+`event` 可能为 `reasoning`、`reasoning_delta`、`tool_call`、`tool_result`、`content_delta`、`iteration` 或 `response`。
+
+### feedback()
+
+对已经生成的回复提交显式反馈。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `session_id` | string | 是 | 产生目标回复的会话 ID |
+| `response_id` | string | 是 | 目标助手回复 ID |
+| `feedback_type` | string | 是 | `thumb_up`、`thumb_down` 或 `rating` |
+| `feedback_score` | number | 条件必填 | `feedback_type=rating` 时必须提供 |
+| `feedback_reason` | string | 否 | 反馈原因标签 |
+| `feedback_text` | string | 否 | 自由文本反馈 |
+| `channel_id` | string | 否 | 多 Channel 路由标识 |
+
+**HTTP API**
+
+```bash
+curl -X POST http://localhost:1933/bot/v1/feedback \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "session_id":"session-id",
+ "response_id":"response-id",
+ "feedback_type":"thumb_up"
+ }'
+```
+
+**响应示例**
+
+```json
+{
+ "accepted": true,
+ "response_id": "response-id",
+ "session_id": "session-id",
+ "feedback_type": "thumb_up",
+ "feedback_delay_sec": 8.42,
+ "timestamp": "2026-07-24T09:00:08"
+}
+```
+
+目标回复不存在时返回 `404`;`rating` 缺少 `feedback_score` 时返回请求校验错误。
+
+## 客户端范围
+
+标准 OpenViking Python、TypeScript 和 Go SDK 当前不封装 Bot 代理接口;聊天入口由 `ov chat` CLI 和 HTTP 提供。VikingBot Gateway 自身还提供 Session 和 Channel API,详见 [VikingBot 文档](https://github.com/volcengine/OpenViking/blob/main/bot/README_CN.md#http-api)。
+
+## 相关文档
+
+- [VikingBot 概念](../concepts/15-vikingbot.md) - 架构和交互流程
+- [VikingBot 指标验证](../guides/12-vikingbot-metrics-validation.md) - Chat、Feedback 和指标链路
diff --git a/docs/zh/api/99-api-doc-writing-guide.md b/docs/zh/api/99-api-doc-writing-guide.md
index 0c4eef8ac..f94884a20 100644
--- a/docs/zh/api/99-api-doc-writing-guide.md
+++ b/docs/zh/api/99-api-doc-writing-guide.md
@@ -87,7 +87,9 @@ API 文档按模块组织,每个模块一个文件,使用两位数字序号
<JSON 响应示例>
```
-#### 4. 响应示例、错误和异常处理等(可选)
+#### 4. 响应契约(必填)与错误处理(可选)
+
+每个公开操作都必须说明成功返回值。JSON 接口至少给出一个与实现一致的响应包示例;文件下载、SSE、WebDAV 等非 JSON 接口必须说明 HTTP 状态、关键响应头、响应体或事件格式。不能只写“返回某些字段”而不展示结构。错误和异常处理示例可按需补充。
---
@@ -141,6 +143,13 @@ API 文档按模块组织,每个模块一个文件,使用两位数字序号
- CLI 示例
- 响应示例
+示例切换由加粗标签自动生成。调用方式标签必须单独成段,并使用以下固定基础写法:
+`**Python SDK**`、`**TypeScript SDK**`、`**Go SDK**`、`**HTTP API**`、`**CLI**`。
+需要区分调用形态时,可以在同一个加粗标签内追加半角括号限定词,例如
+`**Python SDK (Embedded / HTTP)**`;不要把限定词写在加粗标签外,也不要使用全角括号。
+只展示实现中真实存在的调用方式;某个 SDK 或 CLI 没有对应能力时应省略该 Tab,并简短说明
+可用的替代入口。不要把手写 HTTP 请求包装成不存在的 SDK 方法。
+
如果现有接口因工作流说明采用了特殊结构,应保持该局部结构稳定,并将 TypeScript 放在其他
SDK 示例附近。
@@ -253,5 +262,6 @@ openviking add-resource ./documents/guide.md --reason "User guide documentation"
- [ ] 实现介绍清晰,代码入口路径正确
- [ ] 参数表完整且准确
- [ ] 示例代码简洁且可运行
+- [ ] 调用示例使用固定加粗标签,并且每个 SDK/CLI Tab 都有真实实现
- [ ] HTTP 方法和路径正确
-- [ ] 响应示例与实际返回一致
+- [ ] 每个公开操作都有成功响应契约,且示例与实际返回一致