Agent/knowhub/skill/openclaw-plugin/IMPLEMENTATION.md

OpenClaw KnowHub 插件实现总结

已完成的文件

knowhub/skill/openclaw-plugin/
├── package.json              # 包配置
├── openclaw.plugin.json      # 插件元数据和配置 schema
├── tsconfig.json             # TypeScript 配置
├── index.ts                  # 主插件代码 (约 500 行)
├── index.test.ts             # 基础测试
├── README.md                 # 使用文档
└── config-examples.md        # 配置示例

核心功能

1. 工具实现 (3个)

• kb_search: 搜索 KnowHub 知识

  • 参数: query, top_k, min_score, types
  • 返回格式化的搜索结果
  • 支持类型过滤

• kb_save: 保存知识到 KnowHub

  • 参数: task, content, types, score, source_name, source_urls
  • 自动填充 agent_id, submitted_by
  • 参数验证（score 1-5）

• kb_update: 更新知识反馈

  • 参数: knowledge_id, is_helpful, feedback
  • 支持 helpful/harmful 两种反馈

2. 钩子实现 (3个)

• before_agent_start: 初始提醒

  • 注入工具说明和使用建议
  • 可通过 reminderMode=off 关闭

• before_prompt_build: 定期提醒

  • 每 N 次 LLM 调用注入提醒
  • 频率可配置 (minimal=5, normal=3, aggressive=2)

• agent_end: 状态清理 + 服务端提取

  • 清理会话计数器
  • 可选的消息历史上传（enableServerExtraction）

3. 安全防护

• Prompt Injection 检测: 4 种模式检测
• 内容转义: HTML 实体转义
• 数据脱敏: 路径、邮箱、API Key、IP 等
• 隐私模式: strict/relaxed 两种模式

4. 配置管理

• 6 个配置选项，全部有默认值
• 配置验证（apiUrl 必需）
• UI 提示和帮助文本

API 对齐

完全对齐 knowledge-management.md 的数据结构：

插件工具	API 端点	字段
kb_search	GET /api/knowledge/search	query, top_k, min_score, types
kb_save	POST /api/knowledge	task, content, types, score, source, scopes, owner
kb_update	PUT /api/knowledge/{id}	add_helpful_case / add_harmful_case

提醒文本

对齐 SKILL.md 的触发条件：

• 查询时机: 遇到复杂任务、不确定用什么工具、多次失败时
• 保存时机: 使用资源后、获得用户反馈后、搜索过程有发现时
• 反馈时机: 使用知识后

使用方式

安装

1. 将 openclaw-plugin 目录放到 OpenClaw 可访问的位置
2. 在 ~/.openclaw/config.json 中配置插件

最小配置

{
  "plugins": {
    "entries": {
      "knowhub": {
        "enabled": true,
        "config": {
          "apiUrl": "http://43.106.118.91:9999",
          "submittedBy": "user@example.com"
        }
      }
    }
  }
}

Agent 使用

Agent 启动后会看到初始提醒，然后可以：

1. 搜索知识: kb_search({ query: "..." })
2. 保存知识: kb_save({ task: "...", content: "...", types: [...] })
3. 反馈知识: kb_update({ knowledge_id: "...", is_helpful: true })

每 3 次 LLM 调用会收到一次提醒。

测试

基础测试覆盖：

• Prompt injection 检测
• HTML 转义
• 数据脱敏
• 提醒间隔计算

运行测试（需要先安装依赖）：

cd knowhub/skill/openclaw-plugin
pnpm install
pnpm test

下一步

1. 测试: 在实际 OpenClaw 环境中测试插件
2. 调试: 根据实际使用情况调整提醒频率和文本
3. 优化: 根据反馈优化工具参数和错误处理
4. 文档: 补充更多使用示例和故障排查指南

注意事项

• 插件依赖 @sinclair/typebox 和 openclaw/plugin-sdk/core
• 需要 KnowHub Server 运行在配置的 apiUrl
• 服务端提取功能需要 Server 实现 /api/extract 端点
• 测试文件需要导出的函数已经标记为 export