Skip to content

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

feat(server): add user add target defaults (#2888)

Qin Haojied7b96d771576
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rs
index dc7159756..8d4000325 100644
--- a/crates/ov_cli/src/client.rs
+++ b/crates/ov_cli/src/client.rs
@@ -1246,12 +1246,22 @@ impl HttpClient {
&self,
account_id: &str,
admin_user_id: &str,
+ user_config: Option<&Value>,
) -> Result<Value> {
- let body = serde_json::json!({
- "account_id": account_id,
- "admin_user_id": admin_user_id,
- });
- self.post("/api/v1/admin/accounts", &body).await
+ let mut body = Map::new();
+ body.insert(
+ "account_id".to_string(),
+ Value::String(account_id.to_string()),
+ );
+ body.insert(
+ "admin_user_id".to_string(),
+ Value::String(admin_user_id.to_string()),
+ );
+ if let Some(config) = user_config {
+ body.insert("user_config".to_string(), config.clone());
+ }
+ self.post("/api/v1/admin/accounts", &Value::Object(body))
+ .await
}
pub async fn admin_list_accounts(&self) -> Result<Value> {
@@ -1268,13 +1278,16 @@ impl HttpClient {
account_id: &str,
user_id: &str,
role: &str,
+ user_config: Option<&Value>,
) -> Result<Value> {
let path = format!("/api/v1/admin/accounts/{}/users", account_id);
- let body = serde_json::json!({
- "user_id": user_id,
- "role": role,
- });
- self.post(&path, &body).await
+ let mut body = Map::new();
+ body.insert("user_id".to_string(), Value::String(user_id.to_string()));
+ body.insert("role".to_string(), Value::String(role.to_string()));
+ if let Some(config) = user_config {
+ body.insert("user_config".to_string(), config.clone());
+ }
+ self.post(&path, &Value::Object(body)).await
}
pub async fn admin_list_users(
diff --git a/crates/ov_cli/src/commands/admin.rs b/crates/ov_cli/src/commands/admin.rs
index 4dc8091e2..07747dfb0 100644
--- a/crates/ov_cli/src/commands/admin.rs
+++ b/crates/ov_cli/src/commands/admin.rs
@@ -1,5 +1,5 @@
use crate::client::HttpClient;
-use crate::error::Result;
+use crate::error::{Error, Result};
use crate::output::{OutputFormat, output_success};
use crate::theme;
use colored::Colorize;
@@ -11,11 +11,13 @@ pub async fn create_account(
client: &HttpClient,
account_id: &str,
admin_user_id: &str,
+ user_config_json: Option<&str>,
output_format: OutputFormat,
compact: bool,
) -> Result<()> {
+ let user_config = parse_user_config_json(user_config_json, "--user-config-json")?;
let response = client
- .admin_create_account(account_id, admin_user_id)
+ .admin_create_account(account_id, admin_user_id, user_config.as_ref())
.await?;
output_success(&response, output_format, compact);
print_admin_user_key_notice(&response, output_format, false);
@@ -65,17 +67,31 @@ pub async fn register_user(
account_id: &str,
user_id: &str,
role: &str,
+ user_config_json: Option<&str>,
output_format: OutputFormat,
compact: bool,
) -> Result<()> {
+ let user_config = parse_user_config_json(user_config_json, "--user-config-json")?;
let response = client
- .admin_register_user(account_id, user_id, role)
+ .admin_register_user(account_id, user_id, role, user_config.as_ref())
.await?;
output_success(&response, output_format, compact);
print_admin_user_key_notice(&response, output_format, false);
Ok(())
}
+fn parse_user_config_json(value: Option<&str>, flag: &str) -> Result<Option<Value>> {
+ let Some(value) = value else {
+ return Ok(None);
+ };
+ let parsed: Value = serde_json::from_str(value)
+ .map_err(|err| Error::Client(format!("{flag} must be valid JSON: {err}")))?;
+ if !parsed.is_object() {
+ return Err(Error::Client(format!("{flag} must be a JSON object")));
+ }
+ Ok(Some(parsed))
+}
+
pub async fn list_users(
client: &HttpClient,
account_id: &str,
diff --git a/crates/ov_cli/src/handlers.rs b/crates/ov_cli/src/handlers.rs
index 35e96de61..fb2fed9ac 100644
--- a/crates/ov_cli/src/handlers.rs
+++ b/crates/ov_cli/src/handlers.rs
@@ -505,11 +505,13 @@ pub async fn handle_admin(cmd: AdminCommands, ctx: CliContext) -> Result<()> {
AdminCommands::CreateAccount {
account_id,
admin_user_id,
+ user_config_json,
} => {
commands::admin::create_account(
&client,
&account_id,
&admin_user_id,
+ user_config_json.as_deref(),
ctx.output_format,
ctx.compact,
)
@@ -529,12 +531,14 @@ pub async fn handle_admin(cmd: AdminCommands, ctx: CliContext) -> Result<()> {
account_id,
user_id,
role,
+ user_config_json,
} => {
commands::admin::register_user(
&client,
&account_id,
&user_id,
&role,
+ user_config_json.as_deref(),
ctx.output_format,
ctx.compact,
)
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rs
index 0d88793df..109bd5ae2 100644
--- a/crates/ov_cli/src/main.rs
+++ b/crates/ov_cli/src/main.rs
@@ -1500,6 +1500,9 @@ enum AdminCommands {
/// First admin user ID
#[arg(long = "admin", value_name = "user-id")]
admin_user_id: String,
+ /// Initial config for the first admin user as JSON
+ #[arg(long = "user-config-json", value_name = "json")]
+ user_config_json: Option<String>,
},
/// List all accounts (ROOT only)
ListAccounts,
@@ -1526,6 +1529,9 @@ enum AdminCommands {
/// Role: admin or user
#[arg(long, default_value = "user", value_name = "role")]
role: String,
+ /// Initial config for the new user as JSON
+ #[arg(long = "user-config-json", value_name = "json")]
+ user_config_json: Option<String>,
},
/// List all users in an account
ListUsers {
diff --git a/docs/en/api/02-resources.md b/docs/en/api/02-resources.md
index df5619095..ad286681c 100644
--- a/docs/en/api/02-resources.md
+++ b/docs/en/api/02-resources.md
@@ -174,6 +174,7 @@ This endpoint is the core entry point for resource management, supporting adding
**Additional Notes**:
- `to` and `parent` cannot be specified together. Use `create_parent=true` with `parent` when the parent directory should be created automatically.
+- 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/...`, current-user shorthand `viking://user/resources/...`, explicit user `viking://user/{user_id}/resources/...`, or peer `viking://user/{user_id}/peers/{peer_id}/resources/...` paths. Current-user shorthand is canonicalized with the authenticated request identity.
- `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
@@ -623,14 +624,18 @@ Skills are special resources used to define operations or tools that agents can
|-----------|------|----------|---------|-------------|
| data | Any | No | - | Inline skill content or structured data. Mutually exclusive with `temp_file_id` |
| temp_file_id | string | No | - | Temporary upload file ID (obtained via [temp_upload](#temp_upload)). Mutually exclusive with `data` |
+| target_uri | string | No | - | Skill root override. Explicit value wins over user and deployment defaults |
| wait | bool | No | False | Whether to wait for skill processing to complete |
| timeout | float | No | None | Timeout in seconds, only effective when `wait=True` |
| telemetry | TelemetryRequest | No | False | Whether to return telemetry data |
-Skills are always installed under the current user's skills root. The public short form
-`viking://user/skills` is accepted for filesystem/search operations and resolves to
-`viking://user/{user_id}/skills`; `add_skill` does not accept `to`, `parent`,
-`root_uri`, or peer-scoped skill targets.
+When `target_uri` is omitted, the server may use the current user's
+`add_targets.skill_uri` override, then
+`server.user_config_defaults.add_targets.skill_uri`. If neither is set,
+legacy behavior installs under the current user's skills root. The public
+short form `viking://user/skills` resolves to
+`viking://user/{user_id}/skills`. The v1 API accepts only
+`viking://user/skills` and `viking://agent/skills` as skill add roots.
#### 3. Usage Examples
diff --git a/docs/en/api/08-admin.md b/docs/en/api/08-admin.md
index 515b68d3e..a8cf0d52f 100644
--- a/docs/en/api/08-admin.md
+++ b/docs/en/api/08-admin.md
@@ -68,7 +68,8 @@ Create a new workspace with its first admin user.
2. Use API Key Manager to create account and initial admin user
3. Initialize account-level directory structure
4. Initialize admin user's personal directory
-5. Return account info and user key (not in trusted mode)
+5. Write optional initial admin user config
+6. Return account info and user key (not in trusted mode)
**Code Entry Points:**
- `openviking/server/routers/admin.py:create_account` - HTTP route
@@ -83,10 +84,13 @@ Create a new workspace with its first admin user.
|-----------|------|----------|---------|-------------|
| account_id | str | Yes | - | Workspace ID |
| admin_user_id | str | Yes | - | First admin user ID |
+| user_config | object | No | `null` | Initial config for the first admin user. Currently supports `add_targets.resource_uri` and `add_targets.skill_uri` |
**Notes:**
- In `trusted` mode, `user_key` is omitted from the response
- Account-level namespace isolation settings are no longer supported. User memory uses user-scoped namespaces, and one-to-many external participants are represented with `peer_id`.
+- `user_config.add_targets.resource_uri` must be a writable resource directory URI: `viking://resources` or `viking://resources/...`, `viking://user/resources` or `viking://user/resources/...`, `viking://user/{user_id}/resources` or `viking://user/{user_id}/resources/...`, or `viking://user/{user_id}/peers/{peer_id}/resources` or `viking://user/{user_id}/peers/{peer_id}/resources/...`.
+- `user_config.add_targets.skill_uri` must be `viking://user/skills` or `viking://agent/skills`. Explicit `viking://user/{user_id}/skills` is not accepted in v1.
#### 3. Usage Examples
@@ -160,6 +164,17 @@ result = client.admin_create_account("acme", "alice")
print(f"Account created: {result['account_id']}")
print(f"Admin user: {result['admin_user_id']}")
print(f"User key: {result.get('user_key', '(not exposed in trusted mode)')}")
+
+result = client.admin_create_account(
+ "acme-private",
+ "alice",
+ user_config={
+ "add_targets": {
+ "resource_uri": "viking://user/resources",
+ "skill_uri": "viking://user/skills",
+ }
+ },
+)
```
**Go SDK**
@@ -170,6 +185,15 @@ if err != nil {
return err
}
fmt.Println(result["account_id"])
+
+result, err = client.AdminCreateAccountWithOptions(ctx, "acme-private", "alice", &openviking.AdminCreateAccountOptions{
+ UserConfig: map[string]any{
+ "add_targets": map[string]any{
+ "resource_uri": "viking://user/resources",
+ "skill_uri": "viking://user/skills",
+ },
+ },
+})
```
**CLI**
@@ -177,6 +201,9 @@ fmt.Println(result["account_id"])
```bash
# Requires ROOT privileges, use --sudo
ov --sudo admin create-account acme --admin alice
+
+ov --sudo admin create-account acme-private --admin alice \
+ --user-config-json '{"add_targets":{"resource_uri":"viking://user/resources","skill_uri":"viking://user/skills"}}'
```
**Response Example**
@@ -370,7 +397,8 @@ Register a new user in a workspace.
1. Verify requester has ROOT privileges or is an ADMIN of the account
2. Call API Key Manager to register new user
3. Initialize new user's personal directory
-4. Return user info and user key (not in trusted mode)
+4. Write optional initial user config
+5. Return user info and user key (not in trusted mode)
**Code Entry Points:**
- `openviking/server/routers/admin.py:register_user` - HTTP route
@@ -386,11 +414,14 @@ Register a new user in a workspace.
| account_id | str | Yes | - | Workspace ID |
| user_id | str | Yes | - | User ID |
| role | str | No | "user" | Role to assign. `ROOT` and same-account `ADMIN` may register `"user"` or `"admin"`. `"root"` must be assigned through the dedicated role-change endpoint. |
+| user_config | object | No | `null` | Initial config for the new user. Currently supports `add_targets.resource_uri` and `add_targets.skill_uri` |
**Notes:**
- In `trusted` mode, `user_key` is omitted from the response
- ADMIN can only register users in their own account
- The `"root"` role cannot be minted through user registration
+- `user_config.add_targets.resource_uri` must be a writable resource directory URI: `viking://resources` or `viking://resources/...`, `viking://user/resources` or `viking://user/resources/...`, `viking://user/{user_id}/resources` or `viking://user/{user_id}/resources/...`, or `viking://user/{user_id}/peers/{peer_id}/resources` or `viking://user/{user_id}/peers/{peer_id}/resources/...`.
+- `user_config.add_targets.skill_uri` must be `viking://user/skills` or `viking://agent/skills`. Explicit `viking://user/{user_id}/skills` is not accepted in v1.
#### 3. Usage Examples
@@ -421,6 +452,13 @@ client.initialize()
result = client.admin_register_user("acme", "bob", role="user")
print(f"User registered: {result['user_id']}")
print(f"User key: {result.get('user_key', '(not exposed in trusted mode)')}")
+
+result = client.admin_register_user(
+ "acme",
+ "bob-private",
+ role="user",
+ user_config={"add_targets": {"resource_uri": "viking://user/resources/project-a"}},
+)
```
**Go SDK**
@@ -431,6 +469,12 @@ if err != nil {
return err
}
fmt.Println(result["user_id"])
+
+result, err = client.AdminRegisterUserWithOptions(ctx, "acme", "bob-private", "user", &openviking.AdminRegisterUserOptions{
+ UserConfig: map[string]any{
+ "add_targets": map[string]any{"resource_uri": "viking://user/resources/project-a"},
+ },
+})
```
**CLI**
@@ -441,6 +485,9 @@ fmt.Println(result["user_id"])
ov admin register-user acme bob --role user
# If using root_api_key (--sudo):
ov --sudo admin register-user acme bob --role user
+
+ov admin register-user acme bob-private --role user \
+ --user-config-json '{"add_targets":{"resource_uri":"viking://user/resources/project-a"}}'
```
**Response Example**
@@ -926,6 +973,50 @@ ov --sudo admin migrate --cleanup --output json
---
+### user add-location settings
+
+Per-user add defaults are stored as user config under
+`viking://user/{user_id}/settings/user_config.json`. They affect add calls that
+omit explicit targets:
+
+1. `add_resource`: explicit `to` / `parent` wins, then user
+ `add_targets.resource_uri`, then
+ `server.user_config_defaults.add_targets.resource_uri`, then legacy behavior.
+2. `add_skill`: explicit `target_uri` wins, then user
+ `add_targets.skill_uri`, then
+ `server.user_config_defaults.add_targets.skill_uri`, then legacy behavior.
+
+#### HTTP API
+
+```
+GET /api/v1/user-settings/add-locations
+PATCH /api/v1/user-settings/add-locations
+DELETE /api/v1/user-settings/add-locations
+```
+
+`PATCH` accepts the add-target fields directly. Passing `null` clears one field;
+deleting the settings clears the whole per-user override.
+
+```bash
+curl -X PATCH http://localhost:1933/api/v1/user-settings/add-locations \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: <user-key>" \
+ -d '{"resource_uri": "viking://user/resources/project-a"}'
+```
+
+`resource_uri` must be a writable resource directory URI:
+`viking://resources` or `viking://resources/...`,
+`viking://user/resources` or `viking://user/resources/...`,
+`viking://user/{user_id}/resources` or
+`viking://user/{user_id}/resources/...`, or
+`viking://user/{user_id}/peers/{peer_id}/resources` or
+`viking://user/{user_id}/peers/{peer_id}/resources/...`. `skill_uri` must be
+`viking://user/skills` or `viking://agent/skills`; explicit
+`viking://user/{user_id}/skills` is not accepted in v1. Invalid configured
+values are rejected; OpenViking does not silently fall back to another target.
+
+---
+
## Full Example
### Typical Admin Workflow
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index 05d6ebd49..6ac6bd7bb 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -1398,6 +1398,12 @@ When running OpenViking as an HTTP service, add a `server` section to `ov.conf`:
"default_mode": "local",
"shared_max_size_bytes": 536870912,
"shared_prefix": "viking://upload"
+ },
+ "user_config_defaults": {
+ "add_targets": {
+ "resource_uri": "viking://user/resources",
+ "skill_uri": "viking://user/skills"
+ }
}
}
}
@@ -1416,11 +1422,20 @@ When running OpenViking as an HTTP service, add a `server` section to `ov.conf`:
| `temp_upload.default_mode` | str | Server-side default for `POST /api/v1/resources/temp_upload` when the client does not send `upload_mode`: `"local"` (per-instance disk, current single-node behavior) or `"shared"` (distributed shared store usable across replicas). | `"local"` |
| `temp_upload.shared_max_size_bytes` | int | Maximum size accepted in `shared` mode, in bytes. Requests above this size are rejected before object-store write. | `536870912` (512 MiB) |
| `temp_upload.shared_prefix` | str | URI prefix used when allocating shared `temp_file_id` objects. | `"viking://upload"` |
+| `user_config_defaults.add_targets.resource_uri` | str | Deployment default resource add directory used when `add_resource` omits both `to` and `parent`. `viking://user/...` resolves per request user. | `null` |
+| `user_config_defaults.add_targets.skill_uri` | str | Deployment default skill add root used when `add_skill` omits `target_uri`. Only `viking://user/skills` and `viking://agent/skills` are accepted. | `null` |
`api_key` mode uses API keys and is the default. `trusted` mode trusts `X-OpenViking-Account` / `X-OpenViking-User` headers from a trusted gateway or internal caller.
When `root_api_key` is configured in `api_key` mode, the server enables multi-tenant authentication. Use the Admin API to create accounts and user keys. In `trusted` mode, ordinary requests do not require user registration first; each request is resolved as `USER` from the injected identity headers. However, skipping `root_api_key` in `trusted` mode is allowed only on localhost. Development mode only applies when `auth_mode = "api_key"` and `root_api_key` is not set.
+`user_config_defaults` sets defaults for new and existing users when they have no per-user override. For add operations, explicit request targets still win: `add_resource.to` / `add_resource.parent` take precedence over user defaults, and `add_skill.target_uri` takes precedence over user defaults. Per-user overrides are stored in `viking://user/{user_id}/settings/user_config.json`.
+
+Supported add target URIs:
+
+- `resource_uri` is used as the default `add_resource` parent directory, equivalent to `parent=<uri>, create_parent=true`. It must be a writable resource directory URI for the request user. Supported forms are `viking://resources` or `viking://resources/...`, `viking://user/resources` or `viking://user/resources/...`, `viking://user/{user_id}/resources` or `viking://user/{user_id}/resources/...`, and `viking://user/{user_id}/peers/{peer_id}/resources` or `viking://user/{user_id}/peers/{peer_id}/resources/...`. The `viking://user/...` shorthand resolves per request user.
+- `skill_uri` is used as the default `add_skill` target root. In v1, only `viking://user/skills` and `viking://agent/skills` are accepted; explicit `viking://user/{user_id}/skills` is not accepted.
+
For startup and deployment details see [Deployment](./03-deployment.md), for authentication see [Authentication](./04-authentication.md).
## storage.transaction Section
diff --git a/docs/zh/api/02-resources.md b/docs/zh/api/02-resources.md
index b8aec9c4e..b6adeb0ff 100644
--- a/docs/zh/api/02-resources.md
+++ b/docs/zh/api/02-resources.md
@@ -168,6 +168,7 @@ URL/文件 Parser TreeBuilder AGFS Summarizer/Vector
**补充说明**:
- `to` 和 `parent` 不能同时使用;如果使用 `parent` 且希望父目录不存在时自动创建,请传 `create_parent=true`。指定 `to` 且目标已存在时,触发增量更新。
+- 如果同时省略 `to` 和 `parent`,服务端会先尝试使用当前用户的 `add_targets.resource_uri` 覆盖配置,再使用 `server.user_config_defaults.add_targets.resource_uri`。两者都没有配置时,保持旧的目标解析行为。
- 资源目标可以使用公共 `viking://resources/...`、当前用户短写 `viking://user/resources/...`、显式用户 `viking://user/{user_id}/resources/...`,或 peer 级 `viking://user/{user_id}/peers/{peer_id}/resources/...`。当前用户短写会按请求身份 canonicalize。
- `user_id` 和 `peer_id` 路径片段必须是安全的单段标识,例如 `alice` 或 `web-visitor-alice`。包含路径分隔符、`.`、`..`、`:` 或 `+` 的值会被拒绝。
- `path` 和 `temp_file_id` 不能同时指定,上传本地文件需要先通过 [temp_upload](#temp_upload) 上传获取 `temp_file_id`,在 SDK 和 CLI 中已经封装好。
@@ -616,13 +617,16 @@ cancel_watch(to_uri="viking://resources/guide.md") # 按 URI 幂等删除
|------|------|------|--------|------|
| data | Any | 否 | - | 内联技能内容或结构化数据。与 `temp_file_id` 二选一 |
| temp_file_id | string | 否 | - | 临时上传文件 ID(通过 [temp_upload](#temp_upload) 获取)。与 `data` 二选一 |
+| target_uri | string | 否 | - | 技能添加根目录覆盖值。显式值优先于用户默认值和部署默认值 |
| wait | bool | 否 | False | 是否等待技能处理完成 |
| timeout | float | 否 | None | 超时时间(秒),仅 `wait=true` 时生效 |
| telemetry | TelemetryRequest | 否 | False | 是否返回遥测数据 |
-技能始终安装到当前用户的 skills 根。公共短写 `viking://user/skills` 可用于文件系统和检索操作,
-会解析为 `viking://user/{user_id}/skills`;`add_skill` 不接受 `to`、`parent`、`root_uri`
-或 peer-scoped skill 目标。
+未传 `target_uri` 时,服务端会先尝试使用当前用户的 `add_targets.skill_uri` 覆盖配置,
+再使用 `server.user_config_defaults.add_targets.skill_uri`。两者都没有配置时,保持旧行为,
+安装到当前用户的 skills 根。公共短写 `viking://user/skills` 会解析为
+`viking://user/{user_id}/skills`。v1 API 只允许 `viking://user/skills` 和
+`viking://agent/skills` 作为技能添加根目录。
#### 3. 使用示例
diff --git a/docs/zh/api/08-admin.md b/docs/zh/api/08-admin.md
index ddb08acdf..ea6c47c8b 100644
--- a/docs/zh/api/08-admin.md
+++ b/docs/zh/api/08-admin.md
@@ -68,7 +68,8 @@ Admin API 用于多租户环境下的账户和用户管理。包括工作区(a
2. 使用 API Key Manager 创建账户和初始管理员用户
3. 初始化账户级目录结构
4. 初始化管理员用户的个人目录
-5. 返回账户信息和用户密钥(非 trusted 模式下)
+5. 写入可选的初始管理员用户配置
+6. 返回账户信息和用户密钥(非 trusted 模式下)
**代码入口:**
- `openviking/server/routers/admin.py:create_account` - HTTP 路由
@@ -83,10 +84,13 @@ Admin API 用于多租户环境下的账户和用户管理。包括工作区(a
|------|------|------|--------|------|
| account_id | str | 是 | - | 工作区 ID |
| admin_user_id | str | 是 | - | 首个管理员用户 ID |
+| user_config | object | 否 | `null` | 首个管理员用户的初始配置。当前支持 `add_targets.resource_uri` 和 `add_targets.skill_uri` |
**说明:**
- 在 `trusted` 模式下,响应中不会包含 `user_key` 字段
- 不再支持 account 级 namespace 隔离配置。用户记忆使用 user-scoped namespace,一对多外部参与者通过 `peer_id` 表达。
+- `user_config.add_targets.resource_uri` 必须是可写资源目录 URI:`viking://resources` 或 `viking://resources/...`、`viking://user/resources` 或 `viking://user/resources/...`、`viking://user/{user_id}/resources` 或 `viking://user/{user_id}/resources/...`、`viking://user/{user_id}/peers/{peer_id}/resources` 或 `viking://user/{user_id}/peers/{peer_id}/resources/...`。
+- `user_config.add_targets.skill_uri` 只能是 `viking://user/skills` 或 `viking://agent/skills`。v1 不支持显式写成 `viking://user/{user_id}/skills`。
#### 3. 使用示例
@@ -160,6 +164,17 @@ result = client.admin_create_account("acme", "alice")
print(f"Account created: {result['account_id']}")
print(f"Admin user: {result['admin_user_id']}")
print(f"User key: {result.get('user_key', '(not exposed in trusted mode)')}")
+
+result = client.admin_create_account(
+ "acme-private",
+ "alice",
+ user_config={
+ "add_targets": {
+ "resource_uri": "viking://user/resources",
+ "skill_uri": "viking://user/skills",
+ }
+ },
+)
```
**Go SDK**
@@ -170,6 +185,15 @@ if err != nil {
return err
}
fmt.Println(result["account_id"])
+
+result, err = client.AdminCreateAccountWithOptions(ctx, "acme-private", "alice", &openviking.AdminCreateAccountOptions{
+ UserConfig: map[string]any{
+ "add_targets": map[string]any{
+ "resource_uri": "viking://user/resources",
+ "skill_uri": "viking://user/skills",
+ },
+ },
+})
```
**CLI**
@@ -177,6 +201,9 @@ fmt.Println(result["account_id"])
```bash
# 需要 ROOT 权限,使用 --sudo
ov --sudo admin create-account acme --admin alice
+
+ov --sudo admin create-account acme-private --admin alice \
+ --user-config-json '{"add_targets":{"resource_uri":"viking://user/resources","skill_uri":"viking://user/skills"}}'
```
**响应示例**
@@ -368,7 +395,8 @@ ov --sudo admin delete-account acme
1. 验证请求者具有 ROOT 权限,或为本账户的 ADMIN
2. 调用 API Key Manager 注册新用户
3. 初始化新用户的个人目录
-4. 返回用户信息和用户密钥(非 trusted 模式下)
+4. 写入可选的初始用户配置
+5. 返回用户信息和用户密钥(非 trusted 模式下)
**代码入口:**
- `openviking/server/routers/admin.py:register_user` - HTTP 路由
@@ -384,11 +412,14 @@ ov --sudo admin delete-account acme
| account_id | str | 是 | - | 工作区 ID |
| user_id | str | 是 | - | 用户 ID |
| role | str | 否 | "user" | 要分配的角色。`ROOT` 和同 account 的 `ADMIN` 可直接注册 `"user"` 或 `"admin"`。`"root"` 必须通过专门的改角色接口分配。 |
+| user_config | object | 否 | `null` | 新用户的初始配置。当前支持 `add_targets.resource_uri` 和 `add_targets.skill_uri` |
**说明:**
- 在 `trusted` 模式下,响应中不会包含 `user_key` 字段
- ADMIN 只能在自己所属的 account 中注册用户
- 无法通过用户注册接口直接创建 `"root"` 角色
+- `user_config.add_targets.resource_uri` 必须是可写资源目录 URI:`viking://resources` 或 `viking://resources/...`、`viking://user/resources` 或 `viking://user/resources/...`、`viking://user/{user_id}/resources` 或 `viking://user/{user_id}/resources/...`、`viking://user/{user_id}/peers/{peer_id}/resources` 或 `viking://user/{user_id}/peers/{peer_id}/resources/...`。
+- `user_config.add_targets.skill_uri` 只能是 `viking://user/skills` 或 `viking://agent/skills`。v1 不支持显式写成 `viking://user/{user_id}/skills`。
#### 3. 使用示例
@@ -419,6 +450,13 @@ client.initialize()
result = client.admin_register_user("acme", "bob", role="user")
print(f"User registered: {result['user_id']}")
print(f"User key: {result.get('user_key', '(not exposed in trusted mode)')}")
+
+result = client.admin_register_user(
+ "acme",
+ "bob-private",
+ role="user",
+ user_config={"add_targets": {"resource_uri": "viking://user/resources/project-a"}},
+)
```
**Go SDK**
@@ -429,6 +467,12 @@ if err != nil {
return err
}
fmt.Println(result["user_id"])
+
+result, err = client.AdminRegisterUserWithOptions(ctx, "acme", "bob-private", "user", &openviking.AdminRegisterUserOptions{
+ UserConfig: map[string]any{
+ "add_targets": map[string]any{"resource_uri": "viking://user/resources/project-a"},
+ },
+})
```
**CLI**
@@ -439,6 +483,9 @@ fmt.Println(result["user_id"])
ov admin register-user acme bob --role user
# 如果使用 root_api_key(--sudo):
ov --sudo admin register-user acme bob --role user
+
+ov admin register-user acme bob-private --role user \
+ --user-config-json '{"add_targets":{"resource_uri":"viking://user/resources/project-a"}}'
```
**响应示例**
@@ -923,6 +970,45 @@ ov --sudo admin migrate --cleanup --output json
---
+### 用户添加位置设置
+
+个人添加默认值作为用户配置存储在
+`viking://user/{user_id}/settings/user_config.json`。它只影响没有显式传目标的添加请求:
+
+1. `add_resource`:显式 `to` / `parent` 优先,然后是用户
+ `add_targets.resource_uri`,再是
+ `server.user_config_defaults.add_targets.resource_uri`,最后保持旧行为。
+2. `add_skill`:显式 `target_uri` 优先,然后是用户
+ `add_targets.skill_uri`,再是
+ `server.user_config_defaults.add_targets.skill_uri`,最后保持旧行为。
+
+#### HTTP API
+
+```
+GET /api/v1/user-settings/add-locations
+PATCH /api/v1/user-settings/add-locations
+DELETE /api/v1/user-settings/add-locations
+```
+
+`PATCH` 直接接收 add-target 字段。传 `null` 会清除单个字段;删除设置会清除整个个人覆盖配置。
+
+```bash
+curl -X PATCH http://localhost:1933/api/v1/user-settings/add-locations \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: <user-key>" \
+ -d '{"resource_uri": "viking://user/resources/project-a"}'
+```
+
+`resource_uri` 必须是可写资源目录 URI:`viking://resources` 或
+`viking://resources/...`、`viking://user/resources` 或
+`viking://user/resources/...`、`viking://user/{user_id}/resources` 或
+`viking://user/{user_id}/resources/...`、`viking://user/{user_id}/peers/{peer_id}/resources`
+或 `viking://user/{user_id}/peers/{peer_id}/resources/...`。`skill_uri` 只能是
+`viking://user/skills` 或 `viking://agent/skills`;v1 不支持显式写成
+`viking://user/{user_id}/skills`。配置值非法时会直接报错,不会静默回退到其它目标。
+
+---
+
## 完整示例
### 典型管理流程
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index 8734418f3..ac8d3c991 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -1371,6 +1371,12 @@ openviking add-resource ./docs --exclude "*.tmp"
"default_mode": "local",
"shared_max_size_bytes": 536870912,
"shared_prefix": "viking://upload"
+ },
+ "user_config_defaults": {
+ "add_targets": {
+ "resource_uri": "viking://user/resources",
+ "skill_uri": "viking://user/skills"
+ }
}
}
}
@@ -1389,11 +1395,20 @@ openviking add-resource ./docs --exclude "*.tmp"
| `temp_upload.default_mode` | str | `POST /api/v1/resources/temp_upload` 的服务端默认模式(客户端未显式传 `upload_mode` 时使用):`"local"`(仅当前实例本地磁盘,单机默认行为)或 `"shared"`(分布式共享存储,多副本部署可跨实例消费)。 | `"local"` |
| `temp_upload.shared_max_size_bytes` | int | `shared` 模式下接受的最大文件大小(字节)。超过此阈值的请求会在写入对象存储之前被拒绝。 | `536870912`(512 MiB) |
| `temp_upload.shared_prefix` | str | 分配 shared `temp_file_id` 对象时使用的 URI 前缀。 | `"viking://upload"` |
+| `user_config_defaults.add_targets.resource_uri` | str | `add_resource` 未传 `to` 和 `parent` 时使用的部署级默认资源添加目录。`viking://user/...` 会按请求用户解析。 | `null` |
+| `user_config_defaults.add_targets.skill_uri` | str | `add_skill` 未传 `target_uri` 时使用的部署级默认技能添加根目录。仅允许 `viking://user/skills` 和 `viking://agent/skills`。 | `null` |
`api_key` 模式使用 API Key 认证,也是默认模式;`trusted` 模式信任上游网关或受信调用方注入的 `X-OpenViking-Account` / `X-OpenViking-User` 请求头。
在 `api_key` 模式下配置 `root_api_key` 后,服务端启用正式多租户认证,并通过 Admin API 创建工作区和用户 key。在 `trusted` 模式下,普通请求不需要先注册 user key;每个请求都会根据注入的身份头解析成 `USER`。只有在 `auth_mode = "api_key"` 且未配置 `root_api_key` 时,服务端才会进入开发模式。
+`user_config_defaults` 用于给没有个人覆盖配置的新老用户提供默认用户配置。添加操作中,显式请求目标仍然优先:`add_resource.to` / `add_resource.parent` 优先于用户默认值,`add_skill.target_uri` 优先于用户默认值。个人覆盖配置存储在 `viking://user/{user_id}/settings/user_config.json`。
+
+支持的 add target URI:
+
+- `resource_uri` 作为 `add_resource` 的默认父目录使用,等价于 `parent=<uri>, create_parent=true`。它必须是当前请求用户可写的 resource 目录 URI,支持 `viking://resources` 或 `viking://resources/...`、`viking://user/resources` 或 `viking://user/resources/...`、`viking://user/{user_id}/resources` 或 `viking://user/{user_id}/resources/...`、`viking://user/{user_id}/peers/{peer_id}/resources` 或 `viking://user/{user_id}/peers/{peer_id}/resources/...`。`viking://user/...` 短写会按请求用户解析。
+- `skill_uri` 作为 `add_skill` 的默认目标根目录使用。v1 只允许 `viking://user/skills` 和 `viking://agent/skills`;不支持显式写成 `viking://user/{user_id}/skills`。
+
启动方式和部署详情见 [服务部署](./03-deployment.md),认证详情见 [认证](./04-authentication.md)。
## encryption 段
diff --git a/openviking/server/app.py b/openviking/server/app.py
index 41f9eb446..17f7b6e1f 100644
--- a/openviking/server/app.py
+++ b/openviking/server/app.py
@@ -48,6 +48,7 @@ from openviking.server.routers import (
stats_router,
system_router,
tasks_router,
+ user_settings_router,
watches_router,
webdav_router,
)
@@ -539,6 +540,7 @@ def create_app(
app.include_router(observer_router)
app.include_router(metrics_router)
app.include_router(tasks_router)
+ app.include_router(user_settings_router)
app.include_router(watches_router)
app.include_router(webdav_router)
app.include_router(bot_router, prefix="/bot/v1")
diff --git a/openviking/server/config.py b/openviking/server/config.py
index bc0e7393b..dcbb95c77 100644
--- a/openviking/server/config.py
+++ b/openviking/server/config.py
@@ -5,7 +5,7 @@
import sys
from typing import Dict, List, Literal, Optional
-from pydantic import BaseModel, Field, ValidationError
+from pydantic import BaseModel, Field, ValidationError, field_validator
# Import auth plugin registry for config validation
from openviking.server.auth.registry import get_registry
@@ -26,6 +26,69 @@ from openviking_cli.utils.config.consts import (
logger = get_logger(__name__)
+def _normalize_config_uri(value: Optional[str], field_name: str) -> Optional[str]:
+ if value is None:
+ return None
+ if not isinstance(value, str):
+ raise ValueError(f"{field_name} must be a string")
+ uri = value.strip().rstrip("/")
+ if not uri:
+ raise ValueError(f"{field_name} must not be empty")
+ return uri
+
+
+class AddTargetsConfig(BaseModel):
+ """Add targets for resource and skill writes."""
+
+ resource_uri: Optional[str] = None
+ skill_uri: Optional[str] = None
+
+ model_config = {"extra": "forbid"}
+
+ @field_validator("resource_uri")
+ @classmethod
+ def validate_resource_uri(cls, value: Optional[str]) -> Optional[str]:
+ uri = _normalize_config_uri(value, "resource_uri")
+ if uri is None:
+ return None
+ from openviking.core.namespace import classify_uri, uri_parts
+ from openviking.core.uri_validation import validate_viking_uri
+ from openviking_cli.utils.uri import VikingURI
+
+ validate_viking_uri(uri, field_name="resource_uri")
+ normalized = VikingURI.normalize(uri).rstrip("/")
+ parts = uri_parts(normalized)
+ classification = classify_uri(normalized)
+ if parts[:1] == ["resources"] or (
+ parts[:1] == ["user"]
+ and classification.context_type == "resource"
+ and classification.content_index is not None
+ ):
+ return normalized
+ raise ValueError("resource_uri must be a resource directory URI")
+
+ @field_validator("skill_uri")
+ @classmethod
+ def validate_skill_uri(cls, value: Optional[str]) -> Optional[str]:
+ uri = _normalize_config_uri(value, "skill_uri")
+ if uri is None:
+ return None
+ from openviking_cli.utils.uri import VikingURI
+
+ normalized = VikingURI.normalize(uri).rstrip("/")
+ if normalized in {"viking://user/skills", "viking://agent/skills"}:
+ return normalized
+ raise ValueError("skill_uri must be viking://user/skills or viking://agent/skills")
+
+
+class UserConfig(BaseModel):
+ """User configuration values that can be defaulted or initialized."""
+
+ add_targets: AddTargetsConfig = Field(default_factory=AddTargetsConfig)
+
+ model_config = {"extra": "forbid"}
+
+
class MetricsAccountDimensionConfig(BaseModel):
"""Account-dimension configuration for metrics label injection."""
@@ -179,6 +242,7 @@ class ServerConfig(BaseModel):
public_base_url: Optional[str] = None
upload_signed_ttl_seconds: int = 600
temp_upload: TempUploadConfig = Field(default_factory=TempUploadConfig)
+ user_config_defaults: UserConfig = Field(default_factory=UserConfig)
tool_output_externalization: ToolOutputExternalizationConfig = Field(
default_factory=ToolOutputExternalizationConfig
)
diff --git a/openviking/server/routers/__init__.py b/openviking/server/routers/__init__.py
index 1fb22653a..447a532c1 100644
--- a/openviking/server/routers/__init__.py
+++ b/openviking/server/routers/__init__.py
@@ -22,6 +22,7 @@ from openviking.server.routers.snapshot import router as snapshot_router
from openviking.server.routers.stats import router as stats_router
from openviking.server.routers.system import router as system_router
from openviking.server.routers.tasks import router as tasks_router
+from openviking.server.routers.user_settings import router as user_settings_router
from openviking.server.routers.watches import router as watches_router
from openviking.server.routers.webdav import router as webdav_router
@@ -46,6 +47,7 @@ __all__ = [
"metrics_router",
"observer_router",
"tasks_router",
+ "user_settings_router",
"watches_router",
"webdav_router",
]
diff --git a/openviking/server/routers/admin.py b/openviking/server/routers/admin.py
index 646139c1a..ce197c30e 100644
--- a/openviking/server/routers/admin.py
+++ b/openviking/server/routers/admin.py
@@ -13,10 +13,11 @@ from openviking.server.auth import (
require_auth_root,
require_auth_root_or_admin,
)
-from openviking.server.config import ServerConfig
+from openviking.server.config import ServerConfig, UserConfig
from openviking.server.dependencies import get_service
from openviking.server.identity import RequestContext, Role
from openviking.server.models import Response
+from openviking.server.user_config import validate_add_targets, write_user_config
from openviking.service.legacy_migration import LegacyDataMigration
from openviking.service.task_store import (
SYSTEM_TASK_ACCOUNT_ID,
@@ -42,11 +43,13 @@ router = APIRouter(prefix="/api/v1/admin", tags=["admin"])
class CreateAccountRequest(BaseModel):
account_id: str
admin_user_id: str
+ user_config: UserConfig | None = None
class RegisterUserRequest(BaseModel):
user_id: str
role: str = "user"
+ user_config: UserConfig | None = None
class SetRoleRequest(BaseModel):
@@ -75,6 +78,38 @@ def _check_account_access(ctx: RequestContext, account_id: str) -> None:
raise PermissionDeniedError(f"ADMIN can only manage account: {ctx.account_id}")
+def _has_add_targets(user_config: UserConfig | None) -> bool:
+ return bool(
+ user_config and (user_config.add_targets.resource_uri or user_config.add_targets.skill_uri)
+ )
+
+
+def _validate_initial_user_config(
+ service,
+ user_ctx: RequestContext,
+ user_config: UserConfig | None,
+) -> None:
+ if not _has_add_targets(user_config):
+ return
+ if service.viking_fs is None:
+ raise FailedPreconditionError("OpenViking service is not initialized.")
+ validate_add_targets(
+ user_config.add_targets,
+ ctx=user_ctx,
+ viking_fs=service.viking_fs,
+ )
+
+
+async def _write_initial_user_config(
+ service,
+ user_ctx: RequestContext,
+ user_config: UserConfig | None,
+) -> None:
+ if not _has_add_targets(user_config):
+ return
+ await write_user_config(service.viking_fs, user_ctx, user_config)
+
+
def _validate_register_user_role(ctx: RequestContext, role: str) -> Role:
"""Validate which roles may be minted through register_user.
@@ -125,18 +160,20 @@ async def create_account(
ctx: RequestContext = Depends(get_request_context),
):
"""Create a new account (workspace) with its first admin user."""
- manager = _get_api_key_manager(request)
- user_key = await manager.create_account(
- body.account_id,
- body.admin_user_id,
- )
service = get_service()
account_ctx = RequestContext(
user=UserIdentifier(body.account_id, body.admin_user_id),
role=Role.ADMIN,
)
+ _validate_initial_user_config(service, account_ctx, body.user_config)
+ manager = _get_api_key_manager(request)
+ user_key = await manager.create_account(
+ body.account_id,
+ body.admin_user_id,
+ )
await service.initialize_account_directories(account_ctx)
await service.initialize_user_directories(account_ctx)
+ await _write_initial_user_config(service, account_ctx, body.user_config)
result = {
"account_id": body.account_id,
"admin_user_id": body.admin_user_id,
@@ -264,14 +301,16 @@ async def register_user(
"""Register a new user in an account."""
_check_account_access(ctx, account_id)
resolved_role = _validate_register_user_role(ctx, body.role)
- manager = _get_api_key_manager(request)
- user_key = await manager.register_user(account_id, body.user_id, str(resolved_role))
service = get_service()
user_ctx = RequestContext(
user=UserIdentifier(account_id, body.user_id),
- role=Role.USER,
+ role=resolved_role,
)
+ _validate_initial_user_config(service, user_ctx, body.user_config)
+ manager = _get_api_key_manager(request)
+ user_key = await manager.register_user(account_id, body.user_id, str(resolved_role))
await service.initialize_user_directories(user_ctx)
+ await _write_initial_user_config(service, user_ctx, body.user_config)
result = {
"account_id": account_id,
"user_id": body.user_id,
diff --git a/openviking/server/routers/user_settings.py b/openviking/server/routers/user_settings.py
new file mode 100644
index 000000000..d76bbc948
--- /dev/null
+++ b/openviking/server/routers/user_settings.py
@@ -0,0 +1,117 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Per-user server settings."""
+
+from typing import Any, Optional
+
+from fastapi import APIRouter, Depends, Request
+from pydantic import BaseModel, ConfigDict
+
+from openviking.server.auth import get_request_context
+from openviking.server.config import AddTargetsConfig
+from openviking.server.dependencies import get_service
+from openviking.server.identity import RequestContext
+from openviking.server.models import Response
+from openviking.server.user_config import (
+ ResolvedAddTargets,
+ delete_user_add_targets,
+ effective_resource_add_target,
+ effective_skill_add_target,
+ public_add_targets,
+ read_user_add_targets,
+ write_user_add_targets,
+)
+from openviking_cli.exceptions import InvalidArgumentError, NotInitializedError
+
+router = APIRouter(prefix="/api/v1/user-settings", tags=["user-settings"])
+
+
+class PatchAddLocationsRequest(BaseModel):
+ model_config = ConfigDict(extra="forbid")
+
+ resource_uri: Optional[str] = None
+ skill_uri: Optional[str] = None
+
+
+def _viking_fs():
+ viking_fs = get_service().viking_fs
+ if viking_fs is None:
+ raise NotInitializedError("VikingFS")
+ return viking_fs
+
+
+async def _response(request: Request, ctx: RequestContext) -> dict[str, Any]:
+ viking_fs = _viking_fs()
+ override = await read_user_add_targets(viking_fs, ctx)
+ effective = ResolvedAddTargets(
+ resource_uri=await effective_resource_add_target(
+ viking_fs=viking_fs,
+ ctx=ctx,
+ server_config=request.app.state.config,
+ ),
+ skill_uri=await effective_skill_add_target(
+ viking_fs=viking_fs,
+ ctx=ctx,
+ server_config=request.app.state.config,
+ ),
+ )
+ return {
+ "override": public_add_targets(override),
+ "effective": {
+ "resource_uri": effective.resource_uri,
+ "skill_uri": effective.skill_uri,
+ },
+ }
+
+
[email protected]("/add-locations")
+async def get_add_locations(
+ request: Request,
+ _ctx: RequestContext = Depends(get_request_context),
+):
+ return Response(status="ok", result=await _response(request, _ctx)).model_dump(
+ exclude_none=True
+ )
+
+
[email protected]("/add-locations")
+async def patch_add_locations(
+ request: Request,
+ body: PatchAddLocationsRequest,
+ _ctx: RequestContext = Depends(get_request_context),
+):
+ viking_fs = _viking_fs()
+ current = await read_user_add_targets(viking_fs, _ctx)
+ data = current.model_dump(exclude_none=True)
+ for field in body.model_fields_set:
+ value = getattr(body, field)
+ if value is None:
+ data.pop(field, None)
+ else:
+ data[field] = value
+ if data:
+ try:
+ settings = AddTargetsConfig.model_validate(data)
+ except Exception as exc:
+ raise InvalidArgumentError(str(exc)) from exc
+ await write_user_add_targets(
+ viking_fs,
+ _ctx,
+ settings,
+ )
+ else:
+ await delete_user_add_targets(viking_fs, _ctx)
+ return Response(status="ok", result=await _response(request, _ctx)).model_dump(
+ exclude_none=True
+ )
+
+
[email protected]("/add-locations")
+async def delete_add_locations(
+ request: Request,
+ _ctx: RequestContext = Depends(get_request_context),
+):
+ await delete_user_add_targets(_viking_fs(), _ctx)
+ return Response(status="ok", result=await _response(request, _ctx)).model_dump(
+ exclude_none=True
+ )
diff --git a/openviking/server/user_config.py b/openviking/server/user_config.py
new file mode 100644
index 000000000..e384c9aff
--- /dev/null
+++ b/openviking/server/user_config.py
@@ -0,0 +1,204 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Server-side user configuration helpers."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Optional
+
+from openviking.core.namespace import canonical_user_root
+from openviking.core.uri_validation import validate_content_target_uri
+from openviking.server.config import AddTargetsConfig, UserConfig
+from openviking_cli.exceptions import InvalidArgumentError, NotFoundError
+
+if TYPE_CHECKING:
+ from openviking.server.config import ServerConfig
+ from openviking.server.identity import RequestContext
+ from openviking.storage.viking_fs import VikingFS
+
+
+@dataclass(frozen=True)
+class ResolvedAddTargets:
+ resource_uri: Optional[str] = None
+ skill_uri: Optional[str] = None
+
+
+def user_config_uri(ctx: RequestContext) -> str:
+ return f"{canonical_user_root(ctx)}/settings/user_config.json"
+
+
+def _user_config_from_payload(payload: Any) -> UserConfig:
+ if not isinstance(payload, dict):
+ raise InvalidArgumentError("user config must be an object")
+ try:
+ return UserConfig.model_validate(payload)
+ except Exception as exc:
+ raise InvalidArgumentError(str(exc)) from exc
+
+
+def _ensure_mutable(viking_fs: VikingFS, uri: str, ctx: RequestContext) -> None:
+ ensure = getattr(viking_fs, "_ensure_mutable_access", None)
+ if callable(ensure):
+ ensure(uri, ctx)
+
+
+def validate_resource_add_target(
+ uri: str,
+ *,
+ ctx: RequestContext,
+ viking_fs: VikingFS,
+) -> str:
+ resolved = validate_content_target_uri(uri, ctx, kind="resource", field_name="resource_uri")
+ _ensure_mutable(viking_fs, resolved, ctx)
+ return resolved
+
+
+def validate_skill_add_target(
+ uri: str,
+ *,
+ ctx: RequestContext,
+ viking_fs: VikingFS,
+) -> str:
+ normalized = uri.strip().rstrip("/")
+ if normalized == "viking://user/skills":
+ resolved = f"{canonical_user_root(ctx)}/skills"
+ elif normalized == "viking://agent/skills":
+ resolved = "viking://agent/skills"
+ else:
+ raise InvalidArgumentError(
+ "skill_uri must be viking://user/skills or viking://agent/skills",
+ details={"field": "skill_uri"},
+ )
+ _ensure_mutable(viking_fs, resolved, ctx)
+ return resolved
+
+
+def validate_add_targets(
+ settings: AddTargetsConfig,
+ *,
+ ctx: RequestContext,
+ viking_fs: VikingFS,
+) -> ResolvedAddTargets:
+ return ResolvedAddTargets(
+ resource_uri=(
+ validate_resource_add_target(settings.resource_uri, ctx=ctx, viking_fs=viking_fs)
+ if settings.resource_uri
+ else None
+ ),
+ skill_uri=(
+ validate_skill_add_target(settings.skill_uri, ctx=ctx, viking_fs=viking_fs)
+ if settings.skill_uri
+ else None
+ ),
+ )
+
+
+async def read_user_config(
+ viking_fs: VikingFS,
+ ctx: RequestContext,
+) -> UserConfig:
+ read_file = getattr(viking_fs, "read_file", None)
+ if not callable(read_file):
+ return UserConfig()
+ uri = user_config_uri(ctx)
+ try:
+ raw = await read_file(uri, ctx=ctx)
+ except (NotFoundError, FileNotFoundError):
+ return UserConfig()
+ try:
+ payload = json.loads(raw)
+ except json.JSONDecodeError as exc:
+ raise InvalidArgumentError(f"Invalid user config JSON: {exc}") from exc
+ return _user_config_from_payload(payload)
+
+
+async def write_user_config(
+ viking_fs: VikingFS,
+ ctx: RequestContext,
+ user_config: UserConfig,
+) -> ResolvedAddTargets:
+ runtime = validate_add_targets(user_config.add_targets, ctx=ctx, viking_fs=viking_fs)
+ uri = user_config_uri(ctx)
+ await viking_fs.write_file(
+ uri,
+ json.dumps(user_config.model_dump(exclude_none=True), ensure_ascii=False, sort_keys=True),
+ ctx=ctx,
+ )
+ return runtime
+
+
+async def delete_user_config(viking_fs: VikingFS, ctx: RequestContext) -> None:
+ try:
+ await viking_fs.rm(user_config_uri(ctx), ctx=ctx)
+ except (NotFoundError, FileNotFoundError):
+ return
+
+
+async def read_user_add_targets(
+ viking_fs: VikingFS,
+ ctx: RequestContext,
+) -> AddTargetsConfig:
+ return (await read_user_config(viking_fs, ctx)).add_targets
+
+
+async def write_user_add_targets(
+ viking_fs: VikingFS,
+ ctx: RequestContext,
+ settings: AddTargetsConfig,
+) -> ResolvedAddTargets:
+ user_config = await read_user_config(viking_fs, ctx)
+ user_config.add_targets = settings
+ return await write_user_config(viking_fs, ctx, user_config)
+
+
+async def delete_user_add_targets(viking_fs: VikingFS, ctx: RequestContext) -> None:
+ await delete_user_config(viking_fs, ctx)
+
+
+async def effective_resource_add_target(
+ *,
+ viking_fs: VikingFS,
+ ctx: RequestContext,
+ server_config: Optional[ServerConfig],
+) -> Optional[str]:
+ user_settings = await read_user_add_targets(viking_fs, ctx)
+ if user_settings.resource_uri:
+ return validate_resource_add_target(
+ user_settings.resource_uri, ctx=ctx, viking_fs=viking_fs
+ )
+ configured = getattr(
+ getattr(getattr(server_config, "user_config_defaults", None), "add_targets", None),
+ "resource_uri",
+ None,
+ )
+ if configured:
+ return validate_resource_add_target(configured, ctx=ctx, viking_fs=viking_fs)
+ return None
+
+
+async def effective_skill_add_target(
+ *,
+ viking_fs: VikingFS,
+ ctx: RequestContext,
+ server_config: Optional[ServerConfig],
+) -> Optional[str]:
+ user_settings = await read_user_add_targets(viking_fs, ctx)
+ if user_settings.skill_uri:
+ return validate_skill_add_target(user_settings.skill_uri, ctx=ctx, viking_fs=viking_fs)
+ configured = getattr(
+ getattr(getattr(server_config, "user_config_defaults", None), "add_targets", None),
+ "skill_uri",
+ None,
+ )
+ if configured:
+ return validate_skill_add_target(configured, ctx=ctx, viking_fs=viking_fs)
+ return None
+
+
+def public_add_targets(settings: AddTargetsConfig) -> dict[str, Optional[str]]:
+ return {
+ "resource_uri": settings.resource_uri,
+ "skill_uri": settings.skill_uri,
+ }
diff --git a/openviking/service/resource_service.py b/openviking/service/resource_service.py
index c06d298a9..1dba7ba6f 100644
--- a/openviking/service/resource_service.py
+++ b/openviking/service/resource_service.py
@@ -29,6 +29,10 @@ from openviking.server.local_input_guard import (
is_remote_resource_source,
require_remote_resource_source,
)
+from openviking.server.user_config import (
+ effective_resource_add_target,
+ effective_skill_add_target,
+)
from openviking.storage import VikingDBManager
from openviking.storage.queuefs import get_queue_manager
from openviking.storage.transaction import NO_LOCK, LockLease
@@ -564,6 +568,17 @@ class ResourceService:
self._ensure_initialized()
normalized_args = self._normalize_add_resource_args(args, watch_interval=watch_interval)
kwargs.update(normalized_args.processor_kwargs)
+ if not to and not parent:
+ from openviking.server.dependencies import get_server_config
+
+ default_parent = await effective_resource_add_target(
+ viking_fs=self._viking_fs,
+ ctx=ctx,
+ server_config=get_server_config(),
+ )
+ if default_parent:
+ parent = default_parent
+ kwargs["create_parent"] = True
if not wait and is_git_repo_url(path):
return await self.enqueue_git_add_resource(
path=path,
@@ -1051,6 +1066,14 @@ class ResourceService:
Processing result
"""
self._ensure_initialized()
+ if not target_uri:
+ from openviking.server.dependencies import get_server_config
+
+ target_uri = await effective_skill_add_target(
+ viking_fs=self._viking_fs,
+ ctx=ctx,
+ server_config=get_server_config(),
+ )
telemetry_id = get_current_telemetry().telemetry_id
request_wait_tracker = get_request_wait_tracker()
monitor_started = False
diff --git a/sdk/go/README.md b/sdk/go/README.md
index ad6a30b58..2284c7eb8 100644
--- a/sdk/go/README.md
+++ b/sdk/go/README.md
@@ -116,7 +116,7 @@ Implemented:
| Sessions and tasks | `CreateSession`, `ListSessions`, `GetSession`, `SessionExists`, `GetSessionContext`, `GetSessionArchive`, `DeleteSession`, `AddMessage`, `BatchAddMessages`, `CommitSession`, `GetTask`, `ListTasks` |
| Packs | `ExportOVPack`, `BackupOVPack`, `ImportOVPack`, `RestoreOVPack` |
| System and observer | `Health`, `CheckConsistency`, `GetStatus`, `IsHealthy`, `QueueStatus`, `VikingDBStatus`, `ModelsStatus` |
-| Admin | `AdminCreateAccount`, `AdminListAccounts`, `AdminDeleteAccount`, `AdminRegisterUser`, `AdminListUsers`, `AdminRemoveUser`, `AdminSetRole`, `AdminRegenerateKey`, `AdminMigrate` |
+| Admin | `AdminCreateAccount`, `AdminCreateAccountWithOptions`, `AdminListAccounts`, `AdminDeleteAccount`, `AdminRegisterUser`, `AdminRegisterUserWithOptions`, `AdminListUsers`, `AdminRemoveUser`, `AdminSetRole`, `AdminRegenerateKey`, `AdminMigrate` |
Not implemented in Go SDK v1:
@@ -128,6 +128,23 @@ Not implemented in Go SDK v1:
| Metrics endpoint | Prometheus text scrape endpoint, not a JSON SDK API. |
| Console/debug/backend-sync/session tool-result endpoints | Operational or server-only endpoints outside Python HTTP client parity. |
+## Admin User Config
+
+Use the options variants when creating users with initial server-side user
+config. Ordinary add calls do not need SDK defaults; omit `To` / `TargetURI`
+and let the server resolve user and deployment defaults.
+
+```go
+_, err := client.AdminRegisterUserWithOptions(ctx, "acme", "alice", "user", &openviking.AdminRegisterUserOptions{
+ UserConfig: map[string]any{
+ "add_targets": map[string]any{
+ "resource_uri": "viking://user/resources/project-a",
+ "skill_uri": "viking://user/skills",
+ },
+ },
+})
+```
+
## Files, Directories, and Packs
`AddResource` and `AddSkill` accept local files and directories. Directory
diff --git a/sdk/go/README_CN.md b/sdk/go/README_CN.md
index 97eedd754..4bbb17c90 100644
--- a/sdk/go/README_CN.md
+++ b/sdk/go/README_CN.md
@@ -45,7 +45,7 @@ Go SDK 仅支持 HTTP 模式,不支持 Python embedded 模式,也不保留
| 会话和任务 | `CreateSession`, `ListSessions`, `GetSession`, `SessionExists`, `GetSessionContext`, `GetSessionArchive`, `DeleteSession`, `AddMessage`, `BatchAddMessages`, `CommitSession`, `GetTask`, `ListTasks` |
| OVPack | `ExportOVPack`, `BackupOVPack`, `ImportOVPack`, `RestoreOVPack` |
| 系统和 observer | `Health`, `CheckConsistency`, `GetStatus`, `IsHealthy`, `QueueStatus`, `VikingDBStatus`, `ModelsStatus` |
-| 管理接口 | `AdminCreateAccount`, `AdminListAccounts`, `AdminDeleteAccount`, `AdminRegisterUser`, `AdminListUsers`, `AdminRemoveUser`, `AdminSetRole`, `AdminRegenerateKey`, `AdminMigrate` |
+| 管理接口 | `AdminCreateAccount`, `AdminCreateAccountWithOptions`, `AdminListAccounts`, `AdminDeleteAccount`, `AdminRegisterUser`, `AdminRegisterUserWithOptions`, `AdminListUsers`, `AdminRemoveUser`, `AdminSetRole`, `AdminRegenerateKey`, `AdminMigrate` |
## 暂未实现接口
@@ -59,6 +59,21 @@ Go SDK v1 的边界是对齐当前 Python HTTP client,不覆盖所有 server
| Metrics endpoint | Prometheus 文本抓取端点,不是标准 JSON SDK API。 |
| Console/debug/backend-sync/session tool-result 等端点 | 属于运维或 server-only 能力,未纳入 Python HTTP client parity。 |
+## 管理用户配置
+
+创建用户时如需写入初始服务端用户配置,使用 options 版本。普通 add 调用不需要 SDK 侧默认值;省略 `To` / `TargetURI`,让服务端解析用户和部署默认值。
+
+```go
+_, err := client.AdminRegisterUserWithOptions(ctx, "acme", "alice", "user", &openviking.AdminRegisterUserOptions{
+ UserConfig: map[string]any{
+ "add_targets": map[string]any{
+ "resource_uri": "viking://user/resources/project-a",
+ "skill_uri": "viking://user/skills",
+ },
+ },
+})
+```
+
## 技能和 Watch 示例
```go
diff --git a/sdk/go/admin.go b/sdk/go/admin.go
index 079630d17..450b171cb 100644
--- a/sdk/go/admin.go
+++ b/sdk/go/admin.go
@@ -8,11 +8,20 @@ import (
// AdminCreateAccount creates an account with its first admin user.
func (c *Client) AdminCreateAccount(ctx context.Context, accountID, adminUserID string) (map[string]any, error) {
- var result map[string]any
- err := c.doJSON(ctx, http.MethodPost, "/api/v1/admin/accounts", nil, map[string]any{
+ return c.AdminCreateAccountWithOptions(ctx, accountID, adminUserID, nil)
+}
+
+// AdminCreateAccountWithOptions creates an account with its first admin user.
+func (c *Client) AdminCreateAccountWithOptions(ctx context.Context, accountID, adminUserID string, opts *AdminCreateAccountOptions) (map[string]any, error) {
+ payload := map[string]any{
"account_id": accountID,
"admin_user_id": adminUserID,
- }, &result)
+ }
+ if opts != nil && opts.UserConfig != nil {
+ payload["user_config"] = opts.UserConfig
+ }
+ var result map[string]any
+ err := c.doJSON(ctx, http.MethodPost, "/api/v1/admin/accounts", nil, payload, &result)
return result, err
}
@@ -32,14 +41,23 @@ func (c *Client) AdminDeleteAccount(ctx context.Context, accountID string) (map[
// AdminRegisterUser registers a user in an account.
func (c *Client) AdminRegisterUser(ctx context.Context, accountID, userID, role string) (map[string]any, error) {
+ return c.AdminRegisterUserWithOptions(ctx, accountID, userID, role, nil)
+}
+
+// AdminRegisterUserWithOptions registers a user in an account.
+func (c *Client) AdminRegisterUserWithOptions(ctx context.Context, accountID, userID, role string, opts *AdminRegisterUserOptions) (map[string]any, error) {
if role == "" {
role = "user"
}
- var result map[string]any
- err := c.doJSON(ctx, http.MethodPost, "/api/v1/admin/accounts/"+url.PathEscape(accountID)+"/users", nil, map[string]any{
+ payload := map[string]any{
"user_id": userID,
"role": role,
- }, &result)
+ }
+ if opts != nil && opts.UserConfig != nil {
+ payload["user_config"] = opts.UserConfig
+ }
+ var result map[string]any
+ err := c.doJSON(ctx, http.MethodPost, "/api/v1/admin/accounts/"+url.PathEscape(accountID)+"/users", nil, payload, &result)
return result, err
}
diff --git a/sdk/go/client_test.go b/sdk/go/client_test.go
index 0518e7940..b18d3f035 100644
--- a/sdk/go/client_test.go
+++ b/sdk/go/client_test.go
@@ -165,6 +165,42 @@ func TestFindOmitsSearchFiltersWhenUnset(t *testing.T) {
}
}
+func TestAdminCreatePathsAcceptInitialUserConfig(t *testing.T) {
+ var seen []map[string]any
+ client, closeServer := testClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.URL.Path != "/api/v1/admin/accounts" && r.URL.Path != "/api/v1/admin/accounts/acct/users" {
+ t.Fatalf("path = %s", r.URL.Path)
+ }
+ if r.Method != http.MethodPost {
+ t.Fatalf("method = %s", r.Method)
+ }
+ body := readJSONBody(t, r)
+ seen = append(seen, body)
+ writeOK(t, w, body)
+ }))
+ defer closeServer()
+
+ userConfig := map[string]any{
+ "add_targets": map[string]any{"resource_uri": "viking://user/resources/project-a"},
+ }
+ if _, err := client.AdminCreateAccountWithOptions(context.Background(), "acct", "admin", &AdminCreateAccountOptions{
+ UserConfig: userConfig,
+ }); err != nil {
+ t.Fatal(err)
+ }
+ if _, err := client.AdminRegisterUserWithOptions(context.Background(), "acct", "alice", "admin", &AdminRegisterUserOptions{
+ UserConfig: userConfig,
+ }); err != nil {
+ t.Fatal(err)
+ }
+ if got := seen[0]["user_config"].(map[string]any)["add_targets"].(map[string]any)["resource_uri"]; got != "viking://user/resources/project-a" {
+ t.Fatalf("user_config resource_uri = %#v", got)
+ }
+ if got := seen[1]["user_config"].(map[string]any)["add_targets"].(map[string]any)["resource_uri"]; got != "viking://user/resources/project-a" {
+ t.Fatalf("user_config resource_uri = %#v", got)
+ }
+}
+
func TestSearchSendsSessionAndSearchFilters(t *testing.T) {
client, closeServer := testClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path != "/api/v1/search/search" {
diff --git a/sdk/go/types.go b/sdk/go/types.go
index 9029b8c2b..1e3df518e 100644
--- a/sdk/go/types.go
+++ b/sdk/go/types.go
@@ -46,6 +46,16 @@ type AddSkillOptions struct {
Telemetry any
}
+// AdminCreateAccountOptions controls AdminCreateAccountWithOptions.
+type AdminCreateAccountOptions struct {
+ UserConfig map[string]any
+}
+
+// AdminRegisterUserOptions controls AdminRegisterUserWithOptions.
+type AdminRegisterUserOptions struct {
+ UserConfig map[string]any
+}
+
// ListSkillsOptions controls ListSkills.
type ListSkillsOptions struct {
NodeLimit int
diff --git a/sdk/python/README.md b/sdk/python/README.md
index 4344a999c..e99061d1c 100644
--- a/sdk/python/README.md
+++ b/sdk/python/README.md
@@ -208,8 +208,24 @@ result = root_client.admin_create_account(
admin_user_id="demo-admin",
)
print(result)
+
+root_client.admin_register_user(
+ account_id="demo-account",
+ user_id="alice",
+ role="user",
+ user_config={
+ "add_targets": {
+ "resource_uri": "viking://user/resources/project-a",
+ "skill_uri": "viking://user/skills",
+ }
+ },
+)
```
+`admin_create_account` also accepts `user_config` with the same shape.
+These fields initialize server-side user config; ordinary add calls still just
+omit `to` / `parent` / `target_uri` and let the server resolve defaults.
+
## Error Handling
The SDK maps server-side error codes to Python exceptions.
diff --git a/sdk/python/README_CN.md b/sdk/python/README_CN.md
index 3c84adac1..22e0543f8 100644
--- a/sdk/python/README_CN.md
+++ b/sdk/python/README_CN.md
@@ -208,8 +208,22 @@ result = root_client.admin_create_account(
admin_user_id="demo-admin",
)
print(result)
+
+root_client.admin_register_user(
+ account_id="demo-account",
+ user_id="alice",
+ role="user",
+ user_config={
+ "add_targets": {
+ "resource_uri": "viking://user/resources/project-a",
+ "skill_uri": "viking://user/skills",
+ }
+ },
+)
```
+`admin_create_account` 也接受同样结构的 `user_config`。这些字段用于初始化服务端用户配置;普通添加调用仍然只需省略 `to` / `parent` / `target_uri`,由服务端解析默认值。
+
## 错误处理
SDK 会把服务端错误码映射为 Python 异常。
diff --git a/sdk/python/openviking_sdk/client.py b/sdk/python/openviking_sdk/client.py
index f420d5711..f50cfd041 100644
--- a/sdk/python/openviking_sdk/client.py
+++ b/sdk/python/openviking_sdk/client.py
@@ -1223,10 +1223,18 @@ class AsyncHTTPClient:
response = await self._http.get("/api/v1/observer/system")
return self._handle_response(response)
- async def admin_create_account(self, account_id: str, admin_user_id: str) -> Dict[str, Any]:
+ async def admin_create_account(
+ self,
+ account_id: str,
+ admin_user_id: str,
+ user_config: Optional[Dict[str, Any]] = None,
+ ) -> Dict[str, Any]:
+ payload: Dict[str, Any] = {"account_id": account_id, "admin_user_id": admin_user_id}
+ if user_config is not None:
+ payload["user_config"] = user_config
response = await self._http.post(
"/api/v1/admin/accounts",
- json={"account_id": account_id, "admin_user_id": admin_user_id},
+ json=payload,
)
return self._handle_response(response)
@@ -1239,11 +1247,18 @@ class AsyncHTTPClient:
return self._handle_response(response)
async def admin_register_user(
- self, account_id: str, user_id: str, role: str = "user"
+ self,
+ account_id: str,
+ user_id: str,
+ role: str = "user",
+ user_config: Optional[Dict[str, Any]] = None,
) -> Dict[str, Any]:
+ payload: Dict[str, Any] = {"user_id": user_id, "role": role}
+ if user_config is not None:
+ payload["user_config"] = user_config
response = await self._http.post(
f"/api/v1/admin/accounts/{account_id}/users",
- json={"user_id": user_id, "role": role},
+ json=payload,
)
return self._handle_response(response)
@@ -1965,8 +1980,19 @@ class SyncHTTPClient:
) -> Dict[str, Any]:
return run_async(self._async_client.reindex(uri=uri, mode=mode, wait=wait))
- def admin_create_account(self, account_id: str, admin_user_id: str) -> Dict[str, Any]:
- return run_async(self._async_client.admin_create_account(account_id, admin_user_id))
+ def admin_create_account(
+ self,
+ account_id: str,
+ admin_user_id: str,
+ user_config: Optional[Dict[str, Any]] = None,
+ ) -> Dict[str, Any]:
+ return run_async(
+ self._async_client.admin_create_account(
+ account_id,
+ admin_user_id,
+ user_config=user_config,
+ )
+ )
def admin_list_accounts(self) -> List[Any]:
return run_async(self._async_client.admin_list_accounts())
@@ -1975,9 +2001,20 @@ class SyncHTTPClient:
return run_async(self._async_client.admin_delete_account(account_id))
def admin_register_user(
- self, account_id: str, user_id: str, role: str = "user"
+ self,
+ account_id: str,
+ user_id: str,
+ role: str = "user",
+ user_config: Optional[Dict[str, Any]] = None,
) -> Dict[str, Any]:
- return run_async(self._async_client.admin_register_user(account_id, user_id, role))
+ return run_async(
+ self._async_client.admin_register_user(
+ account_id,
+ user_id,
+ role,
+ user_config=user_config,
+ )
+ )
def admin_list_users(self, account_id: str) -> List[Any]:
return run_async(self._async_client.admin_list_users(account_id))
diff --git a/sdk/python/tests/test_async_client_behaviors.py b/sdk/python/tests/test_async_client_behaviors.py
index a78751c3b..2ba12d9af 100644
--- a/sdk/python/tests/test_async_client_behaviors.py
+++ b/sdk/python/tests/test_async_client_behaviors.py
@@ -363,6 +363,29 @@ async def test_add_resource_uploads_local_file_even_when_url_is_localhost(tmp_pa
assert "path" not in payload
+async def test_admin_create_paths_accept_initial_user_config():
+ client = AsyncHTTPClient(url="http://localhost:1933")
+ fake_http = SimpleNamespace(post=AsyncMock(return_value=object()))
+ client._http = fake_http
+ client._handle_response = lambda _response: {"status": "ok"}
+
+ user_config = {"add_targets": {"resource_uri": "viking://user/resources/project-a"}}
+ await client.admin_create_account("acct", "admin", user_config=user_config)
+ await client.admin_register_user("acct", "alice", "admin", user_config=user_config)
+
+ assert fake_http.post.await_args_list[0].kwargs["json"] == {
+ "account_id": "acct",
+ "admin_user_id": "admin",
+ "user_config": user_config,
+ }
+ assert fake_http.post.await_args_list[1].kwargs["json"] == {
+ "user_id": "alice",
+ "role": "admin",
+ "user_config": user_config,
+ }
+
+
@pytest.mark.asyncio
async def test_import_ovpack_uploads_local_file_even_when_url_is_localhost(tmp_path):
pack_file = tmp_path / "demo.ovpack"
@@ -445,10 +468,6 @@ async def test_search_uses_session_wrapper_session_id_in_payload():
"target_uri": "viking://resources/demo",
"session_id": "thread-123",
"limit": 5,
- "score_threshold": None,
- "filter": None,
- "context_type": None,
- "tags": None,
"telemetry": False,
},
)
diff --git a/tests/server/test_add_locations.py b/tests/server/test_add_locations.py
new file mode 100644
index 000000000..abd7190d2
--- /dev/null
+++ b/tests/server/test_add_locations.py
@@ -0,0 +1,146 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+import json
+
+import httpx
+import pytest
+
+from openviking.server.config import AddTargetsConfig, UserConfig, load_server_config
+from openviking_cli.utils.config import OPENVIKING_CONFIG_ENV
+from openviking_cli.utils.config.open_viking_config import OpenVikingConfigSingleton
+
+
[email protected](autouse=True)
+def _configure_test_env(monkeypatch, tmp_path):
+ config_path = tmp_path / "ov.conf"
+ config_path.write_text(
+ json.dumps(
+ {
+ "storage": {
+ "workspace": str(tmp_path / "workspace"),
+ "agfs": {"backend": "local"},
+ "vectordb": {"backend": "local"},
+ },
+ "embedding": {
+ "dense": {
+ "provider": "openai",
+ "model": "test-embedder",
+ "api_base": "http://127.0.0.1:11434/v1",
+ "dimension": 1024,
+ }
+ },
+ "encryption": {"enabled": False},
+ }
+ ),
+ encoding="utf-8",
+ )
+ monkeypatch.setenv(OPENVIKING_CONFIG_ENV, str(config_path))
+ OpenVikingConfigSingleton.reset_instance()
+ yield
+ OpenVikingConfigSingleton.reset_instance()
+
+
+async def _add_resource(client: httpx.AsyncClient, filename: str, **extra):
+ payload = {"temp_file_id": filename, "wait": True, **extra}
+ response = await client.post("/api/v1/resources", json=payload)
+ assert response.status_code == 200, response.text
+ return response.json()["result"]["root_uri"]
+
+
+async def test_add_locations_resource_server_default_and_precedence(
+ app,
+ client: httpx.AsyncClient,
+ sample_markdown_file,
+ upload_temp_dir,
+):
+ app.state.config.user_config_defaults = UserConfig(
+ add_targets=AddTargetsConfig(resource_uri="viking://user/resources")
+ )
+
+ root_uri = await _add_resource(client, sample_markdown_file.name)
+ assert root_uri.startswith("viking://user/default/resources/")
+
+ response = await client.patch(
+ "/api/v1/user-settings/add-locations",
+ json={"resource_uri": "viking://user/resources/project-a"},
+ )
+ assert response.status_code == 200, response.text
+ body = response.json()["result"]
+ assert body["effective"]["resource_uri"] == "viking://user/default/resources/project-a"
+
+ root_uri = await _add_resource(client, sample_markdown_file.name)
+ assert root_uri.startswith("viking://user/default/resources/project-a/")
+
+ root_uri = await _add_resource(
+ client,
+ sample_markdown_file.name,
+ to="viking://resources/one-off/sample",
+ )
+ assert root_uri == "viking://resources/one-off/sample"
+
+ response = await client.delete("/api/v1/user-settings/add-locations")
+ assert response.status_code == 200, response.text
+ root_uri = await _add_resource(client, sample_markdown_file.name)
+ assert root_uri.startswith("viking://user/default/resources/")
+ assert "/project-a/" not in root_uri
+
+
+async def test_add_locations_skill_server_default(
+ app,
+ client: httpx.AsyncClient,
+):
+ app.state.config.user_config_defaults = UserConfig(
+ add_targets=AddTargetsConfig(skill_uri="viking://agent/skills")
+ )
+
+ response = await client.post(
+ "/api/v1/skills",
+ json={
+ "data": {
+ "name": "default-agent-skill",
+ "description": "Skill default target test",
+ "content": "# Default Agent Skill",
+ },
+ "wait": True,
+ },
+ )
+ assert response.status_code == 200, response.text
+ assert response.json()["result"]["root_uri"] == "viking://agent/skills/default-agent-skill"
+
+
+async def test_add_locations_patch_rejects_bad_uris(client: httpx.AsyncClient):
+ response = await client.patch(
+ "/api/v1/user-settings/add-locations",
+ json={"skill_uri": "viking://user/skills/nested"},
+ )
+ assert response.status_code == 400
+ body = response.json()
+ assert body["status"] == "error"
+ assert body["error"]["code"] == "INVALID_ARGUMENT"
+
+ response = await client.patch(
+ "/api/v1/user-settings/add-locations",
+ json={"resource_uri": "viking://user/skills"},
+ )
+ assert response.status_code == 400
+ assert response.json()["error"]["code"] == "INVALID_ARGUMENT"
+
+
+def test_load_server_config_rejects_bad_add_locations(tmp_path):
+ config_path = tmp_path / "ov.conf"
+ config_path.write_text(
+ json.dumps(
+ {
+ "server": {
+ "user_config_defaults": {
+ "add_targets": {"resource_uri": "viking://user/skills"}
+ }
+ }
+ }
+ ),
+ encoding="utf-8",
+ )
+
+ with pytest.raises(ValueError, match="resource_uri"):
+ load_server_config(str(config_path))
diff --git a/tests/server/test_admin_api.py b/tests/server/test_admin_api.py
index 1079d9243..a3457f67d 100644
--- a/tests/server/test_admin_api.py
+++ b/tests/server/test_admin_api.py
@@ -21,6 +21,7 @@ from openviking.server.config import ServerConfig
from openviking.server.dependencies import set_service
from openviking.server.identity import RequestContext, Role
from openviking.server.models import ERROR_CODE_TO_HTTP_STATUS, ErrorInfo, Response
+from openviking.server.user_config import read_user_add_targets
from openviking.service.core import OpenVikingService
from openviking.service.task_store import (
SYSTEM_TASK_ACCOUNT_ID,
@@ -67,6 +68,18 @@ class _FakeAGFS:
class _FakeVikingFS:
def __init__(self):
self.agfs = _FakeAGFS()
+ self.files = {}
+
+ async def read_file(self, uri, **_kwargs):
+ if uri not in self.files:
+ raise FileNotFoundError(uri)
+ return self.files[uri]
+
+ async def write_file(self, uri, content, **_kwargs):
+ self.files[uri] = content
+
+ async def rm(self, uri, **_kwargs):
+ self.files.pop(uri, None)
class _FakeService:
@@ -88,6 +101,7 @@ def _build_lightweight_admin_test_app() -> FastAPI:
app = FastAPI()
app.state.config = ServerConfig(root_api_key=ROOT_KEY)
fake_service = _FakeService()
+ app.state.fake_service = fake_service
set_service(fake_service)
@app.exception_handler(OpenVikingError)
@@ -251,6 +265,48 @@ async def test_create_account(admin_client: httpx.AsyncClient, admin_service: Op
assert await admin_service.viking_fs.abstract("viking://user", ctx=ctx)
+async def test_create_user_paths_accept_initial_user_config(
+ lightweight_admin_client: httpx.AsyncClient,
+ lightweight_admin_app: FastAPI,
+):
+ acct = _uid()
+ viking_fs = lightweight_admin_app.state.fake_service.viking_fs
+
+ resp = await lightweight_admin_client.post(
+ "/api/v1/admin/accounts",
+ json={
+ "account_id": acct,
+ "admin_user_id": "alice",
+ "user_config": {"add_targets": {"resource_uri": "viking://user/resources/admin"}},
+ },
+ headers=root_headers(),
+ )
+ assert resp.status_code == 200, resp.text
+
+ alice_settings = await read_user_add_targets(
+ viking_fs,
+ RequestContext(user=UserIdentifier(acct, "alice"), role=Role.ADMIN),
+ )
+ assert alice_settings.resource_uri == "viking://user/resources/admin"
+
+ resp = await lightweight_admin_client.post(
+ f"/api/v1/admin/accounts/{acct}/users",
+ json={
+ "user_id": "bob",
+ "role": "user",
+ "user_config": {"add_targets": {"resource_uri": "viking://user/resources/bob"}},
+ },
+ headers=root_headers(),
+ )
+ assert resp.status_code == 200, resp.text
+
+ bob_settings = await read_user_add_targets(
+ viking_fs,
+ RequestContext(user=UserIdentifier(acct, "bob"), role=Role.USER),
+ )
+ assert bob_settings.resource_uri == "viking://user/resources/bob"
+
+
async def test_list_accounts(admin_client: httpx.AsyncClient):
"""ROOT can list all accounts."""
acct = _uid()