首頁 探索 說明
登入
howard
/
Agent
1
0
複刻 0
檔案 問題管理 0 合併請求 0 Wiki
分支: supeng-dev
分支列表 標籤列表
Agent
/
knowhub
/
docs
/
decisions.md

decisions.md 8.7 KB
永久連結 文件歷史 原始文件

KnowHub 决策记录

记录设计过程中的关键决策及推演依据。

0. Resource存储系统：分离公开/敏感内容

日期：2026-03-06

背景：用户需要存储有价值的工具资源，包括：

  • 复杂代码片段
  • 特定网站的账号密码
  • 登录状态的Cookie（含获取时间）

问题：

  • 原有resources表只有body字段，明文存储不安全
  • 如果整体加密，会失去搜索能力
  • 缺少元数据（获取时间、过期时间、内容类型）

决策：扩展resources表，分离公开/敏感内容

  • body: 公开内容（明文，可搜索）
  • secure_body: 敏感内容（AES-256-GCM加密）
  • content_type: 内容类型（text|code|credential|cookie）
  • metadata: JSON元数据（language, acquired_at, expires_at）

加密机制：

  • 使用AES-256-GCM加密
  • 密钥从环境变量ORG_KEYS读取（格式：org1:key1_base64,org2:key2_base64）
  • resource_id前缀决定使用哪个组织密钥（如test/tools/...使用test的密钥）
  • 访问时需提供X-Org-Key头，验证通过才解密

实现位置：knowhub/server.py

  • encrypt_resource(): 加密函数
  • decrypt_resource(): 解密函数
  • POST /api/resource: 提交资源
  • GET /api/resource/{id}: 获取资源（支持X-Org-Key头）
  • PATCH /api/resource/{id}: 更新资源
  • GET /api/resource: 列出资源

文档：knowhub/docs/resource-storage.md

1. 定位：经验层而非工具目录

背景：调研发现现有生态（详见 docs/knowledge/）已充分覆盖工具发现：

已解决的问题 谁在做
工具有哪些 Glama（17k+ MCP）、Smithery（125k+ Skills）、awesome-mcp-servers（81k Stars）
哪个热门 Smithery 安装量排行、Glama 下载量
静态质量指标 Glama 质量评分、GitHub Stars、License
安装方式 Smithery CLI、npx、pip/uvx
在线测试 Glama MCP Inspector

缺失：Agent 在特定任务中使用工具后的真实体验。

决策：KnowHub 不做工具目录，只做经验层。发现交给现有平台，KnowHub 收集"用了之后怎么样"。

2. 核心实体：experience 而非 tool

曾考虑的方案：三张表（tools + reports + reviews），以 tool 为中心。

问题：

  • tools 表复制 Glama/Smithery 已有的目录
  • reports（调研发现）的价值有限——Agent 的调研结论不比 Glama 的质量评分更可靠
  • 只有 reviews（实际使用评价）是独有价值

关键洞察：Agent 的问题不是"pymupdf 怎么样"（工具中心），而是"我要从 PDF 提取表格，谁做过"（任务中心）。

决策：单一实体 experience（任务 + 工具 + 结果 + 建议）。工具信息从 experiences 中按 tool_name 聚合得出，不单独维护。取消 reports——没用过不评价。

3. 搜索：任务驱动

决策：LIKE 拆词搜索 task + tips + outcome + name 字段，结果按 name 分组，每组返回相关 experiences 和聚合分数。

Server 只做检索 + GROUP BY，不做智能处理。Agent 拿到 JSON 后自行判断。体现"端侧算力"原则。

搜索范围：仅命中 experience。Content 是 experience 的深入层，通过 resource_id 关联获取，不参与搜索。如果后续发现 content 中有大量有价值信息未被 experience 覆盖，再扩展搜索范围。

4. 接口：curl 直调 API（MVP）

曾考虑的方案：

方案 优势 劣势
CLI（mpk 命令） 封装 HTTP 调用，管理 agent_id 需要 pip install，多一个组件
MCP Server Agent 原生工具调用 需 MCP SDK + 本地进程，多一跳
curl 直调 API 零安装，Agent 和人都能用 命令略长，无本地状态管理

CLI 和 MCP 都在 HTTP API 外面包了一层。MVP 阶段这层封装提供的价值（agent_id 管理、输出格式化、错误处理）Agent 自身都能做。

决策：MVP 不做客户端，skill.md 直接引导 Agent 用 curl 调 API。CLI 和 MCP Server 作为后续接入方式。

5. skill.md：两条路径而非线性流程

曾考虑的方案：四步线性流程（查→找→评→报），发现渠道与查经验并列。

问题：有经验时不需要去外部平台找工具，经验中已包含工具名、URL 和使用建议。

决策：分叉流程——有结果直接用，无结果才 fallback 到外部平台。发现渠道从主流程降级为 fallback。

6. 冷启动：有机增长而非种子数据

曾考虑的方案：从调研成果导入精选工具目录作为种子数据。

问题：导入没有 experience 的工具条目和空数据库无区别。空壳结果反而降低信任感。

决策：数据库从零开始。冷启动路径：

  1. Agent 搜索 → 空结果
  2. skill.md 引导去 Smithery/PyPI 找工具
  3. Agent 使用后 POST /api/experience 上报
  4. 下一个 Agent 搜索时看到前人经验

空结果不是问题，假数据才是。加速冷启动通过运营（自己先用热门工具并提交真实经验），不通过技术手段。

7. 身份标识：可选 submitted_by

曾考虑的方案：

  • 自动生成 agent_id 持久化到本地文件 → 需要客户端组件
  • 要求注册/登录 → 摩擦太大
  • 要求邮箱 → 如何零成本获取？

决策：可选字段 submitted_by，自由格式（邮箱、用户名、团队名均可）。skill.md 建议用 git config user.email 自动填充——几乎所有开发者已配置，零额外设置。

内部项目设置后方便 debug 追溯；外部用户可不填，零摩擦。

8. 算力分布

工作 执行方 理由
搜索工具 Agent（Smithery/PyPI/GitHub） 利用 Agent 搜索和浏览器能力
评估工具质量 Agent Agent 有判断力
决定用哪个 Agent 结合经验 + 自身评估
总结使用经验 Agent LLM 能力
存储/检索/聚合 Server 简单 SQL 操作

Server 零 LLM 成本。

9. 资源范围：从工具扩展到一般性知识

背景：最初定位仅覆盖工具（mcp/skill/library/api）。但 Agent 的集体记忆不应限于工具——论文、博客、电子书、课程等知识资源同样有"用了之后怎么样"的经验价值。

决策：category 从工具类型扩展为资源类型（mcp | skill | library | api | paper | blog | book | course 等）。数据模型不变，只是语义范围扩大。字段从 tool_* 重命名为通用名（name / url / category）。

10. 触发条件：从"需要工具"到更广的场景

背景：skill.md 原始触发条件是"需要外部工具但不确定选哪个时"，将 KnowHub 限定为工具推荐器。

决策：扩展为更广的触发条件——遇到复杂任务、可能超出自身能力、多次失败、可能需要外部资源时。KnowHub 是 Agent 面对不确定性时的第一反应，不只是找工具时才想起来。

11. 内容层：按需积累而非预设结构

背景：Experience（tips/outcome）能承载一条经验的关键信息，但有些资源需要更深入的内容（论文章节、API 文档、书籍目录）。

曾考虑的方案：

  • 固定三层结构（experience → resource detail → sections）：预设层级，用 section_key 约定
  • 通用内容图：每个内容有 ID 和 body，可以引用其他内容

决策：通用的 contents 表，路径式 ID（pymupdf 或 pymupdf/find-tables），扁平二级结构（根 + 叶），body 为 Markdown。内容由 Agent 按需提交——没人需要的资源停留在 experience 层，高频使用的资源自然积累出完整内容。

内容格式：Markdown。Agent 原生理解 markdown，图片用 URL 引用，不存文件。Resonote 的 HTML + span_id 体系是为人类阅读设计的，KnowHub 不需要。

观测性：Server 记录搜索日志。Agent 对不存在内容的 GET 请求频率本身就是"需要更深内容"的信号。

12. KnowHub 与 Resonote：独立演进

背景：两者在内容处理上有潜在协同（内容去重、分析管线、向量检索）。曾讨论 Resonote 依赖 KnowHub 内容层。

分析：

  • Library 的 HTML + span_id + 虚拟切分管线对人类阅读有价值，对 Agent 也有潜在价值（精确引用、结构化内容）
  • 但 KnowHub 在 MVP 阶段，数据模型会频繁变动；Library 已稳定，不应因 KnowHub 迭代而受影响
  • 合并内容层的工程收益小于耦合成本

决策：两个项目独立推进。唯一预留的接口：两边使用相同的 content hash 方案（sha256），未来如果整合，内容去重天然可行。等 KnowHub 验证"集体记忆"方向后再讨论整合。