Agent/agent/docs/scope-design.md

Scope 设计文档

概述

Scope 系统用于控制知识的可见性和访问权限。采用灵活的标签系统，而非固定的层级结构。

核心原则

1. 知识类型与可见性分离

   • type 字段表示知识类型（What）
   • scopes 字段表示可见范围（Who）

2. 多 Scope 支持

   • 一条知识可以有多个 scope 标签
   • 支持灵活的共享关系

3. 明确的所有权

   • owner 字段表示唯一所有者
   • 只有所有者有权修改/删除

Scope 格式

格式：{entity_type}:{entity_id}

示例：
- user:123
- agent:general_assistant
- project:456
- team:frontend
- org:company
- public

Scope 类型

Scope 类型	格式	说明	示例
用户级	user:{user_id}	用户个人可见	user:123
Agent 级	agent:{agent_id}	特定 Agent 可见	agent:crawler_ops
项目级	project:{project_id}	项目组可见	project:456
团队级	team:{team_id}	部门可见	team:frontend
组织级	org:{org_id}	全公司可见	org:company
公开	public	所有人可见	public

数据结构

{
  "id": "knowledge_001",

  "type": "user_profile",

  "scopes": [
    "user:123",
    "project:456"
  ],

  "owner": "user:123",

  "visibility": "shared",

  "content": "...",
  "tags": {...},
  "source": {...},
  "eval": {...}
}

字段说明

type（知识类型）

• user_profile：用户画像
• strategy：执行经验
• tool：工具知识
• usecase：用例
• definition：概念定义
• plan：方法论

scopes（可见范围）

• 数组类型，可包含多个 scope
• 知识对所有 scopes 中的实体可见
• 检索时匹配：知识的 scopes 与用户的 visible_scopes 有交集

owner（所有者）

• 字符串类型，格式同 scope
• 唯一所有者，有权修改/删除
• 通常是创建者

visibility（可见性级别）

快速过滤标签，用于 UI 展示和简单查询：

• private：私有（仅所有者）
• shared：共享（多个实体）
• org：组织级
• public：公开

使用场景

场景 1：用户的私有偏好

{
  "type": "user_profile",
  "scopes": ["user:123"],
  "owner": "user:123",
  "visibility": "private",
  "content": "用户偏好使用 TypeScript"
}

场景 2：项目组共享的经验

{
  "type": "strategy",
  "scopes": ["project:456"],
  "owner": "agent:crawler_ops",
  "visibility": "shared",
  "content": "爬虫反爬策略：使用代理池 + 随机 UA"
}

场景 3：跨项目的用户偏好

{
  "type": "user_profile",
  "scopes": ["user:123", "project:456", "project:789"],
  "owner": "user:123",
  "visibility": "shared",
  "content": "用户在多个项目中都偏好使用 React"
}

场景 4：Agent 间共享的工具知识

{
  "type": "tool",
  "scopes": [
    "agent:crawler_ops",
    "agent:content_library",
    "agent:general_assistant"
  ],
  "owner": "agent:crawler_ops",
  "visibility": "shared",
  "content": "Selenium 使用技巧：headless 模式配置"
}

场景 5：组织级公开知识

{
  "type": "definition",
  "scopes": ["org:company"],
  "owner": "org:company",
  "visibility": "org",
  "content": "公司技术栈：React + TypeScript + Node.js"
}

场景 6：完全公开的知识

{
  "type": "tool",
  "scopes": ["public"],
  "owner": "org:company",
  "visibility": "public",
  "content": "Git 常用命令速查表"
}

检索逻辑

构建可见范围

def build_visible_scopes(context):
    """
    根据执行上下文构建用户的所有可见 scopes

    context = {
        "user_id": "123",
        "agent_id": "general_assistant",
        "project_id": "456",
        "team_id": "frontend",
        "org_id": "company"
    }
    """
    scopes = []

    if context.get("user_id"):
        scopes.append(f"user:{context['user_id']}")

    if context.get("agent_id"):
        scopes.append(f"agent:{context['agent_id']}")

    if context.get("project_id"):
        scopes.append(f"project:{context['project_id']}")

    if context.get("team_id"):
        scopes.append(f"team:{context['team_id']}")

    if context.get("org_id"):
        scopes.append(f"org:{context['org_id']}")

    scopes.append("public")

    return scopes

检索查询

def search_knowledge(query, context, knowledge_type=None):
    """
    检索知识

    query: 查询内容
    context: 用户上下文
    knowledge_type: 可选，过滤知识类型
    """
    # 1. 构建可见范围
    visible_scopes = build_visible_scopes(context)

    # 2. 构建查询条件
    filters = {
        "scopes": {"$in": visible_scopes}  # 交集匹配
    }

    if knowledge_type:
        filters["type"] = knowledge_type

    # 3. 向量检索 + 过滤
    results = vector_db.search(
        query=query,
        filter=filters,
        top_k=10
    )

    # 4. 按优先级排序
    return rank_by_scope_priority(results, context)

优先级排序

def rank_by_scope_priority(results, context):
    """
    按 scope 优先级排序

    优先级：user > project > agent > team > org > public
    """
    priority_map = {
        f"user:{context.get('user_id')}": 6,
        f"project:{context.get('project_id')}": 5,
        f"agent:{context.get('agent_id')}": 4,
        f"team:{context.get('team_id')}": 3,
        f"org:{context.get('org_id')}": 2,
        "public": 1
    }

    def get_priority(knowledge):
        # 取知识的 scopes 中优先级最高的
        max_priority = 0
        for scope in knowledge["scopes"]:
            max_priority = max(max_priority, priority_map.get(scope, 0))
        return max_priority

    return sorted(results, key=get_priority, reverse=True)

权限控制

读权限

用户可以读取知识，当且仅当：

• 知识的 scopes 与用户的 visible_scopes 有交集

写权限

用户可以修改/删除知识，当且仅当：

• 用户是知识的 owner

特殊情况

• 管理员可以修改/删除所有知识
• 组织级知识（owner=org:xxx）可以由管理员管理

实现位置

• agent/tools/builtin/knowledge.py：知识管理工具（KnowHub API 封装）+ KnowledgeConfig

扩展性

新增 Scope 类型

如需新增 scope 类型（如 department:{dept_id}），只需：

1. 在 build_visible_scopes 中添加逻辑
2. 在 rank_by_scope_priority 中添加优先级
3. 无需修改数据结构和存储逻辑

升级为 ACL

如需更细粒度的权限控制，可扩展为 ACL 系统：

{
  "id": "knowledge_001",
  "type": "strategy",
  "owner": "user:123",
  "acl": [
    {"entity": "user:123", "permission": "read_write"},
    {"entity": "project:456", "permission": "read"},
    {"entity": "agent:general_assistant", "permission": "read"}
  ]
}

但对于大多数场景，当前的 scope 标签系统已经足够。