# 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` 中配置插件

### 最小配置

```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 转义
- 数据脱敏
- 提醒间隔计算

运行测试（需要先安装依赖）：
```bash
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