Agent/knowhub/docs/resource-storage.md

Resource 存储系统

概述

Resource 存储系统用于管理原始资源（代码片段、凭证、Cookie等），与 Knowledge 系统互补：

• Knowledge：结构化知识条目（任务场景 + 经验内容）
• Content：原始资源存储（代码、凭证、配置等）

Knowledge 可以通过 resource_id 引用 Content 资源。

---

数据结构

数据库表

实现位置：knowhub/server.py:init_db

CREATE TABLE resources (
    id            TEXT PRIMARY KEY,        -- 层级ID，如 "tools/selenium/login"
    title         TEXT DEFAULT '',
    body          TEXT NOT NULL,           -- 公开内容
    secure_body   TEXT DEFAULT '',         -- 敏感内容（加密存储）
    content_type  TEXT DEFAULT 'text',     -- text|code|credential|cookie
    metadata      TEXT DEFAULT '{}',       -- JSON: {language, acquired_at, expires_at}
    sort_order    INTEGER DEFAULT 0,
    submitted_by  TEXT DEFAULT '',
    created_at    TEXT NOT NULL,
    updated_at    TEXT DEFAULT ''
)

字段说明

• id: 层级标识符，支持路径格式（如 tools/selenium/login）
• title: 资源标题
• body: 公开内容（明文存储，可搜索）
• secure_body: 敏感内容（加密存储，需要组织密钥访问）
• content_type: 内容类型
  • text: 普通文本
  • code: 代码片段
  • credential: 账号密码
  • cookie: Cookie数据
• metadata: 元数据（JSON对象）
  • language: 代码语言（当 content_type=code）
  • acquired_at: 获取时间（ISO 8601格式）
  • expires_at: 过期时间（用于cookie）
• sort_order: 排序顺序（同级内容排序）
• submitted_by: 提交者标识
• created_at: 创建时间
• updated_at: 更新时间

---

加密机制

组织密钥

敏感内容使用 AES-256-GCM 加密，密钥从环境变量读取：

# .env
ORG_KEYS=org1:key1_base64,org2:key2_base64

每个 content 的 id 前缀决定使用哪个组织密钥（如 org1/tools/... 使用 org1 的密钥）。

加密存储格式

encrypted:AES256-GCM:{base64_encoded_data}

实现位置：knowhub/server.py:encrypt_resource, decrypt_resource

访问控制

读取包含 secure_body 的 content 时：

• 需要提供 X-Org-Key HTTP 头
• 验证通过后解密返回
• 验证失败返回 [ENCRYPTED] 占位符

---

API 端点

POST /api/content

提交新资源。

请求体：

{
  "id": "tools/selenium/login",
  "title": "Selenium登录代码",
  "body": "使用undetected_chromedriver绕过检测",
  "secure_body": "账号：xxx 密码：xxx",
  "content_type": "credential",
  "metadata": {
    "acquired_at": "2026-03-06T10:00:00Z"
  },
  "submitted_by": "user@example.com"
}

实现位置：knowhub/server.py:submit_resource

GET /api/content/{resource_id}

获取资源（支持层级路径）。

请求头（可选）：

X-Org-Key: your_org_key_here

响应：

{
  "id": "tools/selenium/login",
  "title": "Selenium登录代码",
  "body": "使用undetected_chromedriver绕过检测",
  "secure_body": "账号：xxx 密码：xxx",  // 有密钥时解密
  "content_type": "credential",
  "metadata": {
    "acquired_at": "2026-03-06T10:00:00Z"
  },
  "toc": {"id": "tools", "title": "工具集"},
  "children": [
    {"id": "tools/selenium/login", "title": "登录代码"}
  ]
}

实现位置：knowhub/server.py:get_resource

PATCH /api/content/{resource_id}

更新资源字段。

请求体（所有字段可选）：

{
  "title": "新标题",
  "body": "新的公开内容",
  "secure_body": "新的敏感内容",
  "metadata": {
    "expires_at": "2026-03-07T10:00:00Z"
  }
}

实现位置：knowhub/server.py:patch_resource

GET /api/content

列出所有资源（支持过滤）。

参数：

• content_type: 按类型过滤（可选）
• limit: 返回数量（默认100）

实现位置：knowhub/server.py:list_resources

---

使用场景

场景1：存储复杂代码

{
  "id": "code/selenium/undetected",
  "title": "Selenium绕过检测",
  "body": "import undetected_chromedriver as uc\n\ndriver = uc.Chrome()\n...",
  "content_type": "code",
  "metadata": {
    "language": "python"
  }
}

场景2：存储账号密码

{
  "id": "credentials/某网站",
  "title": "某网站登录凭证",
  "body": "使用方法：直接登录即可",
  "secure_body": "账号：user@example.com\n密码：SecurePass123",
  "content_type": "credential",
  "metadata": {
    "acquired_at": "2026-03-06T10:00:00Z"
  }
}

场景3：存储Cookie

{
  "id": "cookies/某网站",
  "title": "某网站Cookie",
  "body": "适用于：已登录状态的API调用",
  "secure_body": "session_id=abc123; auth_token=xyz789",
  "content_type": "cookie",
  "metadata": {
    "acquired_at": "2026-03-06T10:00:00Z",
    "expires_at": "2026-03-07T10:00:00Z"
  }
}

场景4：Knowledge引用Content

{
  "task": "登录某网站",
  "content": "使用Selenium + undetected_chromedriver绕过检测",
  "resource_id": "code/selenium/undetected",
  "secure_resource_id": "credentials/某网站"
}

---

层级结构

Content 通过 ID 路径实现树形组织：

tools/
├── selenium/
│   ├── login
│   └── scraping
└── api/
    └── requests

credentials/
├── 网站A
└── 网站B

cookies/
└── 网站A

获取 tools/selenium/login 时自动计算：

• TOC: 根节点 tools
• Children: 子节点列表
• Prev/Next: 同级节点导航

---

安全考虑

1. 加密存储：敏感内容使用 AES-256-GCM 加密
2. 访问控制：需要组织密钥才能解密
3. 密钥管理：密钥存储在环境变量，不入库
4. 审计日志：记录 submitted_by 和时间戳
5. 过期提醒：Cookie 可设置 expires_at

---

与 Knowledge 的关系

维度	Knowledge	Content
用途	结构化知识（经验、策略）	原始资源（代码、凭证）
存储	task + content 字段	body + secure_body 字段
搜索	语义搜索 + 质量排序	层级浏览
引用	可引用 resource_id	被 knowledge 引用
加密	不加密（或整体加密）	分离公开/敏感内容

---

实现位置

组件	文件路径
数据库表	knowhub/server.py:init_db
加密/解密	knowhub/server.py:encrypt_resource, decrypt_resource
POST /api/content	knowhub/server.py:submit_resource
GET /api/content/{id}	knowhub/server.py:get_resource
PATCH /api/content/{id}	knowhub/server.py:patch_resource
GET /api/content	knowhub/server.py:list_resources