volcengine · r266-tech · Jun 18, 2026
diff --git a/docs/en/api/03-filesystem.md b/docs/en/api/03-filesystem.md
@@ -314,6 +314,49 @@ openviking write viking://resources/docs/api.md \
 
 ---
 
+### set_tags()
+
+Update explicit retrieval tags metadata for a file or directory. Tagged content can then be found with the `tags` filters on `find()` and `search()`.
+
+**Parameters**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| uri | str | Yes | - | File or directory URI to tag |
+| tags | List[str] | Yes | - | Tags to apply, for example `project:alpha` or `env:prod` |
+| mode | str | No | `replace` | `replace` overwrites explicit tags; `append` adds tags without removing existing ones |
+| recursive | bool | No | `false` | Apply the tag update to descendants when `uri` is a directory |
+
+**Python SDK (Embedded / HTTP)**
+
+```python
+client.set_tags(
+    "viking://resources/projects/alpha",
+    tags=["project:alpha", "env:prod"],
+    recursive=True,
+)
+```
+
+**HTTP API**
+
+```
+POST /api/v1/content/set_tags
+```
+
+```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/projects/alpha",
+    "tags": ["project:alpha", "env:prod"],
+    "mode": "replace",
+    "recursive": true
+  }'
+```
+
+---
+
 ### ls()
 
 List directory contents.

diff --git a/docs/en/api/06-retrieval.md b/docs/en/api/06-retrieval.md
@@ -60,6 +60,7 @@ The `find()` method performs pure vector similarity search for simple query scen
 | node_limit | int | No | None | Maximum number of results |
 | score_threshold | float | No | None | Minimum relevance score threshold |
 | filter | Dict | No | None | Metadata filter |
+| tags | List[str] | No | None | Return only content with matching retrieval tags |
 | since | str | No | None | Lower time bound, accepts `2h` or ISO 8601 / `YYYY-MM-DD`. Timezone-less values are interpreted as UTC. CLI `--after` maps to this field |
 | until | str | No | None | Upper time bound, accepts `30m` or ISO 8601 / `YYYY-MM-DD`. Timezone-less values are interpreted as UTC. CLI `--before` maps to this field |
 | time_field | "updated_at" \| "created_at" | No | "updated_at" | Metadata time field used by `since` / `until` |
@@ -251,6 +252,9 @@ openviking find "authentication" --context-type memory,resource
 # With time filter
 openviking find "invoice" --after 7d
 
+# With retrieval tags
+openviking find "deployment notes" --tags project:alpha,env:prod
+
 # With limit
 openviking find "how to authenticate users" --limit 20
 
@@ -335,6 +339,7 @@ The `search()` method adds session context understanding and intent analysis cap
 | node_limit | int | No | None | Maximum number of results |
 | score_threshold | float | No | None | Minimum relevance score threshold |
 | filter | Dict | No | None | Metadata filter |
+| tags | List[str] | No | None | Return only content with matching retrieval tags |
 | since | str | No | None | Lower time bound, accepts `2h` or ISO 8601 / `YYYY-MM-DD`. Timezone-less values are interpreted as UTC. CLI `--after` maps to this field |
 | until | str | No | None | Upper time bound, accepts `30m` or ISO 8601 / `YYYY-MM-DD`. Timezone-less values are interpreted as UTC. CLI `--before` maps to this field |
 | time_field | "updated_at" \| "created_at" | No | "updated_at" | Metadata time field used by `since` / `until` |
@@ -448,6 +453,9 @@ openviking search "best practices" --context-type skill
 # Search with time filter
 openviking search "watch vs scheduled" --after 2026-03-15 --before 2026-03-20
 
+# Search with retrieval tags
+openviking search "deployment notes" --tags project:alpha,env:prod
+
 # Search without session (still performs intent analysis)
 openviking search "how to implement OAuth 2.0 authorization code flow"
 

diff --git a/docs/zh/api/03-filesystem.md b/docs/zh/api/03-filesystem.md
@@ -314,6 +314,49 @@ openviking write viking://resources/docs/api.md \
 
 ---
 
+### set_tags()
+
+更新文件或目录的显式检索标签元数据。打过标签的内容之后可以通过 `find()` 和 `search()` 的 `tags` 过滤器检索。
+
+**参数**
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| uri | str | 是 | - | 要打标签的文件或目录 URI |
+| tags | List[str] | 是 | - | 要应用的标签，例如 `project:alpha` 或 `env:prod` |
+| mode | str | 否 | `replace` | `replace` 覆盖显式标签；`append` 在保留已有标签的基础上追加 |
+| recursive | bool | 否 | `false` | 当 `uri` 是目录时，是否递归应用到子节点 |
+
+**Python SDK (Embedded / HTTP)**
+
+```python
+client.set_tags(
+    "viking://resources/projects/alpha",
+    tags=["project:alpha", "env:prod"],
+    recursive=True,
+)
+```
+
+**HTTP API**
+
+```
+POST /api/v1/content/set_tags
+```
+
+```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/projects/alpha",
+    "tags": ["project:alpha", "env:prod"],
+    "mode": "replace",
+    "recursive": true
+  }'
+```
+
+---
+
 ### ls()
 
 列出目录内容。

diff --git a/docs/zh/api/06-retrieval.md b/docs/zh/api/06-retrieval.md
@@ -61,6 +61,7 @@ OpenViking 提供多种检索方法，包括简单的向量相似度搜索、带
 | node_limit | int | 否 | None | 可选 HTTP 别名；如果提供，会覆盖 limit |
 | score_threshold | float | 否 | None | 最低相关性分数阈值 |
 | filter | Dict | 否 | None | 元数据过滤器 |
+| tags | List[str] | 否 | None | 只返回匹配检索标签的内容 |
 | since | str | 否 | None | 时间下界，支持 `2h` 或 ISO 8601 / `YYYY-MM-DD`。不带时区的值按 UTC 解释。CLI `--after` 会映射到这个字段 |
 | until | str | 否 | None | 时间上界，支持 `30m` 或 ISO 8601 / `YYYY-MM-DD`。不带时区的值按 UTC 解释。CLI `--before` 会映射到这个字段 |
 | time_field | "updated_at" \| "created_at" | 否 | "updated_at" | since/until 使用的元数据时间字段 |
@@ -252,6 +253,9 @@ openviking find "authentication" --context-type memory,resource
 # 带时间过滤
 openviking find "invoice" --after 7d
 
+# 带检索标签过滤
+openviking find "deployment notes" --tags project:alpha,env:prod
+
 # 带限制数量
 openviking find "how to authenticate users" --limit 20
 
@@ -337,6 +341,7 @@ openviking find "how to authenticate users" -L 1,2
 | node_limit | int | 否 | None | 可选 HTTP 别名；如果提供，会覆盖 limit |
 | score_threshold | float | 否 | None | 最低相关性分数阈值 |
 | filter | Dict | 否 | None | 元数据过滤器 |
+| tags | List[str] | 否 | None | 只返回匹配检索标签的内容 |
 | since | str | 否 | None | 时间下界，支持 `2h` 或 ISO 8601 / `YYYY-MM-DD`。不带时区的值按 UTC 解释。CLI `--after` 会映射到这个字段 |
 | until | str | 否 | None | 时间上界，支持 `30m` 或 ISO 8601 / `YYYY-MM-DD`。不带时区的值按 UTC 解释。CLI `--before` 会映射到这个字段 |
 | time_field | "updated_at" \| "created_at" | 否 | "updated_at" | since/until 使用的元数据时间字段 |
@@ -450,6 +455,9 @@ openviking search "best practices" --context-type skill
 # 带时间过滤的搜索
 openviking search "watch vs scheduled" --after 2026-03-15 --before 2026-03-20
 
+# 带检索标签过滤
+openviking search "deployment notes" --tags project:alpha,env:prod
+
 # 不带会话的搜索（仍进行意图分析）
 openviking search "how to implement OAuth 2.0 authorization code flow"