ht-skills 详解：OpenClaw 连接灏天文库的知识库自动化方案

让 AI 智能体自动管理你的灏天文库知识库

前言

ht-skills 是 OpenClaw 连接灏天文库的核心技能，它让 AI 智能体能够：

• ✍️ 自动写文章
• 📚 创建文集
• 📤 上传文档

这不仅仅是技术集成，更是 AI 自动化知识管理的最佳实践。

第一部分：技能概述

1.1 技能元数据

---
name: ht-skills
description: 管理灏天文库文集和文档，支持新建文集、新建文档、查询文集/文档、同步指定文档到 RAG
allowed-tools: [bash]
---

关键字段：

• name：技能名称，用于触发
• description：功能描述，AI 根据此判断何时使用
• allowed-tools：允许使用的工具（bash）

1.2 核心功能

1. 文集管理

   • 创建文集（含描述、简介）
   • 查询文集列表
   • 按名称搜索

2. 文档管理

   • 上传文档（Markdown 格式）
   • 更新文档
   • 查询文档列表
   • 按名称搜索

第二部分：技能结构

2.1 目录结构

ht-skills/
├── SKILL.md              # 技能元数据和指令
├── scripts/             # 可执行脚本
│   ├── api_client.py    # API 客户端封装
│   ├── create_collection.py
│   ├── add_document.py
│   ├── update_document.py
│   ├── list_collections.py
│   ├── get_collection.py
│   ├── list_documents.py
│   ├── get_document.py
├── references/          # 参考文档
│   └── README.md
└── config.json.example  # 配置模板

2.2 SKILL.md 详解

核心指令

# 灏天文库管理技能

## 核心功能

1. 新建文集（支持有则用、无则建）
2. 新建文档到指定文集
3. 查询文集列表（含按名称搜索）
4. 查询文集详情
5. 查询文档列表（支持按名称模糊搜索）
6. 查询文档详情
7. 更新文档（修订已发文章）

## 使用规范

### 规范一：修改特定文档

1. 先查询文档 ID
2. 再修改文档

### 规范二：添加特定文档

1. 文集必填
2. 查询文集 ID
3. 添加文档
4. 通知 RAG

### 规范三：添加文集

1. 用户确认
2. 确认后再执行

关键设计：

• 规范驱动：明确的使用规范，确保 AI 正确使用
• 用户确认：创建文集前需要确认

第三部分：脚本实现

3.1 API 客户端

核心类

class HaotianAPI:
    def __init__(self):
        self.base_url = "https://zzht.tech"
        self.api_key = os.environ["HT_API_KEY"]
        self.headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json"
        }

主要方法

def create_collection(self, name, description=None, brief=None):
    """创建文集"""
    
def add_document(self, collection_id, name, content):
    """添加文档"""
    
def update_document(self, document_id, **kwargs):
    """更新文档"""
    
def list_collections(self, name=None):
    """查询文集列表"""
    
def list_documents(self, collection_id=None, name=None):
    """查询文档列表"""

3.2 命令行工具

创建文集

python3 scripts/create_collection.py \\
  --name "文集名称" \\
  --description "简短描述" \\
  --brief "详细介绍"

上传文档

python3 scripts/add_document.py \\
  --collection-id 879 \\
  --name "文档标题" \\
  --content "文档内容"
```---

## 第四部分：智能体使用流程

### 4.1 创建文集流程

用户：@openclaw 创建一个「AI 学习笔记」文集

OpenClaw 思考：

1. 识别关键词：创建、文集、灏天文库
2. 加载 ht-skills
3. 检查是否符合规范

执行步骤：

1. 确认文集名称：「AI 学习笔记」
2. 调用 create_collection.py
3. API 调用灏天文库
4. 返回结果

输出：
✅ 已创建文集「AI 学习笔记」（ID: 880）

### 4.2 上传文档流程

用户：@openclaw 把这篇文章发布到灏天文库

OpenClaw 思考：

1. 检测到文章内容
2. 识别目标文集
3. 准备上传

执行步骤：

1. 查询或创建文集
2. 调用 add_document.py
3. 确认完成

输出：
✅ 文档已上传（ID: 64753）

### 4.3 查询流程

用户：@openclaw 查询我的所有文集

OpenClaw 思考：

1. 识别关键词：查询、文集
2. 加载 ht-skills

执行步骤：

1. 调用 list_collections.py
2. 格式化输出

输出：
📚 你的文集列表：

1. AI 学习笔记（ID: 880）
2. 技术文档（ID: 45）
   ...

---

## 第五部分：高级功能

### 5.1 批量操作

#### 批量上传

```python
def batch_upload(folder, collection_id):
    \"\"\"批量上传 Markdown 文件\"\"\"
    for md_file in Path(folder).glob(\"**/*.md\"):
        with open(md_file, \"r\", encoding=\"utf-8\") as f:
            content = f.read()
        
        add_document(collection_id, md_file.stem, content)
        print(f\"✅ 已上传: {md_file.name}\")

5.2 智能分类

根据文章内容自动选择文集：

def auto_classify(title, content):
    \"\"\"根据内容自动分类\"\"\"
    keywords = {
        \"AI 技术\": [\"AI\", \"机器学习\", \"深度学习\"],
        \"Web 开发\": [\"HTML\", \"CSS\", \"JavaScript\"],
        \"DevOps\": [\"Docker\", \"Kubernetes\"]
    }
    
    text = f\"{title} {content}\".lower()
    
    for category, terms in keywords.items():
        if any(term in text for term in terms):
            return category
    
    return \"未分类\"

5.3 错误处理

def safe_operation(func):
    \"\"\"\"安全的操作包装器\"\"\"
    try:
        result = func()
        if result.get(\"success\"):
            return result
        else:
            logger.error(f\"操作失败：{result.get(message)}\")
    except Exception as e:
        logger.exception(f\"操作异常：{e}\")

第六部分：最佳实践

6.1 Token 安全

# 环境变量方式
export HT_API_KEY=\"你的Token\"

# 配置文件方式
{
  \"apiKey\": {
    \"source\": \"env\",
    \"id\": \"HT_API_KEY\"
  }
}

6.2 性能优化

• 使用缓存减少 API 调用
• 批量操作提高效率
• 异步处理提升速度

6.3 日志记录

logging.basicConfig(
    level=logging.INFO,
    format=\"%(asctime)s - %(levelname)s - %(message)s\",
    handlers=[
        logging.FileHandler(\"/var/log/ht-skills.log\")
    ]
)

第七部分：实战案例

案例 1：自动化写作发布

用户：@openclaw 写一篇 Docker 教程并发布

OpenClaw 处理：

1. 生成文章内容
2. 创建「技术文档」文集
3. 上传文档
4. 同步 RAG

结果：

✅ 已创建文集「技术文档」（ID: 45）
✅ 已上传文档

案例 2：知识库迁移

用户：@openclaw 把本地 50 个 Markdown 文件上传到灏天文库

OpenClaw 处理：

1. 扫描本地文件
2. 按主题分类
3. 创建对应文集
4. 批量上传

结果：

✅ 已上传 50 个文档
📚 创建了 5 个文集

结语

ht-skills 是 OpenClaw 生态的重要组成部分，它让 AI 智能体能够：

• 📚 自动管理知识库
• ✍️ 自动生成和发布
• 🔍 智能检索和搜索
• 🔄 持续优化和迭代

通过 ht-skills，OpenClaw 真正实现了知识管理的自动化！

从今天开始，让 AI 帮你管理灏天文库知识库！🦞