From 946e7197aee825a8667ea5b2711623af53be2acb Mon Sep 17 00:00:00 2001 From: Jowe <123822645+Selei1983@users.noreply.github.com> Date: Mon, 23 Mar 2026 23:16:57 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20API=20=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E5=92=8C=20OpenClaw=20Skill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 docs/API_DOC.md API 接口文档 - 新增 .claude/skills/zjpb-api.md OpenClaw 集成说明 Co-Authored-By: Claude Sonnet 4.6 --- .claude/skills/zjpb-api.md | 42 +++++ docs/API_DOC.md | 325 +++++++++++++++++++++++++++++++++++++ 2 files changed, 367 insertions(+) create mode 100644 .claude/skills/zjpb-api.md create mode 100644 docs/API_DOC.md diff --git a/.claude/skills/zjpb-api.md b/.claude/skills/zjpb-api.md new file mode 100644 index 0000000..b285a99 --- /dev/null +++ b/.claude/skills/zjpb-api.md @@ -0,0 +1,42 @@ +# ZJPB OpenClaw Skill + +## 描述 + +通过 OpenClaw 调用 ZJPB API 管理网站 + +## 使用方法 + +``` +/zjpb-create-site <网站名称> <网站URL> [简短描述] +``` + +## 参数 + +- `<网站名称>`: 必填，网站名称 +- `<网站URL>`: 必填，网站地址 +- `[简短描述]`: 可选，网站简短描述 + +## 示例 + +``` +/zjpb-create-site 谷歌 https://www.google.com 全球最大的搜索引擎 +``` + +## 内部实现 + +调用 ZJPB API: +- URL: `http://175.178.72.171/api/key/sites` +- Method: POST +- Header: `X-API-Key: {配置的API_KEY}` +- Body: `{"name": "<网站名称>", "url": "<网站URL>", "short_desc": "[简短描述]"}` + +--- + +## 配置说明 + +在 OpenClaw 中配置： + +1. 添加 Tool/MCP Server +2. 配置 API 端点: `http://175.178.72.171` +3. 设置认证: Header `X-API-Key` +4. API Key 在 ZJPB 后台「API密钥」菜单获取 \ No newline at end of file diff --git a/docs/API_DOC.md b/docs/API_DOC.md new file mode 100644 index 0000000..549d5c4 --- /dev/null +++ b/docs/API_DOC.md @@ -0,0 +1,325 @@ +# ZJPB API 文档 + +## 概述 + +ZJPB 网站管理 API，通过 API Key 进行认证，可用于外部工具（如 OpenClaw）调用。 + +## 基础信息 + +- **Base URL**: `http://175.178.72.171` +- **认证方式**: Header (`X-API-Key`) +- **数据格式**: JSON + +## 认证 + +所有 API 请求需要在 Header 中携带 API Key： + +``` +X-API-Key: your-api-key-here +``` + +获取 API Key：进入后台管理 → API密钥 → 创建新密钥 + +--- + +## API 接口 + +### 1. 获取网站列表 + +```http +GET /api/key/sites +``` + +**权限**: `site:read` + +**响应示例**: +```json +{ + "success": true, + "sites": [ + { + "id": 1, + "code": "12345678", + "name": "网站名称", + "url": "https://example.com", + "slug": "example", + "logo": "/uploads/logo.png", + "short_desc": "简短描述", + "description": "详细介绍", + "features": "主要功能", + "news_keywords": "关键词", + "is_active": true, + "is_recommended": false, + "view_count": 100, + "tags": ["标签1", "标签2"], + "created_at": "2026-03-23 10:00:00" + } + ] +} +``` + +--- + +### 2. 创建网站 + +```http +POST /api/key/sites +``` + +**权限**: `site:write` + +**请求体**: +```json +{ + "name": "网站名称", + "url": "https://example.com", + "slug": "example", + "logo": "/uploads/logo.png", + "short_desc": "简短描述", + "description": "详细介绍", + "features": "主要功能", + "news_keywords": "关键词", + "tags": ["标签1", "标签2"], + "is_active": true, + "is_recommended": false, + "sort_order": 0 +} +``` + +**字段说明**: +| 字段 | 必填 | 说明 | +|------|------|------| +| name | 是 | 网站名称 | +| url | 是 | 网站 URL | +| slug | 否 | URL别名，用于 SEO | +| logo | 否 | Logo 图片路径 | +| short_desc | 否 | 简短描述 | +| description | 否 | 详细介绍 | +| features | 否 | 主要功能 | +| news_keywords | 否 | 新闻关键词 | +| tags | 否 | 标签数组 | +| is_active | 否 | 是否启用，默认 true | +| is_recommended | 否 | 是否推荐，默认 false | +| sort_order | 否 | 排序权重，默认 0 | + +**响应示例**: +```json +{ + "success": true, + "site": { + "id": 2, + "code": "87654321", + "name": "网站名称", + "url": "https://example.com", + "slug": "example" + } +} +``` + +--- + +### 3. 获取单个网站 + +```http +GET /api/key/sites/{code} +``` + +**权限**: `site:read` + +**参数**: +- `code`: 网站编码（8位数字） + +**响应示例**: +```json +{ + "success": true, + "site": { + "id": 1, + "code": "12345678", + "name": "网站名称", + "url": "https://example.com", + ... + } +} +``` + +--- + +### 4. 更新网站 + +```http +PUT /api/key/sites/{code} +``` + +**权限**: `site:write` + +**参数**: +- `code`: 网站编码（8位数字） + +**请求体**: 同创建网站，可只传需要更新的字段 + +**响应示例**: +```json +{ + "success": true, + "site": { + "id": 1, + "code": "12345678", + "name": "新名称", + ... + } +} +``` + +--- + +### 5. 删除网站 + +```http +DELETE /api/key/sites/{code} +``` + +**权限**: `site:write` + +**参数**: +- `code`: 网站编码（8位数字） + +**响应示例**: +```json +{ + "success": true, + "message": "网站已删除" +} +``` + +--- + +## 错误响应 + +```json +{ + "success": false, + "message": "错误信息" +} +``` + +**状态码**: +- `200`: 成功 +- `400`: 请求参数错误 +- `401`: 认证失败（无效的 API Key） +- `403`: 权限不足 +- `404`: 资源不存在 +- `500`: 服务器错误 + +--- + +## 使用示例 + +### cURL + +```bash +# 获取网站列表 +curl -X GET http://175.178.72.171/api/key/sites \ + -H "X-API-Key: your-api-key" + +# 创建网站 +curl -X POST http://175.178.72.171/api/key/sites \ + -H "Content-Type: application/json" \ + -H "X-API-Key: your-api-key" \ + -d '{ + "name": "示例网站", + "url": "https://example.com", + "short_desc": "这是一个示例网站", + "tags": ["科技", "开源"] + }' + +# 更新网站 +curl -X PUT http://175.178.72.171/api/key/sites/12345678 \ + -H "Content-Type: application/json" \ + -H "X-API-Key: your-api-key" \ + -d '{"name": "新名称"}' + +# 删除网站 +curl -X DELETE http://175.178.72.171/api/key/sites/12345678 \ + -H "X-API-Key: your-api-key" +``` + +### Python + +```python +import requests + +API_KEY = "your-api-key" +BASE_URL = "http://175.178.72.171" +headers = {"X-API-Key": API_KEY} + +# 获取网站列表 +response = requests.get(f"{BASE_URL}/api/key/sites", headers=headers) +print(response.json()) + +# 创建网站 +data = { + "name": "示例网站", + "url": "https://example.com", + "short_desc": "这是一个示例网站", + "tags": ["科技", "开源"] +} +response = requests.post(f"{BASE_URL}/api/key/sites", json=data, headers=headers) +print(response.json()) +``` + +### JavaScript + +```javascript +const API_KEY = "your-api-key"; +const BASE_URL = "http://175.178.72.171"; +const headers = { "X-API-Key": API_KEY }; + +// 获取网站列表 +fetch(`${BASE_URL}/api/key/sites`, { headers }) + .then(res => res.json()) + .then(data => console.log(data)); + +// 创建网站 +fetch(`${BASE_URL}/api/key/sites`, { + method: "POST", + headers: { + "Content-Type": "application/json", + "X-API-Key": API_KEY + }, + body: JSON.stringify({ + name: "示例网站", + url: "https://example.com", + short_desc: "这是一个示例网站" + }) +}) + .then(res => res.json()) + .then(data => console.log(data)); +``` + +--- + +## OpenClaw 集成 + +在 OpenClaw 中配置 API： + +1. **Base URL**: `http://175.178.72.171` +2. **Auth Header**: `X-API-Key` +3. **Auth Value**: 你创建的 API Key + +创建网站的 prompt 示例： + +``` +你是一个网站发布助手。请根据用户提供的网站信息，调用 ZJPB API 创建网站。 + +网站信息： +- 名称：{name} +- URL：{url} +- 描述：{description} + +请调用 POST /api/key/sites 接口创建网站。 +``` + +--- + +**最后更新**: 2026-03-23 \ No newline at end of file