From 36e81f0ef9bd2222182002341b1a8fdebda7cfef Mon Sep 17 00:00:00 2001 From: r266-tech Date: Thu, 18 Jun 2026 21:04:55 +0800 Subject: [PATCH] docs(api): document set_tags and tag retrieval filters --- docs/en/api/03-filesystem.md | 43 ++++++++++++++++++++++++++++++++++++ docs/en/api/06-retrieval.md | 8 +++++++ docs/zh/api/03-filesystem.md | 43 ++++++++++++++++++++++++++++++++++++ docs/zh/api/06-retrieval.md | 8 +++++++ 4 files changed, 102 insertions(+) diff --git a/docs/en/api/03-filesystem.md b/docs/en/api/03-filesystem.md index 446989ded5..2e77df66ab 100644 --- 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 index a38647dc57..2f43ac3f25 100644 --- 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 index 4e5509e0c9..b8aa394eb9 100644 --- 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 index 40fb0400ba..15132e8255 100644 --- 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"