Skip to content

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

docs: repair section links and validate rendered anchors (#5189)

Zayn Jarvis45fe61f17c7c
diff --git a/.github/workflows/_docs.yml b/.github/workflows/_docs.yml
index 259232618..1fbabb2bc 100644
--- a/.github/workflows/_docs.yml
+++ b/.github/workflows/_docs.yml
@@ -37,3 +37,9 @@ jobs:
working-directory: docs
env:
DOCS_BASE: /
+
+ - name: Check built section links
+ run: python3 scripts/check-built-anchors.py
+ working-directory: docs
+ env:
+ DOCS_BASE: /
diff --git a/docs/en/agent-integrations/02-claude-code.md b/docs/en/agent-integrations/02-claude-code.md
index 032e3872b..1fbddf8e2 100644
--- a/docs/en/agent-integrations/02-claude-code.md
+++ b/docs/en/agent-integrations/02-claude-code.md
@@ -72,7 +72,7 @@ The plugin hooks into the Claude Code lifecycle:
All write operations run asynchronously, ensuring they never block your conversation.
-Tool calls and results are captured as dedicated `tool` parts, and `tool_output` is reported verbatim. Truncation is the server's job: output larger than `tool_output_externalization.threshold_chars` (default `20000`) is written to the session's tool-result store, and the part keeps a synopsis stub plus `tool_output_ref`, so the original stays readable through [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read_tool_result).
+Tool calls and results are captured as dedicated `tool` parts, and `tool_output` is reported verbatim. Truncation is the server's job: output larger than `tool_output_externalization.threshold_chars` (default `20000`) is written to the session's tool-result store, and the part keeps a synopsis stub plus `tool_output_ref`, so the original stays readable through [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read-tool-result).
<details>
<summary><b>Configuration</b></summary>
diff --git a/docs/en/agent-integrations/04-codex.md b/docs/en/agent-integrations/04-codex.md
index 9e958ec17..073fc240f 100644
--- a/docs/en/agent-integrations/04-codex.md
+++ b/docs/en/agent-integrations/04-codex.md
@@ -61,7 +61,7 @@ The plugin integrates with Codex's lifecycle by hooking into key events. On `Ses
> **Known limitation**: `SessionEnd` requires Codex 0.145 or newer, and it only fires on a graceful exit (`/quit`, `/exit`, double `Ctrl-C`, EOF, end of a `codex exec` run). It does not fire on `SIGTERM`, a closed terminal, `kill -9`, or a crash, and it is deferred when the TUI runs against a `codex app-server` daemon. Those sessions — and every session on Codex older than 0.145, and any TraeCode CLI build without it — are recovered by the idle-TTL sweep (30 minutes) at the next `SessionStart`.
-Tool calls and results are captured as dedicated `tool` parts, and `tool_output` is reported verbatim. Truncation is the server's job: output larger than `tool_output_externalization.threshold_chars` (default `20000`) is written to the session's tool-result store, and the part keeps a synopsis stub plus `tool_output_ref`, so the original stays readable through [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read_tool_result).
+Tool calls and results are captured as dedicated `tool` parts, and `tool_output` is reported verbatim. Truncation is the server's job: output larger than `tool_output_externalization.threshold_chars` (default `20000`) is written to the session's tool-result store, and the part keeps a synopsis stub plus `tool_output_ref`, so the original stays readable through [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read-tool-result).
<details>
<summary><b>Configuration</b></summary>
diff --git a/docs/en/agent-integrations/10-opencode.md b/docs/en/agent-integrations/10-opencode.md
index 91aee2d9f..be1e0a14d 100644
--- a/docs/en/agent-integrations/10-opencode.md
+++ b/docs/en/agent-integrations/10-opencode.md
@@ -4,7 +4,7 @@ Give [OpenCode](https://opencode.ai/) cross-project and cross-session long-term
Source: [examples/opencode-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode-plugin)
-Tool calls and results are captured as dedicated `tool` parts, and `tool_output` is reported verbatim. Truncation is the server's job: output larger than `tool_output_externalization.threshold_chars` (default `20000`) is written to the session's tool-result store, and the part keeps a synopsis stub plus `tool_output_ref`, so the original stays readable through [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read_tool_result).
+Tool calls and results are captured as dedicated `tool` parts, and `tool_output` is reported verbatim. Truncation is the server's job: output larger than `tool_output_externalization.threshold_chars` (default `20000`) is written to the session's tool-result store, and the part keeps a synopsis stub plus `tool_output_ref`, so the original stays readable through [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read-tool-result).
## Prerequisites
diff --git a/docs/en/agent-integrations/11-pi.md b/docs/en/agent-integrations/11-pi.md
index 032a335dd..27816290b 100644
--- a/docs/en/agent-integrations/11-pi.md
+++ b/docs/en/agent-integrations/11-pi.md
@@ -14,7 +14,7 @@ Source: [examples/pi-coding-agent-extension](https://github.com/volcengine/OpenV
- A footer status segment (`OV ✓ …`) shows connection and capture state; the `/viking` command prints status, and `/viking commit` forces a commit.
- Accidental `read`/`grep`/`find`/`ls` calls whose path is a `viking://` URI are blocked with a hint pointing to the matching `viking_*` tool. A `bash` command that carries a `viking://` URI still runs, and its result ends with a notice suggesting `viking_read` / `viking_search`.
-Tool calls and results are captured as dedicated `tool` parts, and `tool_output` is reported verbatim. Truncation is the server's job: output larger than `tool_output_externalization.threshold_chars` (default `20000`) is written to the session's tool-result store, and the part keeps a synopsis stub plus `tool_output_ref`, so the original stays readable through [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read_tool_result).
+Tool calls and results are captured as dedicated `tool` parts, and `tool_output` is reported verbatim. Truncation is the server's job: output larger than `tool_output_externalization.threshold_chars` (default `20000`) is written to the session's tool-result store, and the part keeps a synopsis stub plus `tool_output_ref`, so the original stays readable through [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read-tool-result).
## Prerequisites
diff --git a/docs/en/api/01-overview.md b/docs/en/api/01-overview.md
index 1003e123e..1ed598c17 100644
--- a/docs/en/api/01-overview.md
+++ b/docs/en/api/01-overview.md
@@ -118,7 +118,7 @@ Configuration field description:
| `timeout` | HTTP request timeout in seconds | `600.0` |
| `output` | Default output format: `"table"` or `"json"` | `"table"` |
-See the [Configuration Guide](../guides/01-configuration.md#ovcliconf) for details.
+See the [Configuration Guide](../guides/01-configuration.md#ovcli-conf) for details.
#### Using Python SDK Client Without Configuration File
diff --git a/docs/en/api/02-resources.md b/docs/en/api/02-resources.md
index 459bd899a..9b6434062 100644
--- a/docs/en/api/02-resources.md
+++ b/docs/en/api/02-resources.md
@@ -199,7 +199,7 @@ This endpoint is the core entry point for resource management. It supports vario
- Resource targets may use public `viking://resources/...`, the home alias `viking://~/resources/...`, explicit user `viking://user/{user_id}/resources/...`, or peer `viking://user/{user_id}/peers/{peer_id}/resources/...` paths. The home alias is expanded to the canonical path using the authenticated request identity; the uid-less spelling `viking://user/resources/...` is rejected with an error pointing at `viking://~/resources/...`.
- `user_id` and `peer_id` path segments must be safe single-segment identifiers, for example `alice` or `web-visitor-alice`. Values with path separators, `.`, `..`, `:`, or `+` are rejected.
- `path` and `temp_file_id` cannot be specified together
-- Raw HTTP calls for local files require first uploading via [temp_upload](#temp_upload) to obtain `temp_file_id`
+- Raw HTTP calls for local files require first uploading via [temp_upload](#temp-upload) to obtain `temp_file_id`
- Only Git repository sources use full background import when `wait=false`; OpenViking performs repository preflight and target planning before returning the `task_id`.
- Native HTTPS Git credentials in `args.auth_config` remain request-local when `watch_interval <= 0`. When `watch_interval > 0`, OpenViking stores the repository-bound username/token in private watch state and restores it only for later Git fetches. The credentials are excluded from ordinary queue payloads and watch API/MCP/CLI responses. Git PATs have no generic refresh flow; rotate an expired or revoked token by recreating the watch. Legacy URL-embedded credentials such as `https://user:token@host/repo.git` remain accepted and are passed through unchanged; because that URL is also the source identifier, it may be recorded in process arguments, logs, queues, resource metadata, and watch state. Prefer `args.auth_config` for new integrations. Plaintext HTTP authentication and authenticated redirects for `args.auth_config` remain rejected.
- The token travels in the HTTPS request body. Keep diagnostic request-body dumping disabled in production because explicitly enabling it can record secrets.
@@ -607,7 +607,7 @@ For Git repository sources with `wait=false`, the background task has `task_type
### temp_upload
-Upload a temporary file for subsequent importing of local files via [add_resource](#add_resource) or [add_skill](#add_skill).
+Upload a temporary file for subsequent importing of local files via [add_resource](#add-resource) or [add_skill](04-skills.md#add-skill).
#### 1. API Implementation Overview
diff --git a/docs/en/api/14-ovpack.md b/docs/en/api/14-ovpack.md
index a7193737e..35c3bbda9 100644
--- a/docs/en/api/14-ovpack.md
+++ b/docs/en/api/14-ovpack.md
@@ -146,7 +146,7 @@ Imports a `.ovpack` file to a specified location for restoring or migrating data
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
-| temp_file_id | string | Yes | - | Temporary upload file ID (obtained via [temp_upload](02-resources.md#temp_upload)) |
+| 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` |
@@ -438,4 +438,4 @@ ov restore ./backups/openviking.ovpack --on-conflict overwrite --vector-mode req
- [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
+- [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
index 1c87845cd..d9349bd5a 100644
--- a/docs/en/api/15-watches.md
+++ b/docs/en/api/15-watches.md
@@ -6,7 +6,7 @@ The Watch API manages periodic resource checks, pausing, resuming, and manual tr
### Watch Management
-List, inspect, update, and trigger watch tasks created via [`add_resource`](02-resources.md#add_resource) with `watch_interval > 0`. The control plane is mirrored across REST (`/api/v1/watches`), the `ov task watch` CLI subcommand group, and a minimum-closure MCP surface (`list_watches` / `cancel_watch`) for agents.
+List, inspect, update, and trigger watch tasks created via [`add_resource`](02-resources.md#add-resource) with `watch_interval > 0`. 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
@@ -211,7 +211,7 @@ list_watches() # one line per task; U
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.
+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.
---
diff --git a/docs/en/api/16-memory.md b/docs/en/api/16-memory.md
index 36552a48d..50802f092 100644
--- a/docs/en/api/16-memory.md
+++ b/docs/en/api/16-memory.md
@@ -26,7 +26,7 @@ These are the enabled built-in types. Deployments can extend or override them wi
### recall()
-> **Deprecated**: `/api/v1/search/recall` is now a thin preset over [`/api/v1/search/search` with `mode="context"`](06-retrieval.md#searchmodecontext) and carries no assembly logic of its own. New integrations should target the context face directly; the v1 field aliases are accepted only here and will be removed in the next minor release. Responses carry a `Deprecation: true` header.
+> **Deprecated**: `/api/v1/search/recall` is now a thin preset over [`/api/v1/search/search` with `mode="context"`](06-retrieval.md#search-mode-context) and carries no assembly logic of its own. New integrations should target the context face directly; the v1 field aliases are accepted only here and will be removed in the next minor release. Responses carry a `Deprecation: true` header.
Search each memory type independently and assemble a bounded memory block that can be injected directly into Agent context. Relative to the context face, `/recall` overlays `purpose="coding"`, the v1-compatible `score_threshold=0.1`, `dedup_turns=5` when a `session_id` is present, and `query_expansion="auto"`. Coding Agent plugins explicitly send `score_threshold=0.35`; the public `/recall` default remains `0.1` so an unchanged request does not silently lose results after upgrading. Omitting `quotas` keeps v1's bucket defaults (`events=10, entities=10, preferences=3, experiences=0`); sending `"quotas": null` explicitly opts into the `purpose` preset ratios instead.
@@ -114,7 +114,7 @@ The response shape matches the context face (flat entries, flat XML in `rendered
}
```
-See [Retrieval - search(mode="context")](06-retrieval.md#searchmodecontext) for field meanings. Shape changes relative to v1: `type` → `category`, `mode` → `detail`, `content`/`summary` → `text`, `rendered` moves from three-level nesting to flat `<memory>` tags, and `rank` is no longer returned.
+See [Retrieval - search(mode="context")](06-retrieval.md#search-mode-context) for field meanings. Shape changes relative to v1: `type` → `category`, `mode` → `detail`, `content`/`summary` → `text`, `rendered` moves from three-level nesting to flat `<memory>` tags, and `rank` is no longer returned.
The public Python, TypeScript, Go SDKs and the `ov` CLI do not wrap this endpoint yet, so this section shows only the HTTP tab plus the MCP call that does exist.
diff --git a/docs/en/concepts/07-retrieval.md b/docs/en/concepts/07-retrieval.md
index b7546522c..110432c39 100644
--- a/docs/en/concepts/07-retrieval.md
+++ b/docs/en/concepts/07-retrieval.md
@@ -39,7 +39,7 @@ results = await client.search(
## Intent Analysis
-IntentAnalyzer uses LLM to analyze query intent and generate 0-5 TypedQueries. The model used for this stage is separately configurable via the [`query_planner`](../guides/01-configuration.md#query_planner) config, falling back to `vlm` when unset.
+IntentAnalyzer uses LLM to analyze query intent and generate 0-5 TypedQueries. The model used for this stage is separately configurable via the [`query_planner`](../guides/01-configuration.md#query-planner) config, falling back to `vlm` when unset.
### Input
diff --git a/docs/en/getting-started/02-quickstart.md b/docs/en/getting-started/02-quickstart.md
index 0b3d0e451..cc6d9cbb1 100644
--- a/docs/en/getting-started/02-quickstart.md
+++ b/docs/en/getting-started/02-quickstart.md
@@ -73,7 +73,7 @@ If you prefer to run OpenViking as a standalone service, Docker is recommended.
By default, the container starts the OpenViking API server on `1933` (which also serves the Web Studio UI at `/studio`) and the bundled `vikingbot` gateway. If you need to disable `vikingbot`, add either `command: ["--without-bot"]` or `environment: ["OPENVIKING_WITH_BOT=0"]`.
- On platforms that don't allow bind mounts, set `OPENVIKING_CONF_CONTENT` to the full config JSON to bootstrap on first start, or `docker exec` in and run `openviking-server init` after the container is up. See [Deployment Guide](../guides/03-deployment.md#when-docker--v-is-not-available) for details.
+ On platforms that don't allow bind mounts, set `OPENVIKING_CONF_CONTENT` to the full config JSON to bootstrap on first start, or `docker exec` in and run `openviking-server init` after the container is up. See [Deployment Guide](../guides/03-deployment.md#when-docker-v-is-not-available) for details.
The container entrypoint binds to `0.0.0.0` inside the container. The [port mapping](https://docs.docker.com/engine/network/port-publishing/) above makes it accessible at `http://localhost:1933` on the host, including macOS. For access from other machines, see [Authentication](../guides/04-authentication.md) and [Public Access](../guides/12-public-access.md).
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index c78ea01f0..0e0f5d3c6 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -1329,7 +1329,7 @@ Notes:
###### Per-session Auto Commit Policy
-When a session carries an `auto_commit_policy`, any field you omit falls back to the recommended default below. Sessions without a stored policy keep auto commit disabled. Values are clamped into `[0, max]`, and unknown keys are rejected with `InvalidArgumentError`. See [Sessions API](../api/05-sessions.md#create_session) for how to set and view it.
+When a session carries an `auto_commit_policy`, any field you omit falls back to the recommended default below. Sessions without a stored policy keep auto commit disabled. Values are clamped into `[0, max]`, and unknown keys are rejected with `InvalidArgumentError`. See [Sessions API](../api/05-sessions.md#create-session) for how to set and view it.
| Field | Type | Default | Max | Description |
|-------|------|---------|-----|-------------|
diff --git a/docs/scripts/check-built-anchors.py b/docs/scripts/check-built-anchors.py
new file mode 100644
index 000000000..23a172635
--- /dev/null
+++ b/docs/scripts/check-built-anchors.py
@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Check local section links against IDs in built VitePress HTML, not guessed slugs.
+
+Run after docs:build. DOCS_BASE must match the build's base path.
+External URLs, text fragments, and non-HTML assets are outside this check.
+"""
+
+import argparse
+import os
+import posixpath
+from html.parser import HTMLParser
+from pathlib import Path
+from urllib.parse import unquote, urlsplit
+
+
+class Page(HTMLParser):
+ def __init__(self, source):
+ super().__init__(convert_charrefs=True)
+ self.ids = set()
+ self.links = []
+ self.feed(source)
+ self.close()
+
+ def handle_starttag(self, tag, attributes):
+ attributes = dict(attributes)
+ if attributes.get("id") is not None:
+ self.ids.add(attributes["id"])
+ if tag == "a" and attributes.get("href") is not None:
+ self.links.append(attributes["href"])
+
+ handle_startendtag = handle_starttag
+
+
+def check(dist, base):
+ pages = {
+ file.relative_to(dist).as_posix(): Page(file.read_text(encoding="utf-8"))
+ for file in sorted(dist.rglob("*.html"))
+ }
+ if not pages:
+ print(f"No built HTML found in {dist}. Run npm run docs:build first.")
+ return 1
+ base = "/" + base.strip("/") + "/" if base.strip("/") else "/"
+ checked = 0
+ errors = []
+ for filename, page in pages.items():
+ for href in page.links:
+ url = urlsplit(href)
+ if url.scheme or url.netloc or not url.fragment:
+ continue
+ # Browser text fragments do not refer to element IDs. A preceding
+ # element fragment still needs to exist (e.g. #heading:~:text=...).
+ fragment = unquote(url.fragment.split(":~:text=", 1)[0])
+ if not fragment:
+ continue
+ target = unquote(url.path)
+ if target.startswith("/"):
+ if not target.startswith(base):
+ # Root-relative links outside a mounted site's base are
+ # other applications, not part of this generated site.
+ continue
+ target = target[len(base):]
+ elif target:
+ target = posixpath.join(posixpath.dirname(filename), target)
+ else:
+ target = filename
+ target = posixpath.normpath(target)
+ if Path(target).suffix not in ("", ".html"):
+ continue
+ candidates = [target, target + ".html", posixpath.normpath(posixpath.join(target, "index.html"))]
+ resolved = next((candidate for candidate in candidates if candidate in pages), None)
+ checked += 1
+ if resolved is None:
+ errors.append(f"{filename}: {href} (target HTML not found)")
+ elif fragment not in pages[resolved].ids:
+ errors.append(f"{filename}: {href} (ID {fragment!r} missing in {resolved})")
+ print(f"Checked {checked} local section links across {len(pages)} built HTML pages.")
+ if errors:
+ print("\n".join(errors))
+ print(f"Found {len(errors)} broken section links.")
+ return 1
+ print("Built section-link checks passed.")
+ return 0
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--dist", type=Path, default=Path(__file__).resolve().parents[1] / ".vitepress/dist")
+ parser.add_argument("--base", default=os.environ.get("DOCS_BASE", "/"))
+ args = parser.parse_args()
+ return check(args.dist, args.base)
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/docs/zh/agent-integrations/02-claude-code.md b/docs/zh/agent-integrations/02-claude-code.md
index 4d1df2322..b75436c8f 100644
--- a/docs/zh/agent-integrations/02-claude-code.md
+++ b/docs/zh/agent-integrations/02-claude-code.md
@@ -72,7 +72,7 @@ bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shar
所有数据写入操作均为异步执行,不会阻塞当前的对话进程。
-工具调用和结果会作为独立的 `tool` part 捕获,`tool_output` 原样上报。截断由服务端负责:超过 `tool_output_externalization.threshold_chars`(默认 `20000`)的输出会写入 session 的 tool-result 存储,part 中只保留 synopsis stub 和 `tool_output_ref`,原文仍可通过 [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read_tool_result) 读回。
+工具调用和结果会作为独立的 `tool` part 捕获,`tool_output` 原样上报。截断由服务端负责:超过 `tool_output_externalization.threshold_chars`(默认 `20000`)的输出会写入 session 的 tool-result 存储,part 中只保留 synopsis stub 和 `tool_output_ref`,原文仍可通过 [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read-tool-result) 读回。
<details>
<summary><b>配置</b></summary>
diff --git a/docs/zh/agent-integrations/04-codex.md b/docs/zh/agent-integrations/04-codex.md
index e67abd8dc..e07077e28 100644
--- a/docs/zh/agent-integrations/04-codex.md
+++ b/docs/zh/agent-integrations/04-codex.md
@@ -60,7 +60,7 @@ TraeCode CLI 2.0 用户启动 `trae-cli`,并可用 `trae-cli plugin list` 确
> **已知局限**:`SessionEnd` 需要 Codex 0.145 及以上版本,且只在正常退出时触发(`/quit`、`/exit`、连按两次 `Ctrl-C`、EOF、`codex exec` 运行结束)。`SIGTERM`、直接关闭终端、`kill -9` 或崩溃都不会触发;当 TUI 挂在 `codex app-server` 守护进程上时,该事件会被延后。这些会话——以及 Codex 低于 0.145 的所有会话(以及没有该事件的 TraeCode CLI 版本)——由下一次 `SessionStart` 的闲置 TTL(生存时间,默认为 30 分钟)清扫回收。
-工具调用和结果会作为独立的 `tool` part 捕获,`tool_output` 原样上报。截断由服务端负责:超过 `tool_output_externalization.threshold_chars`(默认 `20000`)的输出会写入 session 的 tool-result 存储,part 中只保留 synopsis stub 和 `tool_output_ref`,原文仍可通过 [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read_tool_result) 读回。
+工具调用和结果会作为独立的 `tool` part 捕获,`tool_output` 原样上报。截断由服务端负责:超过 `tool_output_externalization.threshold_chars`(默认 `20000`)的输出会写入 session 的 tool-result 存储,part 中只保留 synopsis stub 和 `tool_output_ref`,原文仍可通过 [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read-tool-result) 读回。
<details>
<summary><b>配置</b></summary>
diff --git a/docs/zh/agent-integrations/10-opencode.md b/docs/zh/agent-integrations/10-opencode.md
index 50684388f..6ca8f59bd 100644
--- a/docs/zh/agent-integrations/10-opencode.md
+++ b/docs/zh/agent-integrations/10-opencode.md
@@ -4,7 +4,7 @@
源码:[examples/opencode-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode-plugin)
-工具调用和结果会作为独立的 `tool` part 捕获,`tool_output` 原样上报。截断由服务端负责:超过 `tool_output_externalization.threshold_chars`(默认 `20000`)的输出会写入 session 的 tool-result 存储,part 中只保留 synopsis stub 和 `tool_output_ref`,原文仍可通过 [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read_tool_result) 读回。
+工具调用和结果会作为独立的 `tool` part 捕获,`tool_output` 原样上报。截断由服务端负责:超过 `tool_output_externalization.threshold_chars`(默认 `20000`)的输出会写入 session 的 tool-result 存储,part 中只保留 synopsis stub 和 `tool_output_ref`,原文仍可通过 [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read-tool-result) 读回。
## 前置条件
diff --git a/docs/zh/agent-integrations/11-pi.md b/docs/zh/agent-integrations/11-pi.md
index 997ce310c..7eca571f3 100644
--- a/docs/zh/agent-integrations/11-pi.md
+++ b/docs/zh/agent-integrations/11-pi.md
@@ -14,7 +14,7 @@
- 底部状态栏显示 `OV ✓ …` 连接与捕获状态;`/viking` 命令查看状态,`/viking commit` 强制 commit。
- 模型用本地 `read`/`grep`/`find`/`ls` 访问 `viking://` URI 路径时,调用会被拦截,并提示改用对应的 `viking_*` 工具;`bash` 命令带 `viking://` URI 时照常执行,结果末尾附一条提示,建议改用 `viking_read` / `viking_search`。
-工具调用和结果会作为独立的 `tool` part 捕获,`tool_output` 原样上报。截断由服务端负责:超过 `tool_output_externalization.threshold_chars`(默认 `20000`)的输出会写入 session 的 tool-result 存储,part 中只保留 synopsis stub 和 `tool_output_ref`,原文仍可通过 [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read_tool_result) 读回。
+工具调用和结果会作为独立的 `tool` part 捕获,`tool_output` 原样上报。截断由服务端负责:超过 `tool_output_externalization.threshold_chars`(默认 `20000`)的输出会写入 session 的 tool-result 存储,part 中只保留 synopsis stub 和 `tool_output_ref`,原文仍可通过 [`/api/v1/sessions/{id}/tool-results`](../api/05-sessions.md#read-tool-result) 读回。
## 前置条件
diff --git a/docs/zh/api/01-overview.md b/docs/zh/api/01-overview.md
index 98df1aa4f..cc9f02c54 100644
--- a/docs/zh/api/01-overview.md
+++ b/docs/zh/api/01-overview.md
@@ -113,7 +113,7 @@ export OPENVIKING_CLI_CONFIG_FILE=/path/to/ovcli.conf
| `timeout` | HTTP 请求超时时间(秒) | `600.0` |
| `output` | 默认输出格式:`"table"` 或 `"json"` | `"table"` |
-详细内容请参见 [配置指南](../guides/01-configuration.md#ovcliconf)。
+详细内容请参见 [配置指南](../guides/01-configuration.md#ovcli-conf)。
#### 完全不依赖配置文件使用 Python SDK 客户端
diff --git a/docs/zh/api/02-resources.md b/docs/zh/api/02-resources.md
index 351f28224..5c48c4809 100644
--- a/docs/zh/api/02-resources.md
+++ b/docs/zh/api/02-resources.md
@@ -193,7 +193,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
- 如果同时省略 `to` 和 `parent`,服务端会先尝试使用当前用户的 `add_targets.resource_uri` 覆盖配置,再使用 `server.user_config_defaults.add_targets.resource_uri`。两者都没有配置时,保持旧的目标解析行为。
- 资源目标可以使用公共 `viking://resources/...`、家目录别名 `viking://~/resources/...`、显式用户 `viking://user/{user_id}/resources/...`,或 peer 级 `viking://user/{user_id}/peers/{peer_id}/resources/...`。家目录别名会按请求身份展开为 canonical 路径;无 uid 的写法 `viking://user/resources/...` 会被拒绝,并提示改用 `viking://~/resources/...`。
- `user_id` 和 `peer_id` 路径片段必须是安全的单段标识,例如 `alice` 或 `web-visitor-alice`。包含路径分隔符、`.`、`..`、`:` 或 `+` 的值会被拒绝。
-- `path` 和 `temp_file_id` 不能同时指定,上传本地文件需要先通过 [temp_upload](#temp_upload) 上传获取 `temp_file_id`,在 SDK 和 CLI 中已经封装好。
+- `path` 和 `temp_file_id` 不能同时指定,上传本地文件需要先通过 [temp_upload](#temp-upload) 上传获取 `temp_file_id`,在 SDK 和 CLI 中已经封装好。
- `tags` 会在资源解析后、向量记录写入时同步写入底层向量库。`add_resource(tags=...)` 不返回 `tags_result`;需要验证时,可在 `/api/v1/search/find` 或 `/api/v1/search/search` 中传相同 `tags` 过滤召回。
- 只有 Git 仓库来源在 `wait=false` 时使用完整后台导入;OpenViking 会先完成仓库 preflight 和目标规划,再返回 `task_id`。
- 原生 HTTPS Git 的 `args.auth_config` 在 `watch_interval <= 0` 时只用于本次请求;当 `watch_interval > 0` 时,OpenViking 会把与仓库 URL 绑定的 username/token 保存到 Watch 私有鉴权状态,并只在后续 Git 拉取时恢复使用。凭据不会进入普通持久队列,也不会出现在 Watch API/MCP/CLI 返回中。Git PAT 没有通用刷新流程,过期或撤销后需要重建 Watch 来更换 token。为兼容已有用法,系统仍接受 `https://user:token@host/repo.git` 形式的 URL 内嵌凭据并原样传递;由于该 URL 同时也是资源来源标识,它可能被记录到进程参数、日志、队列、资源元数据和 Watch 状态中。新接入建议使用 `args.auth_config`。`args.auth_config` 的明文 HTTP 鉴权和带鉴权重定向仍会被拒绝。
@@ -615,7 +615,7 @@ task_id uuid-xxx
### temp_upload
-上传临时文件,用于后续通过 [add_resource](#add_resource) 或 [add_skill](#add_skill) 导入本地文件。
+上传临时文件,用于后续通过 [add_resource](#add-resource) 或 [add_skill](04-skills.md#add-skill) 导入本地文件。
#### 1. API 实现介绍
diff --git a/docs/zh/api/14-ovpack.md b/docs/zh/api/14-ovpack.md
index 80f53ba54..24de082fe 100644
--- a/docs/zh/api/14-ovpack.md
+++ b/docs/zh/api/14-ovpack.md
@@ -146,7 +146,7 @@ ov export viking://resources/my-project/ ./exports/my-project.ovpack --include-v
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
-| temp_file_id | string | 是 | - | 临时上传文件 ID(通过 [temp_upload](02-resources.md#temp_upload) 获取) |
+| 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` |
@@ -429,4 +429,4 @@ ov restore ./backups/openviking.ovpack --on-conflict overwrite --vector-mode req
- [OVPack 指南](../guides/09-ovpack.md) - 格式、迁移和操作流程
- [快照](11-snapshot.md) - 工作区版本管理
-- [临时上传](02-resources.md#temp_upload) - 上传待导入的包
+- [临时上传](02-resources.md#temp-upload) - 上传待导入的包
diff --git a/docs/zh/api/15-watches.md b/docs/zh/api/15-watches.md
index 3f0abd695..627591a67 100644
--- a/docs/zh/api/15-watches.md
+++ b/docs/zh/api/15-watches.md
@@ -6,7 +6,7 @@ Watch API 管理资源的周期检查、暂停、恢复和手动触发。
### Watch Management(监控任务管理)
-列出、查看、更新和触发通过 [`add_resource`](02-resources.md#add_resource) 配合 `watch_interval > 0` 创建的监控任务。控制面在 REST(`/api/v1/watches`)、`ov task watch` CLI 子命令组以及面向 Agent 的最小闭包 MCP 接口(`list_watches` / `cancel_watch`)三处镜像。
+列出、查看、更新和触发通过 [`add_resource`](02-resources.md#add-resource) 配合 `watch_interval > 0` 创建的监控任务。控制面在 REST(`/api/v1/watches`)、`ov task watch` CLI 子命令组以及面向 Agent 的最小闭包 MCP 接口(`list_watches` / `cancel_watch`)三处镜像。
#### 1. API 实现介绍
@@ -209,7 +209,7 @@ list_watches() # 每个任务一行
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`。
+暂停 / 恢复 / 触发 / 更新故意不通过 MCP 暴露——这些 power-user 操作放在 CLI/REST 一侧,以保持 Agent 系统提示词的紧凑。Agent 侧若需创建监控任务或调整周期,仍走 [`add_resource`](02-resources.md#add-resource) 配合 `watch_interval`;可显式传 `to`,也可让系统绑定本次导入返回的 `root_uri`。
---
diff --git a/docs/zh/api/16-memory.md b/docs/zh/api/16-memory.md
index 57863bee7..d8825521e 100644
--- a/docs/zh/api/16-memory.md
+++ b/docs/zh/api/16-memory.md
@@ -26,7 +26,7 @@
### recall()
-> **已弃用**:`/api/v1/search/recall` 现在只是 [`/api/v1/search/search` 的 `mode="context"`](06-retrieval.md#searchmodecontext) 之上的轻量预设,自身不再包含独立的组装逻辑。新接入请直接使用 context 面;v1 字段别名仅在本端点保留,将在下一个 minor 版本移除。响应会带上 `Deprecation: true` 头。
+> **已弃用**:`/api/v1/search/recall` 现在只是 [`/api/v1/search/search` 的 `mode="context"`](06-retrieval.md#search-mode-context) 之上的轻量预设,自身不再包含独立的组装逻辑。新接入请直接使用 context 面;v1 字段别名仅在本端点保留,将在下一个 minor 版本移除。响应会带上 `Deprecation: true` 头。
按记忆类型分别检索,并在预算内组合成可直接注入 Agent 上下文的记忆块。相对 context 面,`/recall` 会叠加 `purpose="coding"`、兼容 v1 的 `score_threshold=0.1`、带 `session_id` 时 `dedup_turns=5`、`query_expansion="auto"`。Coding Agent 插件会显式发送 `score_threshold=0.35`;公共 `/recall` 默认值仍为 `0.1`,避免相同请求在升级后静默减少结果。省略 `quotas` 时沿用 v1 的分桶默认值(`events=10, entities=10, preferences=3, experiences=0`);显式传 `"quotas": null` 才改用 `purpose` 预设配比。
@@ -114,7 +114,7 @@ recall(
}
```
-字段含义见 [检索 - search(mode="context")](06-retrieval.md#searchmodecontext)。相对 v1 的形状变化:`type` → `category`、`mode` → `detail`、`content`/`summary` → `text`,`rendered` 由三层嵌套改为扁平 `<memory>` 标签,`rank` 不再返回。
+字段含义见 [检索 - search(mode="context")](06-retrieval.md#search-mode-context)。相对 v1 的形状变化:`type` → `category`、`mode` → `detail`、`content`/`summary` → `text`,`rendered` 由三层嵌套改为扁平 `<memory>` 标签,`rank` 不再返回。
公共 Python、TypeScript、Go SDK 和 `ov` CLI 当前尚未封装该端点,因此本节只展示 HTTP Tab,并补充实际存在的 MCP 调用。
diff --git a/docs/zh/concepts/07-retrieval.md b/docs/zh/concepts/07-retrieval.md
index f163cc203..5acbf594b 100644
--- a/docs/zh/concepts/07-retrieval.md
+++ b/docs/zh/concepts/07-retrieval.md
@@ -39,7 +39,7 @@ results = await client.search(
## 意图分析
-IntentAnalyzer 使用 LLM 分析查询意图,生成 0-5 个 TypedQuery。该阶段使用的模型可通过 [`query_planner`](../guides/01-configuration.md#query_planner) 配置项单独指定,未设置时回退到 `vlm`。
+IntentAnalyzer 使用 LLM 分析查询意图,生成 0-5 个 TypedQuery。该阶段使用的模型可通过 [`query_planner`](../guides/01-configuration.md#query-planner) 配置项单独指定,未设置时回退到 `vlm`。
### 输入
diff --git a/docs/zh/getting-started/02-quickstart.md b/docs/zh/getting-started/02-quickstart.md
index 3b6cf3ccb..38e9b626d 100644
--- a/docs/zh/getting-started/02-quickstart.md
+++ b/docs/zh/getting-started/02-quickstart.md
@@ -73,7 +73,7 @@ pipx upgrade openviking
默认情况下,容器会启动 OpenViking API 服务(`1933`,同时在 `/studio` 提供 Web Studio 前端)以及内置的 `vikingbot` gateway。如果你需要关闭 `vikingbot`,可以在 Compose 里增加 `command: ["--without-bot"]`,或者设置 `environment: ["OPENVIKING_WITH_BOT=0"]`。
- 如果运行平台不支持 bind mount,可以通过 `OPENVIKING_CONF_CONTENT` 环境变量传入完整的配置 JSON,或在容器启动后 `docker exec` 进去执行 `openviking-server init`。详见 [部署指南](../guides/03-deployment.md#无法使用-docker--v-时)。
+ 如果运行平台不支持 bind mount,可以通过 `OPENVIKING_CONF_CONTENT` 环境变量传入完整的配置 JSON,或在容器启动后 `docker exec` 进去执行 `openviking-server init`。详见 [部署指南](../guides/03-deployment.md#无法使用-docker-v-时)。
容器入口脚本在容器内监听 `0.0.0.0`。上述端口映射使宿主机(包括 macOS)可通过 `http://localhost:1933` 访问服务。如需允许其他机器访问,请参见 [身份认证](../guides/04-authentication.md) 和 [公网访问](../guides/12-public-access.md)。
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index f68e2d09f..03d1836d0 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -1304,7 +1304,7 @@ RAGFS 默认使用 Rust binding 模式,通过 Rust 实现直接访问文件系
###### 单 session 自动 commit 策略
-当 session 带有 `auto_commit_policy` 时,未传的字段会回退到下方推荐默认值。没有存储 policy 的 session 保持 auto commit 关闭。取值会被 clamp 到 `[0, 上限]`,未知字段会以 `InvalidArgumentError` 拒绝。设置和查看方式见 [Sessions API](../api/05-sessions.md#create_session)。
+当 session 带有 `auto_commit_policy` 时,未传的字段会回退到下方推荐默认值。没有存储 policy 的 session 保持 auto commit 关闭。取值会被 clamp 到 `[0, 上限]`,未知字段会以 `InvalidArgumentError` 拒绝。设置和查看方式见 [Sessions API](../api/05-sessions.md#create-session)。
| 字段 | 类型 | 默认值 | 上限 | 说明 |
|------|------|--------|------|------|
diff --git a/docs/zh/guides/08-encryption.md b/docs/zh/guides/08-encryption.md
index f204cecc5..c3ed9dfb0 100644
--- a/docs/zh/guides/08-encryption.md
+++ b/docs/zh/guides/08-encryption.md
@@ -417,7 +417,7 @@ ov restore ./backups/before-encryption.ovpack --on-conflict fail
4. 切流前验证资源、用户、session 和索引数据。OVPack 不包含 queue、upload、lock、watch 和 relation 文件等运行时/内部状态,这些内容需要单独重建或验证。
-支持的 scope 和恢复选项详见 [OVPack 导入与导出](09-ovpack.md#全量备份与恢复)。
+支持的 scope 和恢复选项详见 [OVPack 导入与导出](09-ovpack.md#全量备份和恢复)。
### 切换密钥提供程序