Agent/agent/docs/knowledge.md

知识结构（单条知识）

id: 知识唯一标识
task: 任务描述，什么场景、在做什么

type: 知识类型（单选）
    user_profile：用户画像（偏好、习惯、背景、约束）
    strategy：具体执行经验，从执行过程中反思获得
    tool：工具名称，简介，使用方法，优缺点对比，代码示例
    usecase：用户背景，采用方案，实现步骤，问题，效果
    definition：概念定义，技术原理，应用场景
    plan：流程步骤，决策点，某个问题的总结方法论

tags: 业务标签（可有多个）
    category: 子类别（如 preference, background, habit, constraint）
    domain: 领域（如 coding_style, architecture）
    其他自定义标签

scopes: 可见范围（可有多个，格式：{entity_type}:{entity_id}）
    user:{user_id}：用户级（个人可见）
    agent:{agent_id}：Agent 级（特定 Agent 可见）
    project:{project_id}：项目级（项目组可见）
    team:{team_id}：团队级（部门可见）
    org:{org_id}：组织级（全公司可见）
    public：公开（所有人可见）

owner: 所有者（格式：{entity_type}:{entity_id}，唯一）
    谁创建的，谁有权修改/删除

content:
    基于类型的具体内容，相对完整的一条知识

source:
    name: 工具/资源名称（若有）
    category：paper/exp/skill/book...
    urls：知识来源的网站
    agent_id：调用知识查询的agent名称
    submitted_by：创建本条目的agent负责人名称
    timestamp: 知识生成时的时间戳
    trace_id: 来源 Trace ID（若有）

eval：基于使用反馈
    helpful: 好用的次数
    harmful：不好用的次数
    confidence: 置信度（0-1）
    helpful_history: [(query+trace_id+outcome), ]用于记录反馈时的调用总结
    harmful_history: []

知识检索机制

检索流程
    1. 构建可见范围
        根据执行上下文（user_id, agent_id, project_id, team_id, org_id）
        构建用户的所有可见 scopes：
            - user:{user_id}
            - agent:{agent_id}
            - project:{project_id}
            - team:{team_id}
            - org:{org_id}
            - public

    2. 向量检索 + 过滤
        查询条件：
            - 语义匹配（向量检索）
            - scopes 过滤（知识的 scopes 与用户的 visible_scopes 有交集）
            - type 过滤（可选，按知识类型过滤）

    3. 按优先级排序
        优先级：user > project > agent > team > org > public
        取知识的 scopes 中优先级最高的进行排序

触发时机
    - Agent 启动时：自动检索相关知识
    - Goal focus 时：检索与当前目标相关的知识
    - 主动调用：通过 get_knowledge 工具主动查询

实现位置（规划）
    - agent/memory/knowledge_store.py: 知识存储接口
    - agent/memory/knowledge_retriever.py: 检索逻辑
    - agent/tools/builtin/knowledge.py: get_knowledge 工具

知识提取机制

触发时机
    - 主动表达：用户明确表达偏好、纠正、提供背景信息
    - 任务完成：任务完成后的反思总结
    - 压缩消息：在压缩消息节点提取经验
    - 用户反馈：用户对结果的 helpful/harmful 评价

提取流程
    1. 识别知识类型
        根据内容判断是 user_profile / strategy / tool / definition / plan / usecase

    2. 结构化提取
        - 提取核心内容
        - 生成标签（category, domain 等）
        - 确定 scopes（基于执行上下文）
        - 设置 owner 和 visibility

    3. 持久化存储
        - 存入知识库（向量数据库 + 元数据）
        - 记录来源（trace_id, agent_id, timestamp）
        - 初始化评价（helpful=1, confidence=0.5）

实现位置（规划）
    - agent/trace/compaction.py: 压缩时提取经验
    - agent/tools/builtin/knowledge.py: save_knowledge 工具
    - agent/memory/knowledge_extractor.py: 知识提取逻辑

用户画像特殊处理

用户画像是一种特殊的知识类型（type=user_profile），具有以下特点：

获取方式
    - 持续性：在整个对话过程中持续积累
    - 多触发点：主动表达 > 任务完成 > 周期性总结
    - 渐进式：逐步完善，置信度逐渐提高

存储特点
    - type: user_profile
    - scopes: 通常包含 user:{user_id}，可能包含 project:{project_id}
    - owner: user:{user_id}
    - tags.category: preference | background | habit | constraint

检索优先级
    - 在 Agent 启动时自动加载
    - 优先级高于其他类型的知识
    - 按 confidence 和 helpful 评分排序

示例
    {
        "id": "profile_001",
        "type": "user_profile",
        "task": "用户编码风格偏好",
        "tags": {
            "category": "preference",
            "domain": "coding_style"
        },
        "scopes": ["user:123", "project:456"],
        "owner": "user:123",
        "visibility": "shared",
        "content": "用户偏好使用 TypeScript 而非 JavaScript，注重类型安全",
        "source": {
            "agent_id": "general_assistant",
            "trace_id": "trace-xxx",
            "timestamp": "2026-03-03"
        },
        "eval": {
            "helpful": 5,
            "harmful": 0,
            "confidence": 0.9
        }
    }

存储结构（规划）

数据库表结构
    CREATE TABLE knowledge (
        id TEXT PRIMARY KEY,
        type TEXT NOT NULL,              -- user_profile | strategy | tool | ...
        task TEXT,
        tags JSON,
        scopes JSON,                     -- ["user:123", "project:456", ...]
        owner TEXT NOT NULL,             -- "user:123" | "agent:xxx"
        visibility TEXT,                 -- private | shared | org | public
        content TEXT,
        source JSON,
        eval JSON,
        embedding VECTOR(1536),          -- 向量检索
        created_at TIMESTAMP,
        updated_at TIMESTAMP
    );

    -- 索引
    CREATE INDEX idx_type ON knowledge(type);
    CREATE INDEX idx_owner ON knowledge(owner);
    CREATE INDEX idx_visibility ON knowledge(visibility);
    CREATE INDEX idx_scopes ON knowledge USING GIN(scopes);

文件系统结构
    /workspace/knowledge/
    ├── global/                   # 全局知识
    │   ├── tools.json
    │   ├── definitions.json
    │   └── plans.json
    │
    ├── agents/                   # Agent 经验
    │   ├── general_assistant/
    │   ├── crawler_ops/
    │   └── ...
    │
    └── users/                    # 用户画像
        ├── user_123/
        │   ├── profile.json      # 基础信息
        │   ├── preferences.json  # 偏好
        │   ├── habits.json       # 习惯
        │   └── constraints.json  # 约束
        └── ...

TODO

1. 实现知识存储接口（agent/memory/knowledge_store.py）
2. 实现知识检索逻辑（agent/memory/knowledge_retriever.py）
3. 实现 get_knowledge 工具（agent/tools/builtin/knowledge.py）
4. 实现 save_knowledge 工具（agent/tools/builtin/knowledge.py）
5. 在 Agent 启动时集成知识检索
6. 在 Goal focus 时集成知识检索
7. 在压缩消息时集成知识提取
8. 实现用户画像的特殊处理逻辑