Account 级 User / Agent 命名空间策略与共享 Session 设计方案

Context

当前 OpenViking 已具备 account_id / user_id / agent_id 三元身份模型，但 user 与 agent 的关系语义仍然不够明确，session、目录和检索对这层关系的表达也不一致，主要问题有：

系统内缺少 account 级显式策略来定义 user scope 是否再按 agent 切分、agent scope 是否再按 user 切分
命名空间决策分散在多处，目录拓扑无法直接体现 user / agent 关系
session 仍然偏向单 user 视角，不能准确表达一个 account 内多 user / 多 agent 协同场景中的真实参与者身份
检索、目录遍历、向量索引、消息身份模型之间缺少一套统一的 owner / participant 语义

本次方案的目标，是把 user / agent 关系显式提升为 account 级命名空间策略，并为后续混合参与者 session 的提取、审计和协同能力打基础。

决策摘要

account 级新增两项配置：
- isolate_user_scope_by_agent: bool
- isolate_agent_scope_by_user: bool
默认值：
- isolate_user_scope_by_agent = false
- isolate_agent_scope_by_user = false
user 与 agent 目录都采用显式嵌套 canonical URI，不再依赖 hash space。
session 升级为 account 级共享作用域，统一落在：
- viking://session/{session_id}
session add-message 新增 role_id：
- role=user 时绑定真实 user_id
- role=assistant 时绑定真实 agent_id
检索与目录可见性统一基于以下信息：
- account_id
- uri
- owner_user_id
- owner_agent_id
本方案按不兼容改造设计：
- 不做旧命名空间兼容
- 不做历史数据迁移
- 不做 mixed session commit / extract 分流

一、目标与非目标

1.1 目标

引入 account 级配置，显式定义 user 和 agent 的共享边界
统一 user / agent / session 的逻辑 URI 与底层目录拓扑
将 session 升级为 account 级共享会话
在 session add-message 中显式记录消息归属身份
统一文件系统可见性与检索过滤规则，避免“能搜到但不能读”

1.2 非目标

本次不实现历史数据迁移
本次不实现双读双写兼容
本次不定义混合参与者 session 的 commit / extract 分流算法
本次不引入 participant 级 ACL，只提供 account 级共享 session

二、核心设计决策

2.1 account 级配置字段

推荐字段名：

isolate_user_scope_by_agent: bool
isolate_agent_scope_by_user: bool

语义如下：

isolate_user_scope_by_agent = false
- user 作用域只按 user_id 分区
isolate_user_scope_by_agent = true
- user 作用域按 (user_id, agent_id) 分区
isolate_agent_scope_by_user = false
- agent 作用域只按 agent_id 分区
isolate_agent_scope_by_user = true
- agent 作用域按 (agent_id, user_id) 分区

默认值：

isolate_user_scope_by_agent = false
isolate_agent_scope_by_user = false

这个默认值的含义是：

user 记忆按 user 隔离，不区分 agent
agent 记忆按 agent 隔离，不区分 user

采用这个默认值的原因是：

大多数产品里，用户画像、偏好、个人事实更自然地跟 user 绑定，应该能跨 agent 复用
很多 agent 在系统内更像“共享能力单元”而不是“每个 user 一份的私有副本”，默认跨 user 共享更符合直觉
把两者都默认设为“不额外切分”，可以让目录语义最直接，减少初期理解和使用成本

2.2 配置方式与生命周期

这两个字段在 account 创建时配置，并跟随 account 生命周期持久化。

持久化位置：

/local/{account_id}/_system/setting.json

示例：

json

{
  "namespace": {
    "isolate_user_scope_by_agent": false,
    "isolate_agent_scope_by_user": false
  }
}

配置入口：

POST /api/v1/admin/accounts

请求示例：

json

{
  "account_id": "acme",
  "admin_user_id": "alice",
  "isolate_user_scope_by_agent": false,
  "isolate_agent_scope_by_user": false
}

如果请求里省略这两个字段，则服务端按默认值补齐：

json

{
  "isolate_user_scope_by_agent": false,
  "isolate_agent_scope_by_user": false
}

读取入口：

GET /api/v1/admin/accounts
GET /api/v1/admin/accounts/{account_id}（如果后续补充单 account 查询接口）

持久化要求：

account 创建时，服务端将这两个字段写入 /{account_id}/_system/setting.json 的 namespace 节点
服务启动后加载 account 配置时，这两个字段进入 AccountNamespacePolicy
后续所有 URI 解析、目录初始化、检索过滤、session 可见性都只能读取这一个来源

修改策略：

本阶段不提供 account policy 更新接口
account 创建完成后，这两个字段视为不可变
不支持通过手工修改 setting.json 的方式在线切换 policy

原因：

修改任一字段都会改变 canonical URI 结构
已有目录路径、索引字段、session 派生引用都会跟着变化
在没有迁移工具、校验工具和回滚策略之前，不应支持在线修改

如果后续业务确实需要调整：

方案一：新建 account，按新 policy 初始化，再做数据迁移
方案二：单独立项做离线迁移，不通过常规 admin API 在线修改

2.3 配置生效层级

这两个字段只在 account 上定义，不在 user、agent、session 或请求级覆盖。

原因：

命名空间拓扑属于 account 级存储契约，不适合在请求级动态切换
一旦允许运行时切换，就会导致同一 account 内路径布局和检索过滤规则不稳定
统一到 account 级后，目录、索引、权限判断才能保持一致

三、命名空间模型

3.1 总体原则

逻辑 URI 采用显式嵌套路径，不再依赖不可读的 hash space
user、agent、session 都有 canonical URI
简写 URI 可以保留，但内部必须先 canonicalize，再进入存储、检索和权限判断

3.2 四种拓扑矩阵

`isolate_user_scope_by_agent=false`，`isolate_agent_scope_by_user=false`

text

viking://user/{user_id}/...
viking://agent/{agent_id}/...
viking://session/{session_id}/...

底层目录：

text

/local/{account_id}/user/{user_id}/...
/local/{account_id}/agent/{agent_id}/...
/local/{account_id}/session/{session_id}/...

访问规则：

当前请求身份为 (user_id=ua, agent_id=aa) 时，可以访问 viking://user/ua/... 下的全部 user 数据，不受当前 agent 影响
当前请求身份为 (user_id=ua, agent_id=aa) 时，可以访问 viking://agent/aa/... 下的全部 agent 数据，不受当前 user 影响
不能访问其他 user 的 viking://user/{other_user_id}/...
不能访问其他 agent 的 viking://agent/{other_agent_id}/...
session 按 account 共享，访问规则独立于这两个字段

适用场景：

一个 account 内多个 user 共同使用一组标准化 agent，且 agent 的技能、案例、工作区都希望在团队内共享
用户侧资料也希望跨 agent 复用，例如统一的用户画像、偏好、长期事实
更适合协作型工作区，而不是强隔离场景

`isolate_user_scope_by_agent=false`，`isolate_agent_scope_by_user=true`

text

viking://user/{user_id}/...
viking://agent/{agent_id}/user/{user_id}/...
viking://session/{session_id}/...

底层目录：

text

/local/{account_id}/user/{user_id}/...
/local/{account_id}/agent/{agent_id}/user/{user_id}/...
/local/{account_id}/session/{session_id}/...

访问规则：

当前请求身份为 (user_id=ua, agent_id=aa) 时，可以访问 viking://user/ua/... 下的全部 user 数据，不受当前 agent 影响
当前请求身份为 (user_id=ua, agent_id=aa) 时，只能访问 viking://agent/aa/user/ua/...
不能访问 viking://agent/aa/user/{other_user_id}/...
不能访问 viking://agent/{other_agent_id}/user/ua/...
session 按 account 共享，访问规则独立于这两个字段

适用场景：

同一个 user 会在多个 agent 之间切换，希望个人资料和长期偏好能直接复用
不同 user 虽然可能使用同名 agent，但 agent 的案例、instructions、技能配置等沉淀需要彼此隔离
适合希望保留 user 侧共享，但对 agent 侧共享更谨慎的部署方式

`isolate_user_scope_by_agent=true`，`isolate_agent_scope_by_user=false`

text

viking://user/{user_id}/agent/{agent_id}/...
viking://agent/{agent_id}/...
viking://session/{session_id}/...

底层目录：

text

/local/{account_id}/user/{user_id}/agent/{agent_id}/...
/local/{account_id}/agent/{agent_id}/...
/local/{account_id}/session/{session_id}/...

访问规则：

当前请求身份为 (user_id=ua, agent_id=aa) 时，只能访问 viking://user/ua/agent/aa/...
不能访问 viking://user/ua/agent/{other_agent_id}/...
当前请求身份为 (user_id=ua, agent_id=aa) 时，可以访问 viking://agent/aa/... 下的全部 agent 数据，不受当前 user 影响
不能访问其他 agent 的 viking://agent/{other_agent_id}/...
session 按 account 共享，访问规则独立于这两个字段

适用场景：

agent 本身代表某种共享岗位能力或团队能力，希望其案例、技能、instructions 等沉淀在所有 user 之间复用
但同一个 user 在不同 agent 下的个人资料或用户记忆不希望互通
适合“agent 是主实体，user 只是调用者”的平台型场景

`isolate_user_scope_by_agent=true`，`isolate_agent_scope_by_user=true`

text

viking://user/{user_id}/agent/{agent_id}/...
viking://agent/{agent_id}/user/{user_id}/...
viking://session/{session_id}/...

底层目录：

text

/local/{account_id}/user/{user_id}/agent/{agent_id}/...
/local/{account_id}/agent/{agent_id}/user/{user_id}/...
/local/{account_id}/session/{session_id}/...

访问规则：

当前请求身份为 (user_id=ua, agent_id=aa) 时，只能访问 viking://user/ua/agent/aa/...
不能访问 viking://user/ua/agent/{other_agent_id}/...
当前请求身份为 (user_id=ua, agent_id=aa) 时，只能访问 viking://agent/aa/user/ua/...
不能访问 viking://agent/aa/user/{other_user_id}/...
不能访问 viking://agent/{other_agent_id}/user/ua/...
session 按 account 共享，访问规则独立于这两个字段

适用场景：

每个 (user, agent) 组合都应视为独立工作单元，不能共享任何用户记忆或 agent 沉淀
强合规、强审计、强租户内隔离场景
适合外包、敏感业务、或需要最小共享面的部署方式

3.3 scope 内部结构

user scope

text

memories/
  preferences/
  entities/
  events/
profile.md

agent scope

text

memories/
  cases/
  patterns/
skills/
instructions/

session scope

text

messages.jsonl
history/
tools/
.meta.json

3.4 简写 URI 规则

保留如下简写：

viking://user/...
viking://agent/...

但内部一律按当前 account policy 和请求身份展开为 canonical URI。

示例：当前身份为 (account=acme, user=ua, agent=aa)

当 isolate_user_scope_by_agent=false 时：

text

viking://user/memories/preferences/
=> viking://user/ua/memories/preferences/

当 isolate_user_scope_by_agent=true 时：

text

viking://user/memories/preferences/
=> viking://user/ua/agent/aa/memories/preferences/

当 isolate_agent_scope_by_user=false 时：

text

viking://agent/memories/cases/
=> viking://agent/aa/memories/cases/

当 isolate_agent_scope_by_user=true 时：

text

viking://agent/memories/cases/
=> viking://agent/aa/user/ua/memories/cases/

要求：

存储层只处理 canonical URI
向量索引写入只处理 canonical URI
权限判断只处理 canonical URI

四、Session 模型重构

4.1 Session 作用域调整

将 session 从 user 目录下移出，统一为 account 级共享：

text

viking://session/{session_id}

底层目录：

text

/local/{account_id}/session/{session_id}

设计原因：

同一 account 内可能有多个 user / agent 共同参与一个会话
把 session 绑定在某个 user 根目录下，会让会话共享变得别扭
session 作为临时协作容器，更适合按 account 共享，再通过消息身份描述参与者

4.2 Session 可见性与权限

推荐权限：

create / list / get / add-message / commit
- 同 account 内可访问
delete
- 仅 ADMIN
- 或 ROOT

这意味着：

session 可被 account 内其他 user 看到和继续使用
删除权限单独收紧，避免 shared session 的“所有者”语义不清

4.3 Session 元数据

session/.meta.json 新增字段：

created_by_user_id
participant_user_ids
participant_agent_ids

说明：

created_by_user_id 表示“这个 session 最初是由哪个请求身份创建出来的”
写入时机：
- 第一次真正创建 session 时写入 .meta.json
- 具体包括 POST /api/v1/sessions 创建
- 以及未来如果保留 auto_create 语义，则第一次自动创建时也写入
写入来源：
- 直接取创建请求对应的 RequestContext.user.user_id
- 也就是发起这次创建操作的请求用户
一旦写入，不再随着后续 add-message 的 role_id 变化而变化
它是审计字段，不直接参与删除权限判断
participant_* 只用于索引、展示、后续提取分流，不承担 ACL

也就是说：

created_by_user_id 不是客户端额外传的参数
它是服务端在“创建 session 的那一刻”从当前登录身份里自动记下来的
它和消息里的 role_id 不是一回事
- created_by_user_id 解决“这个 session 最初由谁创建”
- role_id 解决“这条消息是谁说的”

4.4 `add-message` 接口扩展

在 POST /api/v1/sessions/{session_id}/messages 中新增 role_id。

示例：

json

{
  "role": "user",
  "role_id": "ua",
  "content": "你好"
}

json

{
  "role": "assistant",
  "role_id": "aa",
  "parts": [...]
}

规则：

role == "user" 时，role_id 表示真实 user_id
role == "assistant" 时，role_id 表示真实 agent_id
其他 role 暂不使用 role_id

4.5 请求头语义与 `RequestContext` 解析

服务端需要区分“真实调用者身份”和“本次请求按谁的视角执行”。

在不同认证模式下，X-OpenViking-Account、X-OpenViking-User、X-OpenViking-Agent 的语义如下：

trusted 模式
- X-OpenViking-Account / User / Agent 表示真实调用者身份
- 此时不存在模拟其他用户身份的语义
api_key + ROOT
- X-OpenViking-Account / User / Agent 表示本次请求的生效上下文
- ROOT 可以显式指定本次请求作用到哪个 account / user / agent
api_key + ADMIN
- X-OpenViking-User / Agent 表示本次请求的生效 user / agent 上下文
- ADMIN 只能在自己的 account 内使用这组请求头模拟用户视角
- ADMIN 不允许通过 X-OpenViking-Account 切换到其他 account
api_key + USER
- user_id 只能从当前 user key 对应的身份解析
- X-OpenViking-Agent 仍可用于指定当前请求的 agent 上下文
- USER 不允许通过 X-OpenViking-User 切换到其他 user

RequestContext 的语义统一为：

ctx.user 表示本次请求的生效身份
ctx.role 表示真实调用者角色
namespace 解析、检索过滤、文件系统可见性都按 ctx.user 执行
管理权限按 ctx.role 判断

4.6 `add-message` 校验与默认填充

role_id 的语义如下：

role = "user" 时，role_id 表示消息所属的 user_id
role = "assistant" 时，role_id 表示消息所属的 agent_id

校验与填充规则：

trusted、ROOT、ADMIN
- 可以显式传入 role_id
- 如果未显式传入：
  - role = "user" 时，默认填充 ctx.user.user_id
  - role = "assistant" 时，默认填充 ctx.user.agent_id
USER
- 可以显式传入 role_id，服务端以传入值为准
- 如果未显式传入：
  - role = "user" 时，默认填充 ctx.user.user_id
  - role = "assistant" 时，默认填充 ctx.user.agent_id

额外约束：

role = "user" 时，role_id 语义表示消息所属的 user_id，由调用方保证为当前 account 下合法的 user_id
role = "assistant" 时，role_id 作为 agent_id 使用
本阶段不引入独立的 agent registry；服务端不对 role_id 做格式或上下文一致性校验，语义一致性由调用方承担

4.7 消息持久化结构

Message 增加字段：

json

{
  "id": "msg_xxx",
  "role": "assistant",
  "role_id": "aa",
  "parts": [...],
  "created_at": "2026-04-09T10:00:00Z"
}

role_id 表示这条消息的 actor 身份，不等于真实调用者身份。后续从消息派生 tool / skill / memory 归属时，应以消息自身的 role + role_id 为准。

4.8 Session 派生 URI

tool_uri 统一调整为：

text

viking://session/{session_id}/tools/{tool_id}

后续凡是从 message 中派生 tool / skill / memory 归属时，都应优先使用消息上的 role + role_id，而不是默认使用当前请求上下文里的 agent / user。

五、检索、文件系统与可见性

5.1 问题

当前很多逻辑依赖单一字符串字段 owner_space。这个字段在以下场景下不够稳定：

命名空间拓扑有四种组合
session 改成 account 共享后，不能再把 session 误归到 user owner
user/agent 简写 URI 需要展开
仅靠一个字符串，不方便做结构化可见性判断

5.2 索引中的归属信息

向量索引和 Context 的归属字段调整为：

保留已有字段：
- account_id
- uri
新增字段：
- owner_user_id
- owner_agent_id
移除字段：
- owner_scope

其中：

uri 使用标准路径
scope 从 uri 的前缀解析得到，不单独存 owner_scope
owner_user_id / owner_agent_id 用来表达这条数据绑定到哪个 user / agent
uri 和 owner_user_id / owner_agent_id 需要保持一致，不能互相冲突

5.3 写入规则

所有写入到索引的数据，都必须先确定标准 URI，再由标准 URI 生成 owner_user_id / owner_agent_id。

写入时规则如下：

resource

text

uri = viking://resources/...
owner_user_id = null
owner_agent_id = null

user scope

text

uri = viking://user/{user_id}/...                         if isolate_user_scope_by_agent = false
uri = viking://user/{user_id}/agent/{agent_id}/...       if isolate_user_scope_by_agent = true

owner_user_id = user_id
owner_agent_id = null                                    if isolate_user_scope_by_agent = false
owner_agent_id = agent_id                                if isolate_user_scope_by_agent = true

agent scope

text

uri = viking://agent/{agent_id}/...                      if isolate_agent_scope_by_user = false
uri = viking://agent/{agent_id}/user/{user_id}/...       if isolate_agent_scope_by_user = true

owner_agent_id = agent_id
owner_user_id = null                                     if isolate_agent_scope_by_user = false
owner_user_id = user_id                                  if isolate_agent_scope_by_user = true

session

text

uri = viking://session/{session_id}/...
owner_user_id = null
owner_agent_id = null

5.4 查询过滤规则

检索时先加：

text

account_id == ctx.account_id

然后根据当前 (user_id, agent_id) 和 account policy，算出本次请求可见的路径根：

resource 根路径

text

viking://resources/

session 根路径

text

viking://session/

user 根路径

text

viking://user/{user_id}/...                         if isolate_user_scope_by_agent = false
viking://user/{user_id}/agent/{agent_id}/...       if isolate_user_scope_by_agent = true

agent 根路径

text

viking://agent/{agent_id}/...                      if isolate_agent_scope_by_user = false
viking://agent/{agent_id}/user/{user_id}/...       if isolate_agent_scope_by_user = true

检索过滤由两部分组成：

account_id == ctx.account_id
uri 必须落在上述可见根路径下
owner_user_id / owner_agent_id 必须满足当前 policy 对应的可见范围

如果请求显式传了 target_uri，则：

先把 target_uri 归一化成标准路径
校验该 target_uri 是否在当前请求可见范围内
再把检索范围收敛到该 target_uri 前缀下

说明：

session 在本方案中按 account 共享，因此统一落在 viking://session/
uri 用来表达真实路径范围
owner_user_id / owner_agent_id 用来表达绑定到哪个 user / agent
文件系统可见性与检索过滤必须复用同一套判断规则

5.5 结果校验与错误处理

检索返回后，服务端仍需对命中结果做一次基于 uri + owner_user_id + owner_agent_id 的一致性校验，避免索引脏数据或历史遗留数据泄漏。

错误处理如下：

target_uri 路径形状和当前 policy 不匹配：返回 400
target_uri 本身形状没问题，但当前身份无权访问：返回 403
不传 target_uri 时，按当前身份可见范围做全局检索

5.6 文件系统与目录初始化

VikingFS

需要引入统一的 namespace resolver，承担以下职责：

根据 account policy + 当前身份生成 canonical user / agent 根路径
将简写 URI canonicalize
解析 URI 对应的 owner 结构
判断路径是否对当前 (account_id, user_id, agent_id) 可见

VikingFS 的以下能力都需要切到新规则：

_uri_to_path
_path_to_uri
_is_accessible
ls / tree / stat / read / write

DirectoryInitializer

目录初始化要区分两类节点：

真实作用域根
- 需要生成 memories / skills / instructions 等预置结构
中间容器目录
- 只承担路径承载作用
- 不重复写入预置抽象与 overview

例如在 isolate_user_scope_by_agent=true 且 isolate_agent_scope_by_user=true 下：

text

viking://agent/{agent_id}

只是容器；

text

viking://agent/{agent_id}/user/{user_id}

才是实际的 agent scope 根。

六、接口与类型变更

6.1 Admin API

POST /api/v1/admin/accounts 新增：

isolate_user_scope_by_agent
isolate_agent_scope_by_user

GET /api/v1/admin/accounts 返回同样两项配置。

account 级 namespace policy 持久化在：

/local/{account_id}/_system/setting.json

文件示例：

json

{
  "namespace": {
    "isolate_user_scope_by_agent": false,
    "isolate_agent_scope_by_user": false
  }
}

如果创建请求未显式传值，则服务端使用默认值：

isolate_user_scope_by_agent = false
isolate_agent_scope_by_user = false

本阶段不提供修改 account policy 的更新接口。

原因：

修改 policy 本质上是重排目录和索引
没有迁移机制前，不应允许运行时修改
直接手工修改 setting.json 也不在支持范围内

6.2 核心类型

需要扩展：

AccountInfo
ResolvedIdentity
RequestContext
Message
SessionMeta
Context

七、影响模块

本次方案预计影响如下模块族：

多租户与认证
- account 配置读写
- auth middleware
- request context
命名空间解析
- UserIdentifier
- 新增统一 resolver / policy
文件系统
- VikingFS
- DirectoryInitializer
session
- Session
- SessionService
- sessions router
- Message
检索与向量
- Context
- embedding message converter
- semantic processor
- collection schema
- vector backend filter
接入层
- Python SDK
- HTTP client
- Rust CLI

八、兼容性策略

本次不采用“全量兼容”或“双读双写”策略，而是按 scope 分别处理：

8.1 user scope

user 侧默认路径本身就是 viking://user/{user_id}/...
如果新拓扑仍然采用 user 共享形态，则 AGFS 路径天然兼容
因此本阶段不对 user 侧做目录迁移

8.2 session scope

session 只在 AGFS 中维护，不进入 VectorDB
在确认 account 内不存在同名 session_id 的前提下，session 迁移按纯目录移动处理：

text

viking://session/{user_id}/{session_id}
-> viking://session/{session_id}

本阶段不保留旧 session 根路径兼容读
迁移完成后，session 的 list / get / delete / add-message / commit 全部只认新路径

8.3 agent scope

本次不支持旧 agent 数据自动迁移到新命名空间
不保留旧 hash namespace 的兼容访问
不继续让 memory.agent_scope_mode 参与服务端命名空间决策
如需保留旧 agent 数据，可在升级前自行使用现有 ovpack 做离线备份

推荐迁移方式：

升级前：在旧版本中从 legacy hash namespace 导出，例如：

bash

ov export viking://agent/{legacy_agent_space_hash}/memories ./agent_memory.ovpack

升级后：在新版本中按目标 account policy 导入到 agent space 的父目录：

bash

# isolate_agent_scope_by_user = false
ov import ./agent_memory.ovpack viking://agent/{agent_id}/ --force

# isolate_agent_scope_by_user = true
ov import ./agent_memory.ovpack viking://agent/{agent_id}/user/{user_id}/ --force

不要把 .ovpack 直接导入到 .../memories/ 本身，否则会得到 .../memories/memories/...
当 isolate_agent_scope_by_user = true 时，viking://agent/{agent_id}/user/ 不是合法目标；必须显式提供 user_id

原因：

当前 agent root 是 hash space，而不是显式 agent_id
hash 值不能从结果稳定反推出原始 user_id / agent_id
如果目标拓扑还涉及 agent 共享，会进一步引入多份旧数据合并问题

8.4 总体取舍

本次兼容策略总结如下：

user：天然兼容，不迁
session：直接 mv
agent：不自动兼容，只提供 ovpack 导出

这个取舍的目的是把新命名空间模型尽快收敛为单一存储契约，而不是把 legacy hash 逻辑继续带入新实现。

九、风险与边界

9.1 混合参与者 session 的提取策略尚未定义

当一个 session 同时包含多个 user 和多个 assistant 时，后续 commit / extract 如何分流到对应 user / agent 作用域，是独立问题。

本次只解决：

会话可以共享
每条消息的参与者身份可追踪
检索与目录可见性有稳定 owner 语义

9.2 session 共享不等于 participant ACL

本方案采用 account 级共享 session。也就是说，同 account 内用户都可以看见 session。

如果未来需要“仅参与者可见”的 session，需要额外引入 participant ACL 模型，这不在本次范围内。

9.3 拓扑切换不可在线修改

一旦 account 已有数据，切换 isolate_user_scope_by_agent 或 isolate_agent_scope_by_user 会导致：

目录 root 变化
索引字段变化
检索过滤条件变化

因此本阶段不支持在线修改。

十、测试方案

10.1 account policy

创建 account 时两项配置写入成功
list account 能返回两项配置
默认值为 false / false
四种组合可正确加载

10.2 namespace matrix

user / agent canonical URI 生成正确
简写 URI 展开正确
四种拓扑下底层目录映射正确
中间容器目录与真实作用域根区分正确

10.3 session

session 根路径为 viking://session/{session_id}
session list 为 account 级
role_id 校验正确
Message.role_id 持久化正确
participant_user_ids / participant_agent_ids 正确累积
ADMIN / ROOT 删除权限正确

10.4 retrieval / visibility

FS ls / stat / read 与检索结果一致
user scope 在四种 policy 下可见性正确
agent scope 在四种 policy 下可见性正确
session scope 按 account 共享
cross-account 不泄漏

10.5 negative cases

缺失 role_id
非法 nested URI
policy 与路径不匹配
尝试访问非本 user / agent 可见作用域

十一、推荐落地顺序

建议按以下顺序实施：

引入 account policy 与统一 namespace resolver
改造 UserIdentifier、RequestContext、Admin API
改造 VikingFS 与目录初始化
改造 session 路径与 Message.role_id
改造 Context、embedding、vector schema 与过滤逻辑
最后更新 SDK / CLI 与文档

这样可以先把“路径与身份语义”固定，再去改造检索与接入层，风险更可控。

结论

本方案的核心是把 user、agent 的共享关系显式提升为 account 级策略，并将 session 升级为 account 级共享容器，再用 role_id 和标准 URI 把消息、目录和检索统一到同一套身份模型上。

如果接受这份方案，后续实现应严格遵守两条主线：

所有 URI 先 canonicalize，再进入存储、检索、权限判断
所有可见性与索引判断都基于 account_id + uri + owner_user_id + owner_agent_id

这两条一旦立住，后续 mixed session extraction、participant ACL、审计追踪才有稳定的基础。

Account 级 User / Agent 命名空间策略与共享 Session 设计方案

Account 级 User / Agent 命名空间策略与共享 Session 设计方案

Context

决策摘要

一、目标与非目标

1.1 目标

1.2 非目标

二、核心设计决策

2.1 account 级配置字段

2.2 配置方式与生命周期

2.3 配置生效层级

三、命名空间模型

3.1 总体原则

3.2 四种拓扑矩阵

isolate_user_scope_by_agent=false，isolate_agent_scope_by_user=false

isolate_user_scope_by_agent=false，isolate_agent_scope_by_user=true

isolate_user_scope_by_agent=true，isolate_agent_scope_by_user=false

isolate_user_scope_by_agent=true，isolate_agent_scope_by_user=true

3.3 scope 内部结构

user scope

agent scope

session scope

3.4 简写 URI 规则

四、Session 模型重构

4.1 Session 作用域调整

4.2 Session 可见性与权限

4.3 Session 元数据

4.4 add-message 接口扩展

4.5 请求头语义与 RequestContext 解析

4.6 add-message 校验与默认填充

4.7 消息持久化结构

4.8 Session 派生 URI

五、检索、文件系统与可见性

5.1 问题

5.2 索引中的归属信息

5.3 写入规则

resource

user scope

agent scope

session

5.4 查询过滤规则

resource 根路径

session 根路径

user 根路径

agent 根路径

5.5 结果校验与错误处理

5.6 文件系统与目录初始化

VikingFS

DirectoryInitializer

六、接口与类型变更

6.1 Admin API

6.2 核心类型

七、影响模块

八、兼容性策略

8.1 user scope

8.2 session scope

8.3 agent scope

8.4 总体取舍

九、风险与边界

9.1 混合参与者 session 的提取策略尚未定义

9.2 session 共享不等于 participant ACL

9.3 拓扑切换不可在线修改

十、测试方案

10.1 account policy

10.2 namespace matrix

10.3 session

10.4 retrieval / visibility

10.5 negative cases

十一、推荐落地顺序

结论

`isolate_user_scope_by_agent=false`，`isolate_agent_scope_by_user=false`

`isolate_user_scope_by_agent=false`，`isolate_agent_scope_by_user=true`

`isolate_user_scope_by_agent=true`，`isolate_agent_scope_by_user=false`

`isolate_user_scope_by_agent=true`，`isolate_agent_scope_by_user=true`

4.4 `add-message` 接口扩展

4.5 请求头语义与 `RequestContext` 解析

4.6 `add-message` 校验与默认填充