docs: adopt co-located documentation structure across modules
This commit is contained in:
1 parent
bd9eda19c1
commit
93ae5b7342
3 files changed
+112
-84
No files matched your search
@@ -2,99 +2,24 @@
|
|||||||
|
|
||||||
OpenClaw 统一私有扩展插件集合,聚合了自定义 Agent 工具、媒体生成驱动(视频/图像)以及内置技能库。
|
OpenClaw 统一私有扩展插件集合,聚合了自定义 Agent 工具、媒体生成驱动(视频/图像)以及内置技能库。
|
||||||
|
|
||||||
---
|
各模块采用**就近同构原则(Co-location)**维护其独立代码、测试与文档,避免全局单页膨胀与文档漂移。
|
||||||
|
|
||||||
## 包含模块一览
|
|
||||||
|
|
||||||
| 模块类别 | 标识符 (ID) | 类型 | 说明 |
|
|
||||||
| :--- | :--- | :--- | :--- |
|
|
||||||
| **视频生成** | `openai-video` | `videoGenerationProviders` | OpenAI `/v1/videos` 兼容格式视频生成驱动(支持自建网关 / gemini-web2api / Sora 协议) |
|
|
||||||
| **基础工具** | `echo` | `tools` | 基础测试与回显工具 |
|
|
||||||
| **内置技能** | `agent-access` | `skills` | Bitwarden Agent Access 自动化技能 |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 模块说明
|
## 包含模块清单
|
||||||
|
|
||||||
### 1. 视频生成驱动 (`openai-video`)
|
| 模块类别 | 标识符 (ID) | 契约类型 | 说明 | 详细文档 |
|
||||||
|
| :--- | :--- | :--- | :--- | :--- |
|
||||||
适配标准 **OpenAI Videos API**(`/v1/videos` 规范),专门针对自建中转(如 `gemini-web2api-go`、`ccLoad`、第三方 OpenAI 兼容视频服务)做了深度兼容修复:
|
| **视频生成** | `openai-video` | `videoGenerationProviders` | OpenAI `/v1/videos` 协议兼容视频生成驱动(支持自建网关 / gemini-web2api / Sora 协议) | [查看文档 →](src/video/README.md) |
|
||||||
* `POST /v1/videos` 创建生成任务(纯文本任务自动发 JSON Body,避免第三方服务不支持 Multipart 的 400 报错;带垫图/垫视频时使用 Multipart 表单)
|
| **基础工具** | `echo` | `tools` | 基础测试与连通性回显工具 | [查看文档 →](src/tools/README.md) |
|
||||||
* `GET /v1/videos/{id}` 轮询任务完成状态(兼容普通对象错误与字符串错误消息)
|
| **内置技能** | `agent-access` | `skills` | Bitwarden Agent Access 自动化技能 | [查看技能 →](skills/agent-access/SKILL.md) |
|
||||||
* `GET /v1/videos/{id}/content` 下载二进制视频流
|
|
||||||
* 原生支持内网/私有端点(`allowPrivateNetwork: true`,支持 `host.incus.internal` 或局域网 IP)
|
|
||||||
|
|
||||||
#### 配置说明
|
|
||||||
|
|
||||||
支持通过 **Web 控制台(Control UI)** 或直接编辑 `~/.openclaw/openclaw.json`。
|
|
||||||
|
|
||||||
##### 方式 1:Web 控制台可视化配置
|
|
||||||
进入 **Settings → Plugins → Tools**:
|
|
||||||
* **API Base URL**:填写视频上游端点(例如 `http://host.incus.internal:8083/v1` 或内部网关地址)
|
|
||||||
* **API Key**:填写 API Key 或 SecretRef(留空时自动回退读取环境变量 `OPENAI_VIDEO_API_KEY`、`CCLOAD_API_KEY` 或 `BIFROST_API_KEY`)
|
|
||||||
* **默认视频模型**:例如 `gemini-video` 或 `sora-2`
|
|
||||||
|
|
||||||
##### 方式 2:编辑 `openclaw.json`
|
|
||||||
|
|
||||||
在 `~/.openclaw/openclaw.json` 中配置:
|
|
||||||
|
|
||||||
```json5
|
|
||||||
{
|
|
||||||
"plugins": {
|
|
||||||
"entries": {
|
|
||||||
"tools": {
|
|
||||||
"enabled": true,
|
|
||||||
"config": {
|
|
||||||
"video": {
|
|
||||||
"baseUrl": "http://host.incus.internal:8083/v1",
|
|
||||||
"apiKey": "sk-your-video-key",
|
|
||||||
"defaultModel": "gemini-video",
|
|
||||||
"allowPrivateNetwork": true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"agents": {
|
|
||||||
"defaults": {
|
|
||||||
"mediaModels": {
|
|
||||||
"video": {
|
|
||||||
"primary": "openai-video/gemini-video"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
> **向下兼容提示**:插件仍完全兼容旧版独立插件 `plugins.entries["openai-video"].config` 的配置路径,迁移期间无需强行改动旧配置即可直接读取。
|
|
||||||
|
|
||||||
#### 使用方法
|
|
||||||
|
|
||||||
配置后,OpenClaw 内置的 `video_generate` 工具即可自动调度:
|
|
||||||
* **自然语言直接对话生成**:
|
|
||||||
> “帮我生成一个 5 秒的猫咪在海滩上奔跑的 16:9 视频”
|
|
||||||
* **垫图/图生视频**:
|
|
||||||
在对话中上传或提供图片链接,提示助手基于该图生成视频。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 2. 基础工具 (`tools`)
|
|
||||||
|
|
||||||
* **`echo`**:回显文本输入,用于验证 Agent 工具链连通性与执行状态。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### 3. 内置技能 (`skills`)
|
|
||||||
|
|
||||||
* **`agent-access`**:位于 `skills/agent-access/SKILL.md`,安装插件后自动软链接至 OpenClaw 技能目录,提供 Bitwarden 凭据的无感注入与访问流程。
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 安装与更新
|
## 安装与更新
|
||||||
|
|
||||||
### 安装插件
|
### 安装插件
|
||||||
在 Gateway 主机上执行:
|
在 OpenClaw Gateway 主机上执行:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
openclaw plugins install git:git.1-h.cc/OpenClaw/openclaw-plugin-tools --force
|
openclaw plugins install git:git.1-h.cc/OpenClaw/openclaw-plugin-tools --force
|
||||||
@@ -107,7 +32,7 @@ openclaw plugins install git:git.1-h.cc/OpenClaw/openclaw-plugin-tools --force
|
|||||||
openclaw plugins update tools
|
openclaw plugins update tools
|
||||||
```
|
```
|
||||||
|
|
||||||
### 验证与测试
|
### 开发与验证
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# 运行单元测试
|
# 运行单元测试
|
||||||
@@ -119,6 +44,30 @@ pnpm run build
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## 项目结构
|
||||||
|
|
||||||
|
```text
|
||||||
|
openclaw-plugin-tools/
|
||||||
|
├── openclaw.plugin.json # 插件统一清单与契约配置
|
||||||
|
├── package.json # 包元数据与入口定义
|
||||||
|
├── README.md # 根目录索引导航
|
||||||
|
├── src/
|
||||||
|
│ ├── index.ts # 插件注册统一入口
|
||||||
|
│ ├── index.test.ts # 统一注册测试
|
||||||
|
│ ├── types.d.ts # Plugin SDK 补充类型定义
|
||||||
|
│ ├── tools/ # 工具模块集合
|
||||||
|
│ │ ├── echo.ts
|
||||||
|
│ │ └── README.md # 工具专属说明
|
||||||
|
│ └── video/ # 视频生成驱动模块
|
||||||
|
│ ├── index.ts
|
||||||
|
│ └── README.md # 视频驱动专属说明
|
||||||
|
└── skills/ # 官方规范就近内置技能
|
||||||
|
└── agent-access/
|
||||||
|
└── SKILL.md # 技能自描述文件
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
[MIT](LICENSE)
|
[MIT](LICENSE)
|
||||||
@@ -0,0 +1,13 @@
|
|||||||
|
# Tools (`tools`)
|
||||||
|
|
||||||
|
基础工具集合模块。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 包含工具
|
||||||
|
|
||||||
|
### `echo`
|
||||||
|
* **说明**:回显输入的文本内容。
|
||||||
|
* **主要用途**:验证 Agent 工具链的挂载连通性、参数序列化与状态交付。
|
||||||
|
* **参数**:
|
||||||
|
* `input` (string): 需要回显的文本内容。
|
||||||
@@ -0,0 +1,66 @@
|
|||||||
|
# OpenAI Video Provider (`openai-video`)
|
||||||
|
|
||||||
|
OpenClaw 视频生成驱动模块,适配标准 **OpenAI Videos API**(`/v1/videos` 规范)。
|
||||||
|
|
||||||
|
专为自建聚合网关或第三方中转(如 `gemini-web2api-go`、`ccLoad`)做了深度兼容修复:
|
||||||
|
* **任务创建**:`POST /v1/videos`。纯文本任务自动发送 JSON Body,避免第三方服务因不支持 Multipart 表单报 400 错误;带参考图/垫视频时使用标准 Multipart 表单。
|
||||||
|
* **状态轮询**:`GET /v1/videos/{id}`。兼容提取普通对象错误信息与字符串错误消息。
|
||||||
|
* **视频下载**:`GET /v1/videos/{id}/content`。流式下载 MP4 二进制视频流。
|
||||||
|
* **私有网络**:原生支持私有/内网端点请求(`allowPrivateNetwork: true`),兼容 `host.incus.internal`、Tailnet 或局域网反代地址。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 配置说明
|
||||||
|
|
||||||
|
支持通过 **Web 控制台(Control UI)** 或直接编辑 `~/.openclaw/openclaw.json`。
|
||||||
|
|
||||||
|
### 方式 1:Web 控制台可视化配置
|
||||||
|
进入 **Settings → Plugins → Tools**:
|
||||||
|
* **API Base URL**:填写视频上游端点(例如 `http://host.incus.internal:8083/v1` 或内部网关地址)
|
||||||
|
* **API Key**:填写 API Key 或 SecretRef(留空时自动回退读取环境变量 `OPENAI_VIDEO_API_KEY`、`CCLOAD_API_KEY` 或 `BIFROST_API_KEY`)
|
||||||
|
* **默认视频模型**:例如 `gemini-video` 或 `sora-2`
|
||||||
|
|
||||||
|
### 方式 2:编辑 `openclaw.json`
|
||||||
|
|
||||||
|
在 `~/.openclaw/openclaw.json` 中配置:
|
||||||
|
|
||||||
|
```json5
|
||||||
|
{
|
||||||
|
"plugins": {
|
||||||
|
"entries": {
|
||||||
|
"tools": {
|
||||||
|
"enabled": true,
|
||||||
|
"config": {
|
||||||
|
"video": {
|
||||||
|
"baseUrl": "http://host.incus.internal:8083/v1",
|
||||||
|
"apiKey": "sk-your-video-key",
|
||||||
|
"defaultModel": "gemini-video",
|
||||||
|
"allowPrivateNetwork": true
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"agents": {
|
||||||
|
"defaults": {
|
||||||
|
"mediaModels": {
|
||||||
|
"video": {
|
||||||
|
"primary": "openai-video/gemini-video"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
> **向下兼容提示**:插件仍完全兼容旧版独立插件 `plugins.entries["openai-video"].config` 的配置路径,迁移期间无需强行改动旧配置即可直接读取。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 使用方法
|
||||||
|
|
||||||
|
配置完成后,OpenClaw 内置的 `video_generate` 工具即可自动调度:
|
||||||
|
* **自然语言直接对话生成**:
|
||||||
|
> “帮我生成一个 5 秒的猫咪在海滩上奔跑的 16:9 视频”
|
||||||
|
* **垫图/图生视频**:
|
||||||
|
在对话中上传或提供图片链接,提示助手基于该图生成视频。
|
||||||
Reference in new issue
Block a user