连接灏天文库实战

连接灏天文库实战

灏天文库是专为 AI 内容管理设计的知识库平台，支持文集分类、文档管理和 RAG 检索增强。本节把三篇原始文章的内容合并整理，从环境搭建到自动写作发布，走通 OpenClaw + 灏天文库的完整链路。

学习目标

• 完成 ht-skills 技能的安装与配置，建立 OpenClaw 到灏天文库的连接
• 掌握文集管理、文档发布、RAG 同步三个核心操作
• 理解 ht-skills 的智能体执行规范，让 AI 按正确流程操作灏天文库
• 搭建"AI 自动写作 → 发布到灏天文库 → RAG 同步"的完整工作流

一、环境搭建与配置

1.1 整体架构

OpenClaw 通过 ht-skills 技能包连接灏天文库。ht-skills 内部封装了灏天文库的 RESTful API，AI 智能体通过执行技能脚本来操作文集和文档。

技术栈很简单：OpenClaw 负责 AI 推理和任务编排，ht-skills 负责 API 对接，灏天文库负责内容存储和检索。

1.2 获取灏天文库 Token

1. 访问灏天文库官网，登录账号
2. 进入「个人中心」
3. 生成 API Token
4. 复制 Token 并妥善保存（Token 只显示一次）

⚠️ Token 安全：API Token 等同于你的账号密码，不要提交到代码仓库或分享给他人。推荐用环境变量存储，不要直接写在配置文件里。

1.3 安装 ht-skills

ht-skills 是 OpenClaw 的技能包，安装方式有两种：

# 方式一：从技能商店安装
openclaw skill install ht-skills

# 方式二：手动安装
cd ~/.openclaw/workspace/skills/
git clone <ht-skills仓库地址> ht-skills
​

安装完成后，进入技能目录安装 Python 依赖：

cd ~/.openclaw/workspace/skills/ht-skills
pip install -r requirements.txt
​

1.4 配置文件

复制配置模板并填入你的 Token：

cp config.example.json config.json
chmod 600 config.json
​

也可以用环境变量方式，更安全：

export HT_API_KEY="你的Token"
​

然后在配置文件中引用环境变量：

{
  apiKey: {
    source: "env",
    id: "HT_API_KEY"
  }
}
​

验证安装是否成功：

python scripts/list_collections.py
​

如果返回了文集列表，说明连接正常。

💡 配置文件不要提交到 Git：.gitignore 里已经配置了忽略 config.json，但如果你手动添加过，记得检查。泄露了 Token 要立即去灏天文库重新生成。

二、ht-skills 技能详解

2.1 技能结构

ht-skills 的目录结构遵循 OpenClaw 标准技能格式：

2.2 SKILL.md 核心指令

SKILL.md 是技能的"说明书"，AI 根据它来决定怎么操作灏天文库。核心内容包括三条执行规范：

规范一：修改文档

先查询文档 ID，再执行修改。不能直接猜 ID。

规范二：添加文档

1. 必须指定文集（先查询文集 ID）
2. 添加文档到文集
3. 通知 RAG 同步

规范三：创建文集

1. 先跟用户确认文集名称
2. 确认后再执行创建

这些规范写在 SKILL.md 里，AI 会严格遵守。

2.3 API 客户端

api_client.py 封装了灏天文库的所有 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):
        """查询文档列表"""
​

每个方法对应一个命令行工具，AI 通过 bash 工具调用这些脚本。

2.4 核心操作演示

查询文集列表

python scripts/list_collections.py
python scripts/list_collections.py --name "OpenClaw"
​

返回结果示例：

[
    {
        "id": 879,
        "name": "OpenClaw",
        "description": "OpenClaw相关教程与案例",
        "created_at": "2026-03-10 10:00:00"
    }
]
​

创建文集

python scripts/create_collection.py \
  --name "技术教程" \
  --description "技术类教程合集"
​

返回结果：

{
    "success": true,
    "collection_id": 880,
    "message": "文集「技术教程」创建成功，ID: 880"
}
​

上传文档

python scripts/add_document.py \
  --collection-id 879 \
  --name "文档标题" \
  --content-file /path/to/article.md
​

返回结果：

{
    "success": true,
    "document_id": 64749,
    "message": "文档已创建并关联到文集，ID: 64749"
}
​

同步 RAG

文档上传后，需要同步到 RAG 才能被检索：

{
    "success": true,
    "document_count": 1,
    "sync_count": 1,
    "rag_result": {
        "success": true,
        "operation_type": "add",
        "processed_documents": 1,
        "details": {
            "collection_879": {
                "documents_count": 1,
                "chunks_count": 7
            }
        }
    }
}
​

三、完整工作流实战

3.1 自动写作并发布

这是最常用的场景：让 AI 写一篇文章，自动发布到灏天文库。

当 AI 接到"写文章并发布"的任务时，它会按以下流程自主执行：

1. 解析任务，确认目标文集。如果用户没指定文集，AI 会主动询问
2. 查询文集 ID。如果文集不存在，询问是否创建
3. 撰写文章内容，保存到临时文件
4. 调用 add_document.py 上传文档
5. 同步 RAG
6. 向用户报告完成结果

3.2 批量内容迁移

把本地的 Markdown 文件批量上传到灏天文库：

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}")
​

AI 执行批量上传时的流程：

1. 扫描本地文件夹中的所有 Markdown 文件
2. 按内容主题自动分类
3. 为每个分类创建对应文集
4. 批量上传文档
5. 统一同步 RAG

3.3 智能分类

ht-skills 支持根据文章内容自动选择目标文集：

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 "未分类"
​

3.4 操作速查表

💡 操作顺序：添加文档前一定要先确认文集 ID。AI 会按 SKILL.md 里的规范自动执行，但如果你手动操作，别忘了先 list_collections.py 查一下。

四、踩坑记录与最佳实践

4.1 常见问题

Token 认证失败

原因：Token 输入错误、过期，或者环境变量没生效。

解决：重新生成 Token，确认环境变量已设置（echo $HT_API_KEY 检查）。

编码错误

上传中文内容时出现乱码。

解决：确保文件以 UTF-8 编码保存，脚本中使用 encoding="utf-8" 读取文件。

并发限制

批量上传时遇到 API 限流。

解决：在批量操作之间加入适当延迟，比如每次上传后等待 1 秒。

⚠️ 批量操作要谨慎：一次性上传太多文档可能触发灏天文库的速率限制。建议每批不超过 20 个文档，批次之间间隔 5 秒。

4.2 错误处理

给关键操作加上错误处理，避免一个失败导致整个流程中断：

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}")
​

4.3 日志记录

生产环境建议开启日志，方便排查问题：

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(levelname)s - %(message)s",
    handlers=[
        logging.FileHandler("ht-skills.log", encoding="utf-8")
    ]
)
​

图：灏天文库集成工作流

本节要点

1. ht-skills 是 OpenClaw 连接灏天文库的桥梁，封装了文集管理、文档操作、RAG 同步的全部 API
2. Token 用环境变量存储，不要硬编码或提交到代码仓库
3. AI 操作灏天文库时遵循三条执行规范：修改先查询、添加先确认文集、创建先确认名称
4. 完整工作流：AI 写作 → 查询/创建文集 → 上传文档 → 同步 RAG → 通知用户
5. 批量操作注意速率限制，建议分批上传并加入延迟