doc: knowhub refine

examples/plan/huahua/analysis.json

@@ -1,98 +0,0 @@
-{
-  "category": {
-    "name": "户外白裙写生少女图文内容",
-    "traits": [
-      "文艺气质的女性主体（白裙、背影、专注姿态）",
-      "户外自然场景（草坪、树木、阳光）",
-      "艺术创作道具（画架、画布、调色板、颜料）",
-      "清新白绿配色基调",
-      "逆光/轮廓光 + 浅景深散景的梦幻氛围",
-      "画中画叙事结构（画布内容与现实互文）"
-    ],
-    "ai_challenges": [
-      "人物姿态一致性：需要精准还原背影、侧颜、蹲坐等多种姿态",
-      "材质质感还原：Impasto 厚涂颜料的杂乱色彩肌理与白裙纯净质感的反差",
-      "光影氛围营造：逆光散景效果需要精确的光照控制和景深模拟",
-      "道具结构准确性：画架、调色板等道具的结构细节容易失真",
-      "色彩一致性：白绿配色的饱和度平衡，避免过曝或偏色",
-      "叙事逻辑连贯：画中画结构需要画布内容与场景的逻辑呼应"
-    ],
-    "reasoning": "基于制作点权重分析，人物（84.5）和绘画工具（78.5）是核心元素，自然背景（74.0）次之；图片亮点中实质亮点（人物、颜料、道具）覆盖全部图片，形式亮点（配色、光影、画中画）针对特定图片；AI 还原挑战主要来自多元素协同控制（姿态 + 材质 + 光影 + 色彩）和精细质感表现（Impasto 颜料、白裙纹理）"
-  },
-  "highlight": [
-    {
-      "name": "人物文艺气质与姿态还原",
-      "description": "白裙女性的背影、侧颜、发丝细节、专注绘画姿态（站立/跪坐），需保持娴静美的文艺气质，头发棕色长发自然散落",
-      "reasoning": "权重最高（84.5）且覆盖全部 5 张图片，是实质亮点核心；姿态骨骼图（pose_skeleton）已提供精确控制信号，但气质表现需要参考图（character_asset）和精细 prompt 控制"
-    },
-    {
-      "name": "Impasto 厚涂颜料质感",
-      "description": "木质调色盘上堆积的厚重油画颜料，杂乱而鲜艳的色彩肌理，与白裙形成强烈视觉反差",
-      "reasoning": "专门针对 img_1 和 img_5 的实质亮点，调色板资产（palette_asset）提供质感参考；AI 生成容易平滑化处理，需要强调 Impasto 厚涂的立体感和色彩杂乱性"
-    },
-    {
-      "name": "白绿配色与森系基调",
-      "description": "高饱和度自然草木绿背景与纯白衣物形成鲜明对比，确立清新、自然、治愈的视觉基调",
-      "reasoning": "形式亮点，针对 img_1 和 img_4；色彩方案（color_scheme）提供精确配色数据；AI 生成容易出现色彩偏差或饱和度过高/过低"
-    },
-    {
-      "name": "逆光散景梦幻氛围",
-      "description": "温暖的逆光/轮廓光 + 大光圈浅景深虚化（Bokeh），背景呈现柔和散景，营造脱离现实的梦幻浪漫氛围",
-      "reasoning": "形式亮点，针对 img_2、img_3、img_5；光照散景分析（lighting_bokeh）提供数据支持；AI 生成容易忽略光照方向或散景效果不自然"
-    },
-    {
-      "name": "写生道具叙事组合",
-      "description": "画架、画布、画笔、白玫瑰在空间上的组合排列，通过具体实体展示人物活动内容，构建画面叙事背景",
-      "reasoning": "实质亮点，针对 img_3 和 img_4；画架资产（easel_asset）提供参考；道具之间的空间关系和比例容易出错"
-    },
-    {
-      "name": "画中画镜像互文结构",
-      "description": "画布上的内容与现实场景形成镜像或互文关系，通过现实与艺术创作的视觉呼应增加叙事深度",
-      "reasoning": "形式亮点，针对 img_1 和 img_2；需要同时控制画布内容和现实场景的对应关系，是最高级的叙事要求"
-    }
-  ],
-  "baseline": [
-    {
-      "name": "人物结构准确性",
-      "description": "人体比例、四肢结构、手部细节（持调色板/画笔动作）无畸形，姿态与骨骼图一致",
-      "why_critical": "做不好会导致人物扭曲、手指异常等'一眼假'问题，破坏整体可信度",
-      "reasoning": "人物权重最高（84.5），姿态骨骼图（pose_skeleton）已提供控制信号，但 AI 生成仍可能出现结构错误；手部动作（持物）是常见失败点"
-    },
-    {
-      "name": "白裙质感与褶皱自然度",
-      "description": "白色连衣裙的布料质感、褶皱走向符合重力和人体形态，无过度平滑或不自然纹理",
-      "why_critical": "白裙是视觉焦点之一，质感假会导致整体画面廉价感；权重 44.7 但贯穿全部图片",
-      "reasoning": "女性衣物单独列为制作点（44.7），但白裙作为人物的一部分影响整体观感；AI 生成容易出现塑料感或褶皱不自然"
-    },
-    {
-      "name": "画架结构透视正确",
-      "description": "画架的三脚架结构、画布框比例、透视关系符合物理规律，无扭曲变形",
-      "why_critical": "画架是核心道具（权重 67.67+60.97），结构错误会破坏场景可信度",
-      "reasoning": "画架与画布、画架与油画两个制作点合计权重超过 128；画架资产提供参考，但 AI 生成容易出现透视错误"
-    },
-    {
-      "name": "背景虚化层次合理",
-      "description": "前景（人物、道具）清晰，背景（树木、草地）有适当虚化，虚化程度符合景深逻辑",
-      "why_critical": "虚化不合理会导致画面扁平或焦点混乱，破坏梦幻氛围",
-      "reasoning": "光影散景是形式亮点（img_2/3/5），深度图（depth_map）提供控制信号；AI 生成容易出现虚化边界生硬或虚化程度不一致"
-    },
-    {
-      "name": "色彩饱和度平衡",
-      "description": "绿色背景饱和度适中偏高但不过曝，白色衣物保持纯净无偏色，颜料色彩鲜艳但不杂乱",
-      "why_critical": "色彩失衡会导致画面脏、灰或过曝，破坏清新基调",
-      "reasoning": "白绿配色是形式亮点，色彩方案提供数据；AI 生成容易出现色彩偏差或饱和度失控"
-    }
-  ],
-  "requirement_summary": [
-    "人物还原：基于 character_asset 参考图和 pose_skeleton 骨骼图，精准还原白裙女性的背影、侧颜、发丝细节和专注姿态（站立/跪坐），保持文艺气质",
-    "姿态控制：使用 pose_skeleton 中的 DWPose 骨骼图控制人物姿态，确保手部持物动作（调色板/画笔）自然准确",
-    "颜料质感：基于 palette_asset 中的 Impasto 厚涂参考图，还原调色板上杂乱而鲜艳的颜料肌理，与白裙形成视觉反差",
-    "道具组合：基于 easel_asset 参考图，还原画架、画布、画笔、白玫瑰的空间组合，确保结构透视正确",
-    "色彩控制：基于 color_scheme 中的色彩数据，精确控制白绿配色饱和度，保持清新森系基调",
-    "光影营造：基于 lighting_bokeh 中的光照分析数据，还原逆光/轮廓光效果和大光圈散景，营造梦幻氛围",
-    "景深控制：基于 depth_map 深度图，实现前景清晰、背景虚化的层次效果，虚化边界自然",
-    "结构控制：基于 edge_map 边缘图，确保人物、道具的结构轮廓准确",
-    "叙事连贯：针对 img_1 和 img_2，实现画布内容与现实场景的画中画互文关系",
-    "下限保障：确保人体结构无畸形、白裙质感自然、画架透视正确、色彩饱和度平衡、虚化层次合理"
-  ]
-}

examples/plan/xiaocong/analysis.json

@@ -1,94 +0,0 @@
-{
-  "category": {
-    "name": "AI 知识科普笔记风格海报",
-    "traits": [
-      "拟真纸张与笔记本实体作为视觉载体",
-      "手绘装饰与卡通图标中和科技主题枯燥感",
-      "结构化排版与导视建立清晰视觉秩序",
-      "语义化色彩高亮建立信息层级",
-      "知识可视化图表将抽象概念具象化"
-    ],
-    "ai_challenges": [
-      "纸张纹理与褶皱的真实感还原（避免塑料感）",
-      "手绘元素的自然笔触与不规则边缘（避免过于规整）",
-      "文字与背景的融合度（避免浮于表面）",
-      "多层元素的空间关系与阴影处理（避免扁平化）",
-      "色彩高亮的透明度与笔触边缘模糊效果"
-    ],
-    "reasoning": "基于制作亮点.md 中 6 组视觉亮点聚类（3 个实质 +3 个形式），以及制作点.md 中权重排序（核心英文单词 87.3、背景 59.2、回形针装饰 48.7），判断该品类为'AI 知识科普笔记风格海报'，核心特征是用拟真笔记本场景包装科技知识内容"
-  },
-  "highlight": [
-    {
-      "name": "拟真纸张纹理与褶皱",
-      "description": "米白色纸张背景（RGB:245,245,235）带有横向浅灰色细线、不规则褶皱和轻微脏污感，模拟真实笔记本纸张的物理质感",
-      "reasoning": "制作亮点中'拟真纸张与笔记本实体'聚类描述强调'真实触感的书写介质'，制作点中'背景'权重 59.2 且出现在 3 张图片中，是视觉基础；做不好会导致画面缺乏真实感、一眼假"
-    },
-    {
-      "name": "核心英文单词的视觉突出",
-      "description": "页面中心位置的大号英文单词（如'Embedding'，约 90-100pt），采用粗体无衬线字体，颜色突出（蓝色 RGB:60,140,220 或黑色），位于彩色背景块或视觉焦点位置",
-      "reasoning": "制作点中'核心英文单词'权重 87.3 为最高，出现在全部 4 张图片的段落中（段落 1.3.3、2.2.2、3.2.2、4.2.2），是每张图的视觉焦点和信息核心"
-    },
-    {
-      "name": "手绘装饰元素的自然笔触",
-      "description": "星星、花朵、笑脸等手绘涂鸦元素，具有不规则边缘和自然笔触感，颜色柔和（粉色五角星、黄色四角星、四瓣花朵），分布在画面四角作为装饰",
-      "reasoning": "制作亮点中'手绘装饰与卡通图标'聚类描述强调'中和科技主题的枯燥感'，在 img_1 中明确出现于左上角和右下角，是营造轻松氛围的关键元素"
-    },
-    {
-      "name": "结构化排版与层级导视",
-      "description": "居中堆叠的标题层级（主标题→副标题→核心词）、虚线分隔、列表缩进、表格对齐等排版手段，建立严谨清晰的视觉秩序",
-      "reasoning": "制作亮点中'结构化排版与导视'聚类描述强调'将复杂信息拆解为易于消化的模块'，在 img_2 中体现为问题标题序号 + 正文 + 表格的层级结构"
-    },
-    {
-      "name": "语义化色彩高亮标记",
-      "description": "模拟荧光笔触的彩色标记（如粉色涂抹区域 RGB:255,180,200、蓝色高亮文字#4682B4），用于强调关键术语，边缘模糊具有手绘感",
-      "reasoning": "制作亮点中'语义化色彩高亮'聚类描述强调'建立清晰的信息层级'，在 img_1 中体现为'AI 知识点'下方的粉色涂抹，在 img_2 中体现为关键术语的蓝色高亮"
-    },
-    {
-      "name": "拟物化装饰元素（回形针/螺旋圈）",
-      "description": "页面边缘的蓝色或黄色回形针形状装饰（具有立体感和阴影），或螺旋笔记本的环形结构边缘，增强场景真实感",
-      "reasoning": "制作点中'回形针装饰'权重 48.7，出现在 img_2、img_3、img_4 中（段落 2.2.1、3.2.1、4.2.1），是营造'实体笔记本'场景感的关键道具"
-    }
-  ],
-  "baseline": [
-    {
-      "name": "纸张纹理的真实感",
-      "description": "背景必须呈现纸张特有的微纹理、横向细线和自然褶皱，颜色为米白色系，避免纯色或塑料质感",
-      "why_critical": "做不好会导致画面失去'笔记'的核心场景感，看起来像普通 PPT 或海报而非手写笔记，一眼假",
-      "reasoning": "制作点中'背景'权重 59.2 且是全部图片的基础层（段落 1.1、2.1、3.1、4.1），制作亮点中'拟真纸张与笔记本实体'和'拟物化笔记场景呈现'两个聚类都强调物理质感"
-    },
-    {
-      "name": "文字与背景的融合度",
-      "description": "文字必须与纸张背景有适当的融合效果（轻微阴影、透明度调整），避免浮于表面的贴图感",
-      "why_critical": "做不好会导致文字看起来是后期添加的数码字体，破坏'手写笔记'的真实感",
-      "reasoning": "制作表中文字字体多为'手写风格'字体，且与背景纹理共同出现，需要视觉融合；AI 生成常见问题是文字过于清晰锐利"
-    },
-    {
-      "name": "手绘元素的不规则性",
-      "description": "星星、花朵、涂抹区域等手绘元素必须具有不规则边缘和自然变化，避免几何完美和重复图案",
-      "why_critical": "做不好会导致装饰元素看起来像素材库贴图，失去'手绘'的亲切感和真实感",
-      "reasoning": "制作亮点中'手绘装饰与卡通图标'强调'手绘涂鸦元素'，制作表中描述'不规则的粉色涂抹区域，边缘模糊，模拟手绘涂抹效果'"
-    },
-    {
-      "name": "色彩高亮的透明度与边缘模糊",
-      "description": "荧光笔触效果必须具有半透明感和边缘模糊过渡，模拟真实荧光笔在纸张上的渗透效果",
-      "why_critical": "做不好会导致高亮区域看起来像纯色块填充，失去'荧光笔标记'的真实感",
-      "reasoning": "制作表中'涂抹颜色'描述为'粉色，边缘模糊，模拟手绘涂抹效果'，透明度是关键参数"
-    },
-    {
-      "name": "多层元素的空间关系",
-      "description": "回形针、螺旋圈等装饰元素必须与纸张有正确的遮挡关系和阴影投射，体现前后空间层次",
-      "why_critical": "做不好会导致画面扁平化，失去'实体笔记本'的立体感和场景沉浸感",
-      "reasoning": "制作点中'回形针装饰'描述为'具有立体感'，制作亮点中'拟物化笔记场景呈现'强调'边缘纹理和阴影处理'"
-    }
-  ],
-  "requirement_summary": [
-    "生成米白色纸张纹理背景（RGB:245,245,235），带有横向浅灰色细线、不规则褶皱和轻微脏污感",
-    "在页面中心位置生成大号英文单词（90-100pt，粗体无衬线字体），颜色突出（蓝色或黑色）",
-    "添加手绘风格的装饰元素（星星、花朵、笑脸），具有不规则边缘和自然笔触感，分布于画面四角",
-    "实现结构化排版：标题层级（主标题→副标题→核心词）居中堆叠，正文左对齐，表格居中对齐",
-    "添加语义化色彩高亮：荧光笔触效果（半透明、边缘模糊）用于强调关键术语",
-    "添加拟物化装饰元素（回形针或螺旋圈），具有立体感和正确阴影，与纸张有遮挡关系",
-    "确保文字与背景融合（轻微阴影、透明度调整），避免浮于表面的贴图感",
-    "所有手绘元素避免几何完美和重复图案，体现自然变化"
-  ]
-}

examples/research/config.py

@@ -32,11 +32,11 @@ RUN_CONFIG = RunConfig(
         enable_injection=True,
 
         # 默认字段（保存/搜索时自动注入）
-        owner="",  # 所有者（空则尝试从 git config user.email 获取，再空则用 agent:{agent_id}）
+        owner="sunlit.howard@gmail.com",  # 所有者（空则尝试从 git config user.email 获取，再空则用 agent:{agent_id}）
         default_tags={"project": "research", "domain": "ai_agent"},  # 默认 tags（会与工具调用参数合并）
         default_scopes=["org:cybertogether"],  # 默认 scopes
         default_search_types=["strategy"],  # 默认搜索类型过滤
-        default_search_owner="guantao,guantao@cybertogether.net"  # 默认搜索 owner 过滤（空则不过滤）
+        default_search_owner="sunlit.howard@gmail.com"  # 默认搜索 owner 过滤（空则不过滤）
     )
 )
 

examples/research/research.prompt

@@ -4,42 +4,12 @@ temperature: 0.3
 ---
 
 $system$
-
 ## 角色
-你是图像修复技术专家，擅长使用搜索工具查找和分析图像还原方法。
-
-**搜索策略**：
-1. 使用 browser 工具搜索相关关键词
-2. 分析搜索结果，提取可行的技术方案
-3. 评估每种方案的优缺点和适用场景
-
-**评估维度**：
-- 技术可行性
-- 所需工具/服务
-- 效果质量
-- 成本和难度
+你是社媒内容制作专家，擅长调研和分析内容制作的方法和工具。你尤其关注使用AI工具或获取网络资源来完成内容制作，避免实景拍摄。
 
-**输出** `%output_dir%/research_<round>.json`，schema 如下：
-
-```jsonschema
-{
-  "trace": "string — 搜索过程，包括使用的关键词、搜索结果概况等",
-  "methods": [
-    {
-      "name": "string — 方法名称",
-      "source": "string — 来源 URL",
-      "description": "string — 方法描述",
-      "tools_required": ["string — 需要的工具或服务"],
-      "pros": ["string — 优点"],
-      "cons": ["string — 缺点"],
-      "difficulty": "easy | medium | hard",
-      "cost": "free | paid | mixed"
-    }
-  ]
-}
-```
+## 任务
+你的任务是为指定的制作需求系统性搜索方法和工具。
 
 
 $user$
-
-请搜索如何还原一张人像图的方法和技术。可以尝试搜索"人像图修复"、"老照片还原"、"AI图像修复"等关键词。
+请帮我调研一下，如何生成一组美少女的摄影写真组图。

examples/research/run.py

@@ -58,7 +58,7 @@ async def main():
     base_dir = Path(__file__).parent
     project_root = base_dir.parent.parent
     prompt_path = base_dir / "research.prompt"
-    output_dir = base_dir / "output_1"
+    output_dir = base_dir / "output"
     output_dir.mkdir(exist_ok=True)
 
     # 1. 配置日志

knowhub/docs/feedback-optimization-proposal.md

@@ -0,0 +1,678 @@
+# 知识库反馈与管理机制优化提案
+
+> 本文档记录知识库反馈机制和规模管理的优化方案
+>
+> 讨论日期：2026-03-17
+> 状态：提案阶段，待审阅后实施
+
+---
+
+## 一、背景与问题
+
+### 1.1 当前反馈机制
+
+**现有结构**：
+- `eval` 字段：score (1-5), helpful/harmful 计数, confidence, 历史记录
+- 工具：`knowledge_update`, `knowledge_batch_update`
+- 应用：`min_score` 过滤、知识进化（`evolve_feedback`）
+
+**存在的问题**：
+1. 反馈来源不区分（人类、Agent、任务结果混在一起）
+2. 评分更新逻辑简单（手动设置，未根据反馈历史自动调整）
+3. 缺少隐式反馈（使用频率、检索排名等）
+4. 缺少时间衰减机制（旧知识可能过时）
+
+### 1.2 规模控制问题
+
+**现有 slim 机制的问题**：
+- 一次性加载 10000 条知识到内存
+- 单次 LLM 调用处理全部（成本高 $1-5/次，质量差）
+- 每条只截取前 200 字符，信息不完整
+
+**知识库膨胀原因**：
+1. 重复提取：相似任务多次执行，每次都提取"新"知识
+2. 粒度不一致：同一经验被拆成多条或合并成粗粒度
+3. 版本演化：知识更新时创建新版本而非覆盖旧版本
+4. 低质量沉积：score=3 的"中等"知识大量累积
+
+---
+
+## 二、核心优化方案
+
+### 2.1 保存时关系判断（P0 核心机制）
+
+#### 知识关系类型
+
+| 关系类型 | 说明 | 处理策略 |
+|---------|------|---------|
+| `duplicate` | 完全重复，只是表述略有差异 | 跳过保存 |
+| `subset` | 新知识是已有知识的特例或部分 | 跳过保存，或作为案例添加 |
+| `superset` | 新知识更全面，包含已有知识 | 保存新知识，废弃旧知识 |
+| `conflict` | 两条知识给出矛盾的建议 | 保存但标记冲突，需要人工审核 |
+| `complement` | 相关但不重复，可以互相补充 | 保存并建立关联关系 |
+| `independent` | 两条知识无关 | 直接保存 |
+
+#### 分层判断策略（降低成本）
+
+```
+Layer 1: 向量相似度检索（快速过滤）
+  ↓ 无相似知识 → 直接保存
+  ↓ 有相似知识
+Layer 2: 规则判断（免费）
+  - task 完全相同 + content 重叠 > 90% → 跳过
+  - content 完全相同 → 跳过
+  ↓ 规则无法判断
+Layer 3: LLM 判断（仅处理边界情况）
+  - 相似度 > 0.85 时才调用
+  - 使用 gemini-2.5-flash-lite
+```
+
+**成本估算**：
+- 假设每天保存 50 条知识
+- Layer 1 过滤 70%，Layer 2 过滤 20%，Layer 3 处理 10%
+- 每次 LLM 调用：1100 tokens
+- 年成本：50 × 10% × 1100 tokens × 365 天 ≈ **$0.15/年**
+
+#### 实现位置
+
+- `agent/tools/builtin/knowledge.py:knowledge_save` - 保存前检查
+- `knowhub/server.py:analyze_knowledge_relation` - 关系分析
+- `knowhub/server.py:handle_knowledge_relation` - 关系处理
+
+---
+
+### 2.2 反馈来源区分与加权评分（P0）
+
+#### 数据结构变更
+
+```python
+{
+  "eval": {
+    "score": 4.2,  # 加权综合评分（自动计算）
+    "confidence": 0.9,
+
+    # 分来源统计
+    "feedback_by_source": {
+      "human": {
+        "helpful": 3,
+        "harmful": 0,
+        "weight": 1.0,  # 权重最高
+        "last_feedback": "2026-03-17"
+      },
+      "agent_explicit": {
+        "helpful": 12,
+        "harmful": 2,
+        "weight": 0.6,  # 中等权重
+        "last_feedback": "2026-03-17"
+      },
+      "task_outcome": {
+        "success": 45,
+        "failure": 5,
+        "weight": 0.3,  # 权重最低（归因不明确）
+        "last_feedback": "2026-03-17"
+      }
+    },
+
+    # 详细历史（保留来源标记）
+    "feedback_history": [
+      {
+        "source": "human",
+        "type": "helpful",
+        "comment": "非常准确",
+        "timestamp": "2026-03-17",
+        "user_id": "user@example.com"
+      }
+    ]
+  }
+}
+```
+
+#### 加权评分算法
+
+```python
+def calculate_weighted_score(feedback_by_source):
+    """根据来源加权计算综合评分"""
+
+    total_weight = 0
+    weighted_sum = 0
+
+    for source, data in feedback_by_source.items():
+        helpful = data["helpful"]
+        harmful = data["harmful"]
+        weight = data["weight"]
+
+        if helpful + harmful == 0:
+            continue
+
+        # 正向率
+        positive_ratio = helpful / (helpful + harmful)
+
+        # 置信度：反馈次数越多越可信（上限10次）
+        confidence = min(1.0, (helpful + harmful) / 10)
+
+        # 该来源的得分：3 + 2 * (正向率 - 0.5)
+        source_score = 3 + 2 * (positive_ratio - 0.5)
+
+        # 加权累加
+        weighted_sum += source_score * weight * confidence
+        total_weight += weight * confidence
+
+    return max(1.0, min(5.0, weighted_sum / total_weight)) if total_weight > 0 else 3.0
+```
+
+#### 实现位置
+
+- `knowhub/server.py:update_knowledge` - 更新评分逻辑
+- `knowhub/server.py:calculate_weighted_score` - 评分计算
+- `agent/tools/builtin/knowledge.py:knowledge_feedback` - 新增人类反馈工具
+
+---
+
+### 2.3 分层存储（P0 必需）
+
+#### 知识状态机
+
+```
+active（活跃）→ stable（稳定）→ cold（冷藏）→ archived（归档）
+                                    ↓
+                              deprecated（废弃）
+```
+
+#### 状态转换规则
+
+```python
+def calculate_state(knowledge):
+    days_since_last_use = (now - knowledge["last_used"]).days
+    usage_count = knowledge["implicit_feedback"]["search_count"]
+
+    if days_since_last_use > 180 and usage_count < 5:
+        return "archived"  # 半年未用且使用少 → 归档
+    elif days_since_last_use > 90:
+        return "cold"      # 3个月未用 → 冷藏
+    elif usage_count > 20:
+        return "active"    # 使用频繁 → 活跃
+    else:
+        return "stable"    # 默认稳定
+```
+
+#### 检索策略
+
+- 默认只检索 `active` + `stable`
+- 可选参数 `include_cold=true` 扩展到冷藏知识
+- `archived` 和 `deprecated` 不参与检索，但可通过 ID 访问
+
+#### 数据结构
+
+```python
+{
+  "state": "active",  # active/stable/cold/archived/deprecated
+  "state_reason": "",  # 状态变更原因
+  "state_updated_at": "2026-03-17T12:00:00Z"
+}
+```
+
+#### 实现位置
+
+- `knowhub/server.py:update_knowledge_states` - 后台任务，每天更新
+- `knowhub/server.py:search_knowledge_api` - 检索时过滤状态
+- `knowhub/vector_store.py` - Milvus 查询添加状态过滤
+
+---
+
+### 2.4 质量淘汰（P0 必需）
+
+#### 淘汰条件
+
+- `score < 2`
+- `harmful > helpful`
+- 存在超过 30 天
+
+#### 操作
+
+标记为 `deprecated`，不直接删除（可恢复）
+
+#### 实现
+
+```python
+async def prune_low_quality():
+    """定期清理低质量知识"""
+
+    low_quality = milvus_store.query(
+        filter_expr='eval["score"] < 2 and eval["harmful"] > eval["helpful"]'
+    )
+
+    for k in low_quality:
+        age_days = (now - k["created_at"]).days
+        if age_days > 30:
+            await knowledge_update(
+                knowledge_id=k["id"],
+                metadata={
+                    "state": "deprecated",
+                    "state_reason": "low_quality",
+                    "deprecated_at": now
+                }
+            )
+```
+
+#### 实现位置
+
+- `knowhub/server.py:prune_low_quality` - 后台任务，每天执行
+
+---
+
+### 2.5 知识关系网络（P0）
+
+#### 数据结构
+
+```python
+{
+  "relations": [
+    {
+      "target_id": "knowledge-20260310-c3d4",
+      "relation_type": "complement",  # duplicate/subset/superset/conflict/complement
+      "direction": "bidirectional",   # bidirectional/outgoing/incoming
+      "confidence": 0.95,
+      "reason": "两条知识互补，分别覆盖不同场景",
+      "created_at": "2026-03-17T12:00:00Z",
+      "created_by": "system",  # system/human/agent
+      "action_taken": ""  # 可选：deprecated_target/merged/etc
+    }
+  ]
+}
+```
+
+#### 关系方向说明
+
+| 关系类型 | 方向性 | 说明 |
+|---------|--------|------|
+| `complement` | 双向 | 互补关系，建立双向链接 |
+| `duplicate` | 双向 | 完全重复 |
+| `subset` | 单向 | 本知识是目标的子集 |
+| `superset` | 单向 | 本知识是目标的超集 |
+| `conflict` | 双向 | 冲突关系 |
+
+#### 实现位置
+
+- `knowhub/server.py:create_knowledge_link` - 创建关系链接
+- `knowhub/server.py:get_related_knowledge` - 查询相关知识
+
+---
+
+### 2.6 轻量级健康检查（P1 推荐）
+
+#### 目的
+
+检测保存时去重的漏判（兜底机制）
+
+#### 策略
+
+```python
+async def weekly_health_check():
+    """每周检查新增知识的重复情况"""
+
+    # 只检查最近7天新增的知识
+    recent = query(filter=f'created_at > "{seven_days_ago}"')
+
+    if len(recent) < 10:
+        return  # 新增太少，不值得检查
+
+    # 使用向量聚类检测明显重复（阈值 0.90）
+    clusters = await cluster_similar_knowledge(
+        knowledge_list=recent,
+        threshold=0.90
+    )
+
+    # 只报告，不自动处理
+    if clusters:
+        send_alert(f"发现 {len(clusters)} 组疑似重复，请人工审核")
+```
+
+#### 成本
+
+几乎为 0（只用向量聚类，不调用 LLM）
+
+#### 实现位置
+
+- `knowhub/server.py:weekly_health_check` - 后台任务，每周执行
+
+---
+
+## 三、可选优化（P2）
+
+### 3.1 隐式反馈收集
+
+```python
+{
+  "implicit_feedback": {
+    "search_count": 156,      # 被检索次数
+    "click_count": 89,        # 被选中使用次数
+    "last_used": "2026-03-17",
+    "avg_rank": 2.3           # 平均检索排名
+  }
+}
+```
+
+**实现位置**：`knowhub/server.py:search_knowledge_api` - 返回结果时记录
+
+### 3.2 时间衰减机制
+
+```python
+def apply_time_decay(knowledge, current_time):
+    age_days = (current_time - knowledge["created_at"]).days
+
+    # 6个月后开始衰减，1年后降至50%
+    if age_days > 180:
+        decay_factor = max(0.5, 1 - (age_days - 180) / 365)
+        knowledge["_search_score"] *= decay_factor
+
+    return knowledge
+```
+
+**实现位置**：`knowhub/server.py:_llm_rerank` - 精排前应用衰减
+
+### 3.3 多维度反馈
+
+```python
+{
+  "eval": {
+    "dimensions": {
+      "accuracy": 5,      # 准确性
+      "completeness": 4,  # 完整性
+      "clarity": 4,       # 清晰度
+      "timeliness": 3     # 时效性
+    }
+  }
+}
+```
+
+### 3.4 归因置信度
+
+对于任务成功/失败反馈，计算"这个结果有多大程度归因于该知识"：
+
+```python
+async def calculate_attribution_confidence(
+    knowledge_id: str,
+    task_result: dict
+) -> float:
+    """计算归因置信度"""
+
+    # 因素1：该知识在任务中的使用程度
+    usage_ratio = task_result["knowledge_usage"][knowledge_id] / task_result["total_steps"]
+
+    # 因素2：是否是唯一使用的知识
+    is_only_knowledge = len(task_result["used_knowledge_ids"]) == 1
+
+    # 因素3：失败时的错误类型
+    if task_result["status"] == "failed":
+        error_type = task_result["error_type"]
+        if error_type in ["network", "timeout", "rate_limit"]:
+            return 0.2  # 环境问题，归因置信度低
+        elif error_type in ["logic_error", "wrong_output"]:
+            return 0.9  # 逻辑问题，归因置信度高
+
+    # 综合计算
+    if is_only_knowledge:
+        return 0.9
+    else:
+        return 0.3 + 0.6 * usage_ratio
+```
+
+**实现位置**：`agent/core/runner.py` - 任务完成回调
+
+### 3.5 质量仪表盘
+
+```python
+@app.get("/api/knowledge/stats")
+async def knowledge_stats():
+    """知识库质量统计"""
+    return {
+        "total": 1234,
+        "by_score": {5: 234, 4: 567, 3: 345, 2: 67, 1: 21},
+        "by_state": {"active": 800, "stable": 300, "cold": 100, "archived": 34},
+        "low_quality": [...],      # score < 3 的知识列表
+        "stale": [...],            # 6个月未使用的知识
+        "top_helpful": [...],      # helpful 最多的知识
+        "needs_review": [...],     # harmful > helpful 的知识
+        "conflicts": [...]         # 标记为冲突的知识对
+    }
+```
+
+### 3.6 改进 slim v2（按需执行）
+
+使用聚类 + 分批处理，替换现有的一次性加载方案：
+
+```python
+@app.post("/api/knowledge/slim")
+async def slim_knowledge_v2(
+    batch_size: int = 100,
+    similarity_threshold: float = 0.85,
+    model: str = "google/gemini-2.5-flash-lite"
+):
+    """知识库瘦身 v2：分批聚类合并"""
+
+    # 1. 聚类相似知识（只用向量，不用 LLM）
+    clusters = await cluster_similar_knowledge(
+        similarity_threshold=similarity_threshold
+    )
+
+    # 2. 对每个聚类调用 LLM 判断（分批处理）
+    merged_count = 0
+    for cluster in clusters:
+        knowledge_list = [milvus_store.get_by_id(kid) for kid in cluster]
+
+        # 只处理这个聚类的 2-5 条知识
+        decision = await llm_merge_cluster(knowledge_list, model)
+
+        if decision["should_merge"]:
+            await execute_merge(decision)
+            merged_count += 1
+
+    return {"clusters_found": len(clusters), "merged": merged_count}
+```
+
+**成本**：~$0.5/次（按需执行）
+
+---
+
+## 四、实施优先级与成本
+
+### P0（立即实施）
+
+| 机制 | 成本 | 实现位置 |
+|------|------|---------|
+| 保存时关系判断 | $0.15/年 | `agent/tools/builtin/knowledge.py:knowledge_save` |
+| 反馈来源区分 | $0 | `knowhub/server.py:update_knowledge` |
+| 分层存储 | $0 | `knowhub/server.py` + `knowhub/vector_store.py` |
+| 质量淘汰 | $0 | `knowhub/server.py:prune_low_quality` |
+| 知识关系网络 | $0 | `knowhub/server.py` |
+
+**P0 总成本**：~$0.15/年
+
+### P1（短期实施）
+
+| 机制 | 成本 | 实现位置 |
+|------|------|---------|
+| 轻量级健康检查 | ~$0 | `knowhub/server.py:weekly_health_check` |
+| 归因置信度 | $0 | `agent/core/runner.py` |
+
+### P2（按需实施）
+
+| 机制 | 成本 | 备注 |
+|------|------|------|
+| 隐式反馈收集 | $0 | 可选 |
+| 时间衰减机制 | $0 | 可选 |
+| 多维度反馈 | $0 | 可选 |
+| 质量仪表盘 | $0 | 可选 |
+| 改进 slim v2 | $0.5/次 | 按需执行 |
+| 定期全量去重 | $10-20/次 | 仅在保存时去重误判率 > 5% 时需要 |
+
+---
+
+## 五、关键设计原则
+
+1. **实时防御优于事后清理**：保存时去重比定期去重更有效
+2. **分层判断降低成本**：向量 → 规则 → LLM，只在必要时用 LLM
+3. **反馈来源加权**：人类 (1.0) > Agent (0.6) > 任务结果 (0.3)
+4. **知识关系网络**：通过 `relations` 字段建立知识图谱
+5. **生命周期管理**：通过 `state` 字段管理知识的可见性
+6. **质量驱动淘汰**：基于反馈自动清理低质量知识
+
+---
+
+## 六、完整数据结构
+
+```python
+{
+  # 现有字段
+  "id": "knowledge-20260317-a1b2",
+  "message_id": "msg-xxx",
+  "types": ["strategy", "tool"],
+  "task": "在什么场景下要完成什么目标",
+  "content": "核心知识内容",
+  "tags": {"category": "preference"},
+  "scopes": ["org:cybertogether"],
+  "owner": "agent:research_agent",
+  "resource_ids": ["code/selenium/login"],
+  "source": {
+    "name": "资源名称",
+    "category": "exp",
+    "urls": ["https://example.com"],
+    "agent_id": "research_agent",
+    "submitted_by": "user@example.com",
+    "timestamp": "2026-03-17T12:00:00Z",
+    "message_id": "msg-xxx"
+  },
+
+  # 改进的评估字段
+  "eval": {
+    "score": 4.2,  # 加权综合评分（自动计算）
+    "confidence": 0.9,
+    "feedback_by_source": {
+      "human": {"helpful": 3, "harmful": 0, "weight": 1.0, "last_feedback": "2026-03-17"},
+      "agent_explicit": {"helpful": 12, "harmful": 2, "weight": 0.6, "last_feedback": "2026-03-17"},
+      "task_outcome": {"success": 45, "failure": 5, "weight": 0.3, "last_feedback": "2026-03-17"}
+    },
+    "feedback_history": [
+      {
+        "source": "human",
+        "type": "helpful",
+        "comment": "非常准确",
+        "timestamp": "2026-03-17T12:00:00Z",
+        "user_id": "user@example.com"
+      }
+    ]
+  },
+
+  # 新增：隐式反馈（P2 可选）
+  "implicit_feedback": {
+    "search_count": 156,
+    "click_count": 89,
+    "last_used": "2026-03-17",
+    "avg_rank": 2.3
+  },
+
+  # 新增：知识关系（P0）
+  "relations": [
+    {
+      "target_id": "knowledge-xxx",
+      "relation_type": "complement",
+      "direction": "bidirectional",
+      "confidence": 0.95,
+      "reason": "两条知识互补，分别覆盖不同场景",
+      "created_at": "2026-03-17T12:00:00Z",
+      "created_by": "system",
+      "action_taken": ""
+    }
+  ],
+
+  # 新增：知识状态（P0）
+  "state": "active",  # active/stable/cold/archived/deprecated
+  "state_reason": "",
+  "state_updated_at": "2026-03-17T12:00:00Z",
+
+  "created_at": "2026-03-17T12:00:00Z",
+  "updated_at": "2026-03-17T12:00:00Z"
+}
+```
+
+---
+
+## 七、实施路线图
+
+### 阶段 1：核心机制（1-2周）
+
+1. 修改知识数据结构（添加 `relations`, `state`, `feedback_by_source`）
+2. 实现保存时关系判断
+3. 实现反馈来源区分与加权评分
+4. 实现分层存储
+5. 实现质量淘汰
+
+### 阶段 2：监控与优化（1周）
+
+6. 实现轻量级健康检查
+7. 实现归因置信度
+8. 观察运行效果，调整参数
+
+### 阶段 3：增强功能（按需）
+
+9. 隐式反馈收集
+10. 时间衰减机制
+11. 多维度反馈
+12. 质量仪表盘
+13. 改进 slim v2
+
+---
+
+## 八、风险与缓解
+
+### 风险 1：LLM 判断误判
+
+**影响**：可能误判为 duplicate 导致丢失有用知识
+
+**缓解**：
+- 使用分层判断，只在边界情况用 LLM
+- 设置置信度阈值，低于 0.8 时降级到更好的模型
+- 轻量级健康检查作为兜底
+
+### 风险 2：关系网络复杂度
+
+**影响**：知识关系可能形成复杂网络，难以维护
+
+**缓解**：
+- 初期只建立必要的关系（complement, conflict）
+- 提供可视化工具查看关系图
+- 定期清理无效关系
+
+### 风险 3：状态转换过于激进
+
+**影响**：有用的知识可能被过早归档
+
+**缓解**：
+- 保守的阈值设置（180天才归档）
+- 归档的知识仍可通过 ID 访问
+- 提供恢复接口
+
+---
+
+## 九、成功指标
+
+### 定量指标
+
+- 知识库增长率：从当前 X 条/月降至 Y 条/月
+- 重复率：新增知识中重复率 < 5%
+- 低质量知识占比：score < 3 的知识 < 10%
+- 归档知识占比：archived 状态 < 20%
+
+### 定性指标
+
+- Agent 检索到的知识更相关
+- 知识质量反馈更准确
+- 知识库维护成本降低
+
+---
+
+## 十、参考资料
+
+- 现有知识管理文档：`knowhub/docs/knowledge-management.md`
+- 决策记录：`knowhub/docs/decisions.md`
+- 资源存储文档：`knowhub/docs/resource-storage.md`