From 93ae5b734254d6abf53cc8a2be9d1bb8df34b601 Mon Sep 17 00:00:00 2001 From: openclaw Date: Mon, 19 Oct 2026 01:46:55 +0000 Subject: [PATCH] docs: adopt co-located documentation structure across modules --- README.md | 117 +++++++++++++------------------------------- src/tools/README.md | 13 +++++ src/video/README.md | 66 +++++++++++++++++++++++++ 3 files changed, 112 insertions(+), 84 deletions(-) create mode 100644 src/tools/README.md create mode 100644 src/video/README.md diff --git a/README.md b/README.md index 187aaa2..cdebbda 100644 --- a/README.md +++ b/README.md @@ -2,99 +2,24 @@ OpenClaw 统一私有扩展插件集合,聚合了自定义 Agent 工具、媒体生成驱动(视频/图像)以及内置技能库。 ---- - -## 包含模块一览 - -| 模块类别 | 标识符 (ID) | 类型 | 说明 | -| :--- | :--- | :--- | :--- | -| **视频生成** | `openai-video` | `videoGenerationProviders` | OpenAI `/v1/videos` 兼容格式视频生成驱动(支持自建网关 / gemini-web2api / Sora 协议) | -| **基础工具** | `echo` | `tools` | 基础测试与回显工具 | -| **内置技能** | `agent-access` | `skills` | Bitwarden Agent Access 自动化技能 | +各模块采用**就近同构原则(Co-location)**维护其独立代码、测试与文档,避免全局单页膨胀与文档漂移。 --- -## 模块说明 +## 包含模块清单 -### 1. 视频生成驱动 (`openai-video`) - -适配标准 **OpenAI Videos API**(`/v1/videos` 规范),专门针对自建中转(如 `gemini-web2api-go`、`ccLoad`、第三方 OpenAI 兼容视频服务)做了深度兼容修复: -* `POST /v1/videos` 创建生成任务(纯文本任务自动发 JSON Body,避免第三方服务不支持 Multipart 的 400 报错;带垫图/垫视频时使用 Multipart 表单) -* `GET /v1/videos/{id}` 轮询任务完成状态(兼容普通对象错误与字符串错误消息) -* `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 凭据的无感注入与访问流程。 +| 模块类别 | 标识符 (ID) | 契约类型 | 说明 | 详细文档 | +| :--- | :--- | :--- | :--- | :--- | +| **视频生成** | `openai-video` | `videoGenerationProviders` | OpenAI `/v1/videos` 协议兼容视频生成驱动(支持自建网关 / gemini-web2api / Sora 协议) | [查看文档 →](src/video/README.md) | +| **基础工具** | `echo` | `tools` | 基础测试与连通性回显工具 | [查看文档 →](src/tools/README.md) | +| **内置技能** | `agent-access` | `skills` | Bitwarden Agent Access 自动化技能 | [查看技能 →](skills/agent-access/SKILL.md) | --- ## 安装与更新 ### 安装插件 -在 Gateway 主机上执行: +在 OpenClaw Gateway 主机上执行: ```bash 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 ``` -### 验证与测试 +### 开发与验证 ```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 [MIT](LICENSE) diff --git a/src/tools/README.md b/src/tools/README.md new file mode 100644 index 0000000..754f7c7 --- /dev/null +++ b/src/tools/README.md @@ -0,0 +1,13 @@ +# Tools (`tools`) + +基础工具集合模块。 + +--- + +## 包含工具 + +### `echo` +* **说明**:回显输入的文本内容。 +* **主要用途**:验证 Agent 工具链的挂载连通性、参数序列化与状态交付。 +* **参数**: + * `input` (string): 需要回显的文本内容。 diff --git a/src/video/README.md b/src/video/README.md new file mode 100644 index 0000000..93ed74b --- /dev/null +++ b/src/video/README.md @@ -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 视频” +* **垫图/图生视频**: + 在对话中上传或提供图片链接,提示助手基于该图生成视频。