openknowforge-skill

name

openknowforge-skill

description

Operate OpenKnowForge database through HTTP API. Use when Codex needs to work with OpenKnowForge note management system for: (1) Creating, reading, updating, or deleting notes, (2) Searching or filtering notes by keywords/tags, (3) Managing draft and published states, (4) Batch operations on notes, or any other database operations. Provides Python client library and CLI tool for all CRUD operations.

OpenKnowForge-Skill

通用的 OpenKnowForge 数据库操作工具。提供 HTTP API 交互、CRUD 操作、搜索、批量处理等完整功能。

快速开始

初始化客户端

from okforge_client import OpenKnowForgeClient

# 使用默认 URL (http://127.0.0.1:8000)
client = OpenKnowForgeClient()

# 或指定自定义 URL
client = OpenKnowForgeClient("http://example.com:8000")

基本操作

# 创建笔记 - 用户提供所有内容
note = client.create_note(
    title=user_provided_title,
    content=user_provided_content,
    tags=user_provided_tags
)

# 搜索笔记
results = client.search_notes(q=user_query, limit=20)

# 读取、编辑、删除等
client.read_note(slug)
client.edit_note(slug, title=new_title)
client.delete_note(slug)
client.publish_note(slug)
client.save_as_draft(slug)

API 方法参考

所有方法返回 JSON 对象。错误时抛出异常。

健康检查

health = client.health_check()

CRUD 操作

创建笔记

note = client.create_note(
    title,              # 必填: 1-200 字符
    content="",         # 可选: 笔记内容
    tags=[],            # 可选: 标签列表
    images=[],          # 可选: 图片 URL
    type="note",        # 可选: 笔记类型
    status=None,        # 可选: 自定义状态
    is_draft=False,     # 可选: 是否草稿
    related=[],         # 可选: 相关笔记 slug
    submitted_at=None   # 可选: 提交时间
)

读取笔记

note = client.read_note(slug)

编辑笔记 (所有字段都是可选的，仅更新传入的字段)

updated = client.edit_note(
    slug,
    title=None,
    content=None,
    tags=None,
    images=None,
    type=None,
    status=None,
    is_draft=None,
    related=None,
    submitted_at=None
)

删除笔记

result = client.delete_note(slug)

列表与搜索

列表所有已发布笔记

all_notes = client.list_notes()

列表所有草稿

drafts = client.list_draft_notes()

搜索笔记 (关键词搜索标题/内容/标签)

results = client.search_notes(
    q="",               # 关键词 (可选)
    tag=None,           # 精确标签过滤 (可选)
    limit=20            # 结果数量限制 1-200 (可选)
)

状态管理

更新笔记状态

updated = client.update_note_status(
    slug,
    status=None,        # 新状态
    is_draft=None,      # 新草稿状态
    submitted_at=None   # 新提交时间
)

快速发布

client.publish_note(slug)  # 转为已发布状态

快速保存为草稿

client.save_as_draft(slug)  # 转为草稿状态

命令行工具

使用 okforge.py 进行快速操作。

# 创建
python okforge.py create -t "标题" -c "内容" --tags "tag1,tag2"

# 读取
python okforge.py read slug

# 列表
python okforge.py list              # 所有笔记
python okforge.py drafts            # 草稿

# 搜索
python okforge.py search -q "关键词" --tag "标签" --limit 20

# 编辑
python okforge.py edit slug -t "新标题"

# 发布 / 草稿
python okforge.py publish slug
python okforge.py draft slug

# 删除
python okforge.py delete slug --confirm

# 健康检查
python okforge.py health

数据模型

Note 对象包含以下字段：

字段	类型	说明
id	string (UUID)	笔记唯一标识
slug	string	URL 安全的标识符 (由服务器自动生成)
title	string	笔记标题
content	string	笔记内容 (支持 Markdown)
tags	array	标签列表
images	array	图片 URL 列表
type	string	笔记类型 (默认: "note")
status	string	自定义状态标记
is_draft	boolean	是否为草稿
related	array	相关笔记 slug 列表
submitted_at	ISO 8601	提交时间戳
created_at	ISO 8601	创建时间
updated_at	ISO 8601	更新时间

配置

环境变量

设置 OpenKnowForge 服务器地址 (在 openclaw.json 或系统环境中)：

OPENKNOWFORGE_BASE_URL=http://127.0.0.1:8000

默认值: http://127.0.0.1:8000

openclaw.json 配置

{
  "skills": {
    "entries": {
      "openknowforge-skill": {
        "env": {
          "OPENKNOWFORGE_BASE_URL": "http://127.0.0.1:8000"
        }
      }
    }
  }
}

常见模式

批量创建笔记

data_list = [
    {"title": "...", "content": "...", "tags": [...]},
    ...
]

for data in data_list:
    note = client.create_note(**data)
    print(f"创建: {note['result']['slug']}")

搜索并更新

results = client.search_notes(q="keyword", limit=100)

for note_info in results["result"]:
    updated = client.edit_note(
        slug=note_info["slug"],
        status="reviewed"
    )

备份所有笔记

import json
from datetime import datetime

all_notes = client.list_notes()

backup_file = f"backup_{datetime.now().isoformat()}.json"
with open(backup_file, "w") as f:
    json.dump(all_notes, f, indent=2, ensure_ascii=False)

错误处理

所有方法在出错时抛出 Exception：

try:
    note = client.read_note("non-existent")
except Exception as e:
    print(f"错误: {e}")  # HTTP 404: ...

文件结构

openknowforge-skill/
├── SKILL.md                    # 本文档
├── scripts/
│   ├── okforge_client.py       # 核心客户端库
│   ├── okforge.py              # CLI 工具
│   └── test_okforge.py         # 单元测试
└── references/
    └── api_spec.json           # OpenAPI 规范

相关资源

• API 规范详情: See references/api_spec.json
• 完整文档和示例: See README.md
• 项目架构: See STRUCTURE.md