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(resources): clarify add-resource target semantics (#4357)
zgy6e0aa34fabf0
diff --git a/docs/en/api/02-resources.md b/docs/en/api/02-resources.mdindex 0ef353724..8fb6a10ac 100644--- a/docs/en/api/02-resources.md+++ b/docs/en/api/02-resources.md@@ -164,7 +164,7 @@ This endpoint is the core entry point for resource management, supporting adding|-----------|------|----------|---------|-------------|| path | string | No | - | Remote resource URL (HTTP/HTTPS/Git). Mutually exclusive with `temp_file_id` || temp_file_id | string | No | - | Temporary upload file ID. Mutually exclusive with `path` |-| to | string | No | - | Target Viking URI (exact location). Mutually exclusive with `parent` |+| to | string | No | - | Final location for this import. If the target already exists, it is refreshed. Mutually exclusive with `parent` || parent | string | No | - | Parent Viking URI (resource placed under this directory). Mutually exclusive with `to` || create_parent | bool | No | False | Automatically create parent directory if it does not exist (server-side flag) || reason | string | No | "" | Reason for adding the resource. When non-empty, OpenViking runs it through the normal session memory extraction pipeline with the resource URI and records resource references in the resulting memory |@@ -183,13 +183,12 @@ This endpoint is the core entry point for resource management, supporting adding| telemetry | TelemetryRequest | No | False | Whether to return telemetry data |**Additional Notes**:-- `to` and `parent` cannot be specified together. Use `create_parent=true` with `parent` when the parent directory should be created automatically.+- `to` and `parent` cannot be specified together. `to` is the final save location: a missing target is created, and an existing target is refreshed. If the target is a directory, old files or subdirectories that are not produced by the current import may be removed. `parent` is the destination directory, and is the right option for adding a new resource under an existing directory; use `create_parent=true` or CLI `--parent-auto-create` when that directory should be created automatically. When the imported `root_uri` is the same as `to`, semantic and vector processing reuse unchanged content and process only the changed parts.- If both `to` and `parent` are omitted, the server may use the current user's `add_targets.resource_uri` override, then `server.user_config_defaults.add_targets.resource_uri`. If neither is set, legacy target resolution is unchanged.- 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`-- When `to` is specified and the target already exists, triggers incremental update- 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.diff --git a/docs/zh/api/02-resources.md b/docs/zh/api/02-resources.mdindex 8c54824ca..1465c03d9 100644--- a/docs/zh/api/02-resources.md+++ b/docs/zh/api/02-resources.md@@ -157,7 +157,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector|------|------|------|--------|------|| path | string | 否 | - | 远程资源 URL(HTTP/HTTPS/Git)。与 `temp_file_id` 二选一 || temp_file_id | string | 否 | - | 临时上传文件 ID。与 `path` 二选一 |-| to | string | 否 | - | 目标 Viking URI(精确位置)。与 `parent` 互斥 |+| to | string | 否 | - | 本次导入的最终保存位置。目标已存在时会覆盖该目标;与 `parent` 互斥 || parent | string | 否 | - | 父级 Viking URI(资源放入此目录下)。与 `to` 互斥 || create_parent | bool | 否 | False | 如果父目录不存在,自动创建父目录(服务端标志) || reason | string | 否 | "" | 添加资源的原因;非空时会随资源 URI 进入常规 session 记忆抽取链路,并在生成的记忆中记录资源引用 |@@ -178,7 +178,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector| telemetry | TelemetryRequest | 否 | False | 是否返回遥测数据 |**补充说明**:-- `to` 和 `parent` 不能同时使用;如果使用 `parent` 且希望父目录不存在时自动创建,请传 `create_parent=true`。指定 `to` 且目标已存在时,触发增量更新。+- `to` 和 `parent` 不能同时使用。`to` 是最终保存位置:目标不存在就创建,目标已存在就覆盖该目标;如果目标是目录,目录里本次导入没有生成的旧文件或子目录会被删除。`parent` 是保存目录,适合向已有目录追加新资源;父目录不存在时使用 `create_parent=true` 或 CLI 的 `--parent-auto-create`。当导入后的 `root_uri` 与 `to` 相同时,语义与向量处理会复用未变化内容,只处理变化部分。- 如果同时省略 `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`。包含路径分隔符、`.`、`..`、`:` 或 `+` 的值会被拒绝。