Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs(localfs): document case-insensitive alias behavior (#6053)
zhanggaoyuane6e5f7d2fe52
diff --git a/docs/en/api/03-filesystem.md b/docs/en/api/03-filesystem.mdindex 6287e0a50..3d0955e32 100644--- a/docs/en/api/03-filesystem.md+++ b/docs/en/api/03-filesystem.md@@ -72,6 +72,8 @@ discoverable-name behavior applies only to the shared`viking://resources` namespace; private user and peer namespaces retain theirexisting hiding rules.+On case-insensitive `localfs`, directory name aliases that differ only by case may affect what `ls`, `tree`, and `glob` can see. For example, if the real directory is `viking://resources/bob-private/`, a request for `viking://resources/BOB-PRIVATE/` may list the same directory; on case-sensitive systems, the alias directory returns `NOT_FOUND` when it does not exist.+**Python SDK (HTTP)**@@ -405,6 +407,8 @@ The `id` field (files only) is the deterministic vector record primary key in ViThe `count` field (directories only) contains the estimated number of items (files and subdirectories) under this directory (from vector index).+On case-insensitive `localfs`, `stat` may also return metadata for a real file or directory through a case-only alias. For example, `viking://resources/docs/REPORT.md` may hit the real `viking://resources/docs/report.md`; on case-sensitive systems, the alias target returns `NOT_FOUND` when it does not exist.+---### attrs()@@ -581,6 +585,8 @@ ov mkdir viking://resources/new-project/ --description "API docs directory"}```+On case-insensitive `localfs`, creating a directory that differs only by case may hit an existing directory. For example, if `viking://resources/docs/` already exists, `ov mkdir viking://resources/DOCS/` may act on the same underlying directory; on case-sensitive systems, they are separate paths.+---### rm()@@ -676,6 +682,8 @@ The `estimated_deleted_count` field (for recursive deletes) contains the estimatWhen deleting `viking://resources/...`, the response may include `memory_cleanup`, indicating that user memories referencing that resource URI were cleaned up before deletion.+On case-insensitive `localfs`, case-only aliases may affect the delete target. For example, if the real file is `viking://resources/bob-private/private.md`, `ov rm viking://resources/BOB-PRIVATE/private.md` may delete the same file; on case-sensitive systems, deleting the missing alias path still succeeds because `rm` is idempotent, but it does not delete the real file.+---### cp()@@ -762,6 +770,8 @@ ov cp -r viking://resources/docs viking://resources/docs-backupCommon errors include `NOT_FOUND` when the source or destination parent is missing, `CONFLICT` when a path lock is busy, and `INVALID_ARGUMENT` (HTTP 400) when a directory is copied or removed without `recursive=true`, a directory operation targets a file, or the source/destination relationship or file/directory types are invalid.+On case-insensitive `localfs`, both `from_uri` and `to_uri` may be affected by case-only aliases. For example, `ov cp viking://resources/BOB-PRIVATE/private.md viking://resources/archive/copy.md` may copy from the real `bob-private/private.md`; a `to_uri` that differs only by case may also overwrite an existing target. On case-sensitive systems, a differently cased missing source returns `NOT_FOUND`, and a differently cased target is a separate path.+---### mv()@@ -839,6 +849,8 @@ ov mv viking://resources/old-name/ viking://resources/new-name/}```+On case-insensitive `localfs`, both `from_uri` and `to_uri` may be affected by case-only aliases. For example, `ov mv viking://resources/BOB-PRIVATE/private.md viking://resources/archive/private.md` may move the real `bob-private/private.md`; a `to_uri` that differs only by case may also overwrite or merge into an existing target. On case-sensitive systems, a differently cased missing source returns `NOT_FOUND`, and a differently cased target is a separate path.+<a id="grep"></a><a id="glob"></a><a id="export_ovpack"></a><a id="import_ovpack"></a><a id="backup_ovpack"></a><a id="restore_ovpack"></a>diff --git a/docs/en/api/12-acl.md b/docs/en/api/12-acl.mdindex 0f018927b..6add97512 100644--- a/docs/en/api/12-acl.md+++ b/docs/en/api/12-acl.md@@ -63,6 +63,29 @@ The account's `acl.enabled` defaults to false: namespace rules apply and ACL isACL stays in the context index and follows existing asynchronous processing and wait semantics. Temporary inconsistency is accepted. Standalone ACL mutations require an existing context record. Vectorless records and empty-file support are outside this change.+## Case Aliases and ACL++When `localfs` runs on a case-insensitive filesystem, ACL is resolved from the requested URI while the underlying filesystem may resolve a URI that differs only by letter case to the same real file or directory. If the alias URI is authorized, later operations such as `read`, `stat`, `ls`, `write`, `rm`, `cp`, and `mv` may act on the real object.++Example:++```bash+# Bob's directory grants access only to Bob+ov acl set viking://resources/bob-private --acl-mode restricted --entry user:bob=manage++# Alice reading the exact path should get 403+ov read viking://resources/bob-private/private.md++# On case-insensitive localfs, the alias directory may hit the same real directory+ov read viking://resources/BOB-PRIVATE/private.md+ov ls viking://resources/BOB-PRIVATE+ov write viking://resources/BOB-PRIVATE/private.md --content changed --mode replace+```++The same risk applies to system-generated files that are reachable through public URIs in the shared resource tree, such as `.abstract.md` and `.overview.md`. For example, if the real file is `viking://resources/bob-private/.overview.md`, `viking://resources/BOB-PRIVATE/.OVERVIEW.md` may hit it. Internal databases, queues, and lock files that are not exposed through public URIs are not directly in scope for this URI alias issue.++On case-sensitive systems, `BOB-PRIVATE` and `bob-private` are different paths; a missing alias target returns `NOT_FOUND` and does not trigger this issue.+**CLI**```bashdiff --git a/docs/zh/api/03-filesystem.md b/docs/zh/api/03-filesystem.mdindex 164a49bab..cbbc56601 100644--- a/docs/zh/api/03-filesystem.md+++ b/docs/zh/api/03-filesystem.md@@ -70,6 +70,11 @@ OpenViking 提供类 Unix 的文件系统操作来管理上下文。内容。该行为只适用于共享的`viking://resources` 命名空间;个人和 peer 私有命名空间仍按原有规则隐藏。+在大小写不敏感的 `localfs` 上,目录名大小写别名可能影响 `ls`、`tree` 和 `glob`+看到的内容。例如真实目录是 `viking://resources/bob-private/`,请求+`viking://resources/BOB-PRIVATE/` 也可能列出同一目录;大小写敏感系统上,别名目录+不存在时会返回 `NOT_FOUND`。+**Python SDK (HTTP)**@@ -440,6 +445,8 @@ ov stat viking://resources/my-project/docs`count` 字段(仅目录)包含该目录下的项目(文件和子目录)估计数量(来自向量索引)。+在大小写不敏感的 `localfs` 上,`stat` 也可能通过大小写别名返回真实文件或目录的元数据。例如 `viking://resources/docs/REPORT.md` 可能命中真实的 `viking://resources/docs/report.md`;大小写敏感系统上,别名目标不存在时返回 `NOT_FOUND`。+---### attrs()@@ -616,6 +623,8 @@ ov mkdir viking://resources/new-project/ --description "接口文档目录"}```+在大小写不敏感的 `localfs` 上,创建仅大小写不同的目录可能命中已有目录。例如已存在 `viking://resources/docs/` 时,`ov mkdir viking://resources/DOCS/` 可能作用到同一个底层目录;大小写敏感系统上二者是不同路径。+---### rm()@@ -711,6 +720,8 @@ ov rm viking://resources/old.md [--recursive]删除 `viking://resources/...` 时,响应可能包含 `memory_cleanup`,表示删除前已清理引用该资源 URI 的用户记忆。+在大小写不敏感的 `localfs` 上,大小写别名可能影响删除目标。例如真实文件是 `viking://resources/bob-private/private.md`,执行 `ov rm viking://resources/BOB-PRIVATE/private.md` 可能删除同一个文件;大小写敏感系统上,别名目标不存在时该幂等删除仍会成功,但不会删除真实文件。+---### cp()@@ -797,6 +808,8 @@ ov cp -r viking://resources/docs viking://resources/docs-backup常见错误包括:源或目标父目录不存在时返回 `NOT_FOUND`;路径锁繁忙时返回 `CONFLICT`;复制或删除目录但未设置 `recursive=true`、对文件执行目录操作、源和目标关系非法或类型冲突时返回 `INVALID_ARGUMENT`(HTTP 400)。+在大小写不敏感的 `localfs` 上,`from_uri` 和 `to_uri` 都可能受大小写别名影响。例如 `ov cp viking://resources/BOB-PRIVATE/private.md viking://resources/archive/copy.md` 可能从真实的 `bob-private/private.md` 复制;`to_uri` 仅大小写不同也可能覆盖已有目标。大小写敏感系统上,大小写不同的源不存在时返回 `NOT_FOUND`,大小写不同的目标按独立路径处理。+---### mv()@@ -874,6 +887,8 @@ ov mv viking://resources/old-name/ viking://resources/new-name/}```+在大小写不敏感的 `localfs` 上,`from_uri` 和 `to_uri` 都可能受大小写别名影响。例如 `ov mv viking://resources/BOB-PRIVATE/private.md viking://resources/archive/private.md` 可能移动真实的 `bob-private/private.md`;`to_uri` 仅大小写不同也可能覆盖或合并已有目标。大小写敏感系统上,大小写不同的源不存在时返回 `NOT_FOUND`,大小写不同的目标按独立路径处理。+<a id="grep"></a><a id="glob"></a><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/12-acl.md b/docs/zh/api/12-acl.mdindex 6879a80d4..49b3ed688 100644--- a/docs/zh/api/12-acl.md+++ b/docs/zh/api/12-acl.md@@ -73,6 +73,29 @@ POST /api/v1/acl/revokeACL 仍保存在 context 索引内,允许短暂不一致,按现有异步任务和 wait 语义生效。独立修改 ACL 要求目标已有 context 记录;本次不增加无向量记录或空文件支持。+## 大小写别名与 ACL++使用 `localfs` 且底层文件系统大小写不敏感时,ACL 按请求 URI 解析权限,底层文件系统可能把仅大小写不同的 URI 解析到同一个真实文件或目录。若别名 URI 的权限判断被放行,后续 `read`、`stat`、`ls`、`write`、`rm`、`cp`、`mv` 等操作可能作用到真实对象。++直观例子:++```bash+# Bob 的目录只给 Bob 权限+ov acl set viking://resources/bob-private --acl-mode restricted --entry user:bob=manage++# Alice 读取精确路径,应返回 403+ov read viking://resources/bob-private/private.md++# 在大小写不敏感的 localfs 上,别名目录可能命中同一个真实目录+ov read viking://resources/BOB-PRIVATE/private.md+ov ls viking://resources/BOB-PRIVATE+ov write viking://resources/BOB-PRIVATE/private.md --content changed --mode replace+```++同一风险也适用于共享资源树中可通过公开 URI 访问的系统生成文件,例如 `.abstract.md` 和 `.overview.md`。例如真实文件是 `viking://resources/bob-private/.overview.md` 时,`viking://resources/BOB-PRIVATE/.OVERVIEW.md` 也可能命中它。未通过公开 URI 暴露的底层内部数据库、队列或锁文件不属于该 URI 别名问题的直接影响范围。++大小写敏感系统上,`BOB-PRIVATE` 和 `bob-private` 是不同路径;别名目标不存在时返回 `NOT_FOUND`,不会触发该问题。+**CLI**```bash