- 产生知识时区分：人、场景（例如飞书群，可以对应到tags）、业务（还有子业务）

**知识结构**（单条知识）
    id: 知识唯一标识
    task: 任务描述，什么场景、在做什么

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

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

    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/tools/builtin/knowledge.py: 知识管理工具（KnowHub API 封装）+ KnowledgeConfig
        - agent/tools/builtin/knowledge.py: knowledge_search / knowledge_save 工具
知识提取机制
    触发时机
        - 主动表达：用户明确表达偏好、纠正、提供背景信息
        - 任务完成：任务完成后的反思总结
        - 压缩消息：在压缩消息节点提取经验
        - 用户反馈：用户对结果的 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: knowledge_save 工具
用户画像特殊处理
    用户画像是一种特殊的知识类型（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. ~~实现知识存储接口~~ → 已通过 KnowHub API 实现（agent/tools/builtin/knowledge.py）
    2. ~~实现知识检索逻辑~~ → knowledge_search 工具
    3. ~~实现 knowledge_save 工具~~ → 已实现
    4. ~~实现 knowledge_search 工具~~ → 已实现
    5. ~~在 Agent 启动时集成知识检索~~ → 已实现（goal focus 时注入）
    6. ~~在 Goal focus 时集成知识检索~~ → 已实现（agent/trace/goal_tool.py:inject_knowledge_for_goal）
    7. ~~在压缩消息时集成知识提取~~ → 已实现（agent/core/runner.py:_run_reflect）
    8. 实现用户画像的特殊处理逻辑