Skip to content

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

Feat/cli unify tags flag (#4599)

Jiahui Zhoubbc1f9bab00e
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rs
index 511ca9d3d..5464fac19 100644
--- a/crates/ov_cli/src/main.rs
+++ b/crates/ov_cli/src/main.rs
@@ -449,10 +449,10 @@ enum Commands {
/// locally, e.g. --args dry_run:true (supported keys: catalog, dry_run, skip_failed)
#[arg(long = "args")]
resource_args: Option<String>,
- /// Explicit k=v retrieval tag to apply after import. Can be repeated.
- #[arg(long = "tag", value_name = "k=v", help_heading = "Common options")]
+ /// Comma-separated k=v retrieval tags to apply after import
+ #[arg(long = "tags", value_delimiter = ',', value_name = "k=v", help_heading = "Common options")]
tags: Vec<String>,
- /// Tag update mode when --tag is provided
+ /// Tag update mode when --tags is provided
#[arg(
long = "tag-mode",
default_value = "replace",
@@ -1218,10 +1218,10 @@ enum Commands {
/// Preview prune_orphans deletions without mutating vectors
#[arg(long, help_heading = "Common options")]
dry_run: bool,
- /// Explicit k=v retrieval tag for rebuilt vector records. Can be repeated.
- #[arg(long = "tag", value_name = "k=v", help_heading = "Common options")]
+ /// Comma-separated k=v retrieval tags for rebuilt vector records
+ #[arg(long = "tags", value_delimiter = ',', value_name = "k=v", help_heading = "Common options")]
tags: Vec<String>,
- /// Tag update mode when --tag is provided
+ /// Tag update mode when --tags is provided
#[arg(
long = "tag-mode",
default_value = "replace",
@@ -4568,10 +4568,8 @@ mod tests {
"ov",
"add-resource",
"./README.md",
- "--tag",
- "team=search",
- "--tag",
- "env=test",
+ "--tags",
+ "team=search,env=test",
"--tag-mode",
"append",
])
@@ -5543,7 +5541,7 @@ mod tests {
"prune_orphans",
"--wait=false",
"--dry-run",
- "--tag",
+ "--tags",
"team=search",
"--tag-mode",
"append",
diff --git a/docs/en/api/06-retrieval.md b/docs/en/api/06-retrieval.md
index bd0b01ebf..f39aed1bf 100644
--- a/docs/en/api/06-retrieval.md
+++ b/docs/en/api/06-retrieval.md
@@ -58,7 +58,7 @@ The `find()` method performs pure vector similarity search for simple query scen
| image_url | str | No | None | Image query as a `data:image/...;base64,...`, `http(s)://`, or `viking://` URI. Requires a multimodal embedding model |
| target_uri | str \| List[str] | No | "" | Limit search to specific URI prefix |
| context_type | str \| List[str] | No | None | Limit results to one or more `ContextType` values: `memory`, `resource`, or `skill` |
-| tags | List[str] | No | None | Explicit retrieval tags in strict `k=v` form. Multiple tags are combined with AND; a result must contain every requested tag |
+| tags | List[str] | No | None | Explicit retrieval tags in strict `k=v` form (lowercase letters/digits/`_`/`-`/`.`, starting with a letter or digit, key<=64, value<=128). Multiple tags are combined with AND; a result must contain every requested tag |
| node_limit | int | No | None | Maximum number of results |
| score_threshold | float | No | None | Minimum relevance score threshold |
| filter | Dict | No | None | Metadata filter |
@@ -176,7 +176,7 @@ curl -X POST http://localhost:1933/api/v1/search/find \
}'
```
-Tags must use strict `k=v` strings. When multiple tags are provided, `find()` requires all of them; the example above only returns contexts whose explicit retrieval tags contain both `env=prod` and `team=search`.
+Tags must use strict `k=v` strings: both key and value are non-empty, contain exactly one `=`, are made only of lowercase letters, digits, `_`, `-`, `.` and start with a letter or digit (the server trims whitespace and lowercases). The key is capped at 64 and the value at 128 characters. When multiple tags are provided, `find()` requires all of them; the example above only returns contexts whose explicit retrieval tags contain both `env=prod` and `team=search`.
**Python SDK**
@@ -396,7 +396,7 @@ The `search()` method adds session context understanding and intent analysis cap
| session | Session | No | None | Session for context-aware search (SDK) |
| session_id | str | No | None | Session ID for context-aware search (HTTP) |
| context_type | str \| List[str] | No | None | Limit results to one or more `ContextType` values: `memory`, `resource`, or `skill` |
-| tags | List[str] | No | None | Explicit retrieval tags in strict `k=v` form. Multiple tags are combined with AND; a result must contain every requested tag |
+| tags | List[str] | No | None | Explicit retrieval tags in strict `k=v` form (lowercase letters/digits/`_`/`-`/`.`, starting with a letter or digit, key<=64, value<=128). Multiple tags are combined with AND; a result must contain every requested tag |
| node_limit | int | No | None | Maximum number of results |
| score_threshold | float | No | None | Minimum relevance score threshold |
| filter | Dict | No | None | Metadata filter |
diff --git a/docs/en/api/12-content.md b/docs/en/api/12-content.md
index c2ea88e34..df49478ca 100644
--- a/docs/en/api/12-content.md
+++ b/docs/en/api/12-content.md
@@ -491,7 +491,7 @@ Content-Disposition: attachment; filename*=UTF-8''logo.png
### 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.
+Set explicit `k=v` tags used by retrieval filters. Both key and value are non-empty, contain exactly one `=`, are made only of lowercase letters, digits, `_`, `-`, `.` and start with a letter or digit (the server trims whitespace and lowercases); the key is capped at 64 and the value at 128 characters, and invalid tags are rejected. `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**
diff --git a/docs/zh/api/06-retrieval.md b/docs/zh/api/06-retrieval.md
index 169aa01b9..59c1c1274 100644
--- a/docs/zh/api/06-retrieval.md
+++ b/docs/zh/api/06-retrieval.md
@@ -58,7 +58,7 @@ OpenViking 提供多种检索方法,包括简单的向量相似度搜索、带
| image_url | str | 否 | None | 图片查询,支持 `data:image/...;base64,...`、`http(s)://` 或 `viking://` URI;需要 multimodal embedding 模型 |
| target_uri | str \| List[str] | 否 | "" | 限制搜索范围到指定的 URI 前缀 |
| context_type | str \| List[str] | 否 | None | 限定一个或多个 `ContextType` 取值:`memory`、`resource` 或 `skill` |
-| tags | List[str] | 否 | None | 显式检索标签,必须是严格的 `k=v` 格式。多个 tags 之间是 AND 关系,结果必须同时包含所有请求的标签 |
+| tags | List[str] | 否 | None | 显式检索标签,必须是严格的 `k=v` 格式(小写字母/数字/`_`/`-`/`.`,以字母或数字开头,key≤64、value≤128)。多个 tags 之间是 AND 关系,结果必须同时包含所有请求的标签 |
| limit | int | 否 | 10 | 最大返回结果数 |
| node_limit | int | 否 | None | 可选 HTTP 别名;如果提供,会覆盖 limit |
| score_threshold | float | 否 | None | 最低相关性分数阈值 |
@@ -177,7 +177,7 @@ curl -X POST http://localhost:1933/api/v1/search/find \
}'
```
-Tags 必须使用严格的 `k=v` 字符串。传入多个 tags 时,`find()` 会要求全部命中;上面的例子只返回显式检索标签同时包含 `env=prod` 和 `team=search` 的上下文。
+Tags 必须使用严格的 `k=v` 字符串:key 和 value 都非空,只能有一个 `=`,仅由小写字母、数字、`_`、`-`、`.` 组成且以字母或数字开头(服务端会去空白并转小写),key 最长 64、value 最长 128 字符。传入多个 tags 时,`find()` 会要求全部命中;上面的例子只返回显式检索标签同时包含 `env=prod` 和 `team=search` 的上下文。
**Python SDK**
@@ -397,7 +397,7 @@ openviking find "红色海报风格" --image ./poster.png --uri "viking://resour
| session | Session | 否 | None | 用于上下文感知搜索的会话(SDK)|
| session_id | str | 否 | None | 用于上下文感知搜索的会话 ID(HTTP)|
| context_type | str \| List[str] | 否 | None | 限定一个或多个 `ContextType` 取值:`memory`、`resource` 或 `skill` |
-| tags | List[str] | 否 | None | 显式检索标签,必须是严格的 `k=v` 格式。多个 tags 之间是 AND 关系,结果必须同时包含所有请求的标签 |
+| tags | List[str] | 否 | None | 显式检索标签,必须是严格的 `k=v` 格式(小写字母/数字/`_`/`-`/`.`,以字母或数字开头,key≤64、value≤128)。多个 tags 之间是 AND 关系,结果必须同时包含所有请求的标签 |
| limit | int | 否 | 10 | 最大返回结果数 |
| node_limit | int | 否 | None | 可选 HTTP 别名;如果提供,会覆盖 limit |
| score_threshold | float | 否 | None | 最低相关性分数阈值 |
diff --git a/docs/zh/api/12-content.md b/docs/zh/api/12-content.md
index fe2febb93..6f877ddf3 100644
--- a/docs/zh/api/12-content.md
+++ b/docs/zh/api/12-content.md
@@ -491,7 +491,7 @@ Content-Disposition: attachment; filename*=UTF-8''logo.png
### set_tags()
-设置用于检索过滤的显式 `k=v` 标签。`replace` 替换已有标签,`append` 追加标签;对目录设置 `recursive=true` 时会更新目录下的文件。
+设置用于检索过滤的显式 `k=v` 标签。key 和 value 都非空、只能有一个 `=`,仅由小写字母、数字、`_`、`-`、`.` 组成且以字母或数字开头(服务端会去空白并转小写),key 最长 64、value 最长 128 字符;不合规的标签会被拒绝。`replace` 替换已有标签,`append` 追加标签;对目录设置 `recursive=true` 时会更新目录下的文件。
**Python SDK**
diff --git a/openviking/utils/tags.py b/openviking/utils/tags.py
index c9c581ae6..a6faa5e08 100644
--- a/openviking/utils/tags.py
+++ b/openviking/utils/tags.py
@@ -5,6 +5,7 @@
from __future__ import annotations
import logging
+import re
from collections import OrderedDict
from typing import Any, Iterable
@@ -12,12 +13,25 @@ from openviking_cli.exceptions import InvalidArgumentError
logger = logging.getLogger(__name__)
+# Explicit search tags are meant to be small, enumerable business dimensions
+# (env, team, source, ...). Constrain both sides of ``k=v`` so tags stay stable
+# identifiers rather than free-form text: bounded length and a predictable
+# character set after lower-casing (no internal spaces, no ``=``).
+MAX_TAG_KEY_LENGTH = 64
+MAX_TAG_VALUE_LENGTH = 128
+MAX_TAG_LENGTH = MAX_TAG_KEY_LENGTH + 1 + MAX_TAG_VALUE_LENGTH
+_TAG_TOKEN_RE = re.compile(r"^[a-z0-9][a-z0-9_.-]*$")
+
def normalize_search_tag(tag: str) -> str:
"""Validate and normalize a single k=v search tag."""
value = str(tag).strip().lower()
if not value:
raise InvalidArgumentError("search tag must be a non-empty k=v string")
+ if len(value) > MAX_TAG_LENGTH:
+ raise InvalidArgumentError(
+ f"invalid search tag '{tag}': exceeds max length {MAX_TAG_LENGTH}"
+ )
if value.count("=") != 1:
raise InvalidArgumentError(f"invalid search tag '{tag}': expected strict k=v format")
@@ -26,6 +40,19 @@ def normalize_search_tag(tag: str) -> str:
raise InvalidArgumentError(
f"invalid search tag '{tag}': key and value must both be non-empty"
)
+ if len(key) > MAX_TAG_KEY_LENGTH:
+ raise InvalidArgumentError(
+ f"invalid search tag '{tag}': key exceeds max length {MAX_TAG_KEY_LENGTH}"
+ )
+ if len(raw_value) > MAX_TAG_VALUE_LENGTH:
+ raise InvalidArgumentError(
+ f"invalid search tag '{tag}': value exceeds max length {MAX_TAG_VALUE_LENGTH}"
+ )
+ if not _TAG_TOKEN_RE.match(key) or not _TAG_TOKEN_RE.match(raw_value):
+ raise InvalidArgumentError(
+ f"invalid search tag '{tag}': key and value may only contain lowercase "
+ "letters, digits, '_', '-', '.', and must start with a letter or digit"
+ )
return f"{key}={raw_value}"
diff --git a/tests/unit/test_search_tags_filter.py b/tests/unit/test_search_tags_filter.py
index f51435864..a7b584746 100644
--- a/tests/unit/test_search_tags_filter.py
+++ b/tests/unit/test_search_tags_filter.py
@@ -3,9 +3,19 @@
import logging
+import pytest
+
from openviking.server.routers.search import _resolve_search_filter
from openviking.utils import tags as tags_module
-from openviking.utils.tags import build_search_tags_filter, merge_search_tags, normalize_search_tags
+from openviking.utils.tags import (
+ MAX_TAG_KEY_LENGTH,
+ MAX_TAG_VALUE_LENGTH,
+ build_search_tags_filter,
+ merge_search_tags,
+ normalize_search_tag,
+ normalize_search_tags,
+)
+from openviking_cli.exceptions import InvalidArgumentError
def test_search_tags_filter_keeps_single_tag_as_single_must():
@@ -30,6 +40,44 @@ def test_search_tags_duplicate_keys_keep_last_value():
assert normalize_search_tags(["channel=web", "channel=app"]) == ["channel=app"]
+def test_search_tag_allows_dot_dash_underscore():
+ assert normalize_search_tag("doc_type=api-v1.2") == "doc_type=api-v1.2"
+
+
+ "tag",
+ [
+ "team=search platform", # internal space
+ "team=with/slash", # unsupported char
+ "team=值", # non-ascii
+ "-team=search", # must start with letter/digit
+ "team=-search",
+ "te=am=search", # more than one '='
+ ],
+)
+def test_search_tag_rejects_disallowed_characters(tag):
+ with pytest.raises(InvalidArgumentError):
+ normalize_search_tag(tag)
+
+
+def test_search_tag_rejects_over_length_key():
+ over_key = "k" * (MAX_TAG_KEY_LENGTH + 1)
+ with pytest.raises(InvalidArgumentError):
+ normalize_search_tag(f"{over_key}=v")
+
+
+def test_search_tag_rejects_over_length_value():
+ over_value = "v" * (MAX_TAG_VALUE_LENGTH + 1)
+ with pytest.raises(InvalidArgumentError):
+ normalize_search_tag(f"team={over_value}")
+
+
+def test_search_tag_accepts_boundary_lengths():
+ key = "k" * MAX_TAG_KEY_LENGTH
+ value = "v" * MAX_TAG_VALUE_LENGTH
+ assert normalize_search_tag(f"{key}={value}") == f"{key}={value}"
+
+
def test_discard_invalid_search_tags_logs_one_warning_for_batch(caplog):
tags_module.logger.addHandler(caplog.handler)
try: