ephron_ren/agent-skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
Hermes Agent
2026-05-10 13:52:46 +08:00
commit ccc63d1e70
4583 changed files with 584341 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

291
sn-image-base/references/api_spec.md Normal file
View File

@@ -0,0 +1,291 @@
# sn-image-base API Specification
## Table of Contents
- [sn-image-generate](#sn-image-generate)
- [sn-image-recognize](#sn-image-recognize)
- [sn-text-optimize](#sn-text-optimize)
- [Error Handling](#error-handling)
---
## sn-image-generate
Image generation tool that calls the configured image generation backend.
### Command Format
```bash
python sn_agent_runner.py sn-image-generate \
--prompt <string> \
[--api-key <string>] \
[--base-url <string>] \
[--negative-prompt <string>] \
[--image-size 2k] \
[--aspect-ratio <string>] \
[--seed <int>] \
[--unet-name <string>] \
[--poll-interval <float>] \
[--timeout <float>] \
[--insecure] \
[--output-format text|json] \
[--save-path <path>]
```
### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `--prompt` | string | **Yes** | - | Text prompt |
| `--api-key` | string | No | `SN_IMAGE_GEN_API_KEY` -> `SN_API_KEY` | API Key (CLI takes precedence; raises `MissingApiKeyError` if all are empty) |
| `--base-url` | string | No | `SN_IMAGE_GEN_BASE_URL` -> `SN_BASE_URL` | API base URL (CLI takes precedence) |
| `--negative-prompt` | string | No | `""` | Negative prompt |
| `--image-size` | string | No | `"2k"` | Image size: `2k` only |
| `--aspect-ratio` | string | No | `"16:9"` | Aspect ratio |
| `--seed` | int | No | `None` | Random seed (for reproducibility) |
| `--unet-name` | string | No | `None` | UNet model name |
| `--poll-interval` | float | No | `5.0` | Polling interval in seconds |
| `--timeout` | float | No | `300.0` | Timeout in seconds |
| `--insecure` | flag | No | `False` | Disable TLS verification |
| `--output-format` | string | No | `"text"` | Output format: `text` or `json` |
| `--save-path` | path | No | Auto-generated | Output image path |
### Aspect Ratio Options
`2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `1:1`, `16:9`, `9:16`, `21:9`, `9:21`
### Output Path
Default output: `/tmp/openclaw-sn-image/t2i_<timestamp>.png`
### Response Examples
**text format**:
```
Image generated successfully
/tmp/openclaw-sn-image/t2i_20260414_120000.png
```
**json format**:
```json
{
"status": "ok",
"output": "/tmp/openclaw-sn-image/t2i_20260414_120000.png",
"task_id": "task_xxx",
"message": "Image generated successfully",
"elapsed_seconds": 1.23
}
```
### API Key Notes
`--api-key` is optional. CLI parameter takes precedence; if not provided, reads `SN_IMAGE_GEN_API_KEY` -> `SN_API_KEY`. If all are empty, raises `MissingApiKeyError`:
**text format**:
```
Error: API key is required but was not provided. Set SN_API_KEY, or set SN_IMAGE_GEN_API_KEY only for an image-generation-specific override, or pass --api-key explicitly.
```
**json format**:
```json
{"status": "failed", "error": "API key is required but was not provided. Set SN_API_KEY, or set SN_IMAGE_GEN_API_KEY only for an image-generation-specific override, or pass --api-key explicitly.", "elapsed_seconds": 0.05}
```
---
## sn-image-recognize
Image recognition tool that uses a VLM (Vision Language Model) to analyze image content.
### Command Format
```bash
python sn_agent_runner.py sn-image-recognize \
(--user-prompt <string> | --user-prompt-path <path>) \
--images <string> [<string> ...] \
--api-key <string> \
--base-url <string> \
--model <string> \
[--system-prompt <string>] \
[--system-prompt-path <path>] \
[--vlm-type openai-completions|anthropic-messages] \
[--output-format text|json]
```
### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `--user-prompt` | string | One of two | - | User instruction (mutually exclusive with `--user-prompt-path`) |
| `--user-prompt-path` | path | One of two | - | Local file path to read user instruction from (mutually exclusive with `--user-prompt`) |
| `--images` | string[] | **Yes** | - | List of image paths (supports multiple) |
| `--api-key` | string | No | No hardcoded default | CLI > `SN_VISION_API_KEY` > `SN_CHAT_API_KEY` > `SN_API_KEY`; raises `MissingApiKeyError` if all are empty |
| `--base-url` | string | No | `https://token.sensenova.cn/v1` | CLI > `SN_VISION_BASE_URL` > `SN_CHAT_BASE_URL` > `SN_BASE_URL` |
| `--model` | string | No | `sensenova-6.7-flash-lite` | CLI > `SN_VISION_MODEL` > `SN_CHAT_MODEL` |
| `--system-prompt` | string | No | `""` | System instruction (mutually exclusive with `--system-prompt-path`) |
| `--system-prompt-path` | path | No | - | Local file path to read system instruction from (mutually exclusive with `--system-prompt`) |
| `--vlm-type` | string | No | `openai-completions` | CLI > `SN_VISION_TYPE` > `SN_CHAT_TYPE` |
| `--output-format` | string | No | `"text"` | Output format: `text` or `json` |
`--vlm-type` options:
- `openai-completions`: OpenAI-compatible `/v1/chat/completions` endpoint
- `anthropic-messages`: Anthropic Messages `/v1/messages` endpoint
### Response Examples
**text format**:
```
This image shows an adorable orange cat napping in the sunlight.
```
**json format**:
```json
{
"status": "ok",
"result": "This image shows an adorable orange cat napping in the sunlight.",
"model": "sensenova-6.7-flash-lite",
"base_url": "https://token.sensenova.cn/v1",
"interface_type": "openai-completions",
"elapsed_seconds": 2.15
}
```
### Parameter Priority
`--api-key`, `--base-url`, `--model`, and `--vlm-type` use priority: **CLI parameter > command-specific environment variable > shared `SN_CHAT_*` environment variable > global `SN_*` environment variable > built-in default**.
| Parameter | Built-in Default | Environment Variable |
|-----------|-----------------|---------------------|
| `--api-key` | None (required) | `SN_VISION_API_KEY` -> `SN_CHAT_API_KEY` -> `SN_API_KEY` |
| `--base-url` | `https://token.sensenova.cn/v1` | `SN_VISION_BASE_URL` -> `SN_CHAT_BASE_URL` -> `SN_BASE_URL` |
| `--model` | `sensenova-6.7-flash-lite` | `SN_VISION_MODEL` -> `SN_CHAT_MODEL` |
| `--vlm-type` | `openai-completions` | `SN_VISION_TYPE` -> `SN_CHAT_TYPE` |
Compatibility note: host-only chat base URLs such as `https://token.sensenova.cn`
are also accepted. If the base URL has no path, the runner inserts `/v1` before
the interface endpoint; if it already has a path such as `/v1`, the runner
appends only the interface endpoint path.
---
## sn-text-optimize
Text optimization tool that uses an LLM (Language Model) to optimize text content.
### Command Format
```bash
python sn_agent_runner.py sn-text-optimize \
(--user-prompt <string> | --user-prompt-path <path>) \
--api-key <string> \
--base-url <string> \
--model <string> \
[--system-prompt <string>] \
[--system-prompt-path <path>] \
[--llm-type openai-completions|anthropic-messages] \
[--output-format text|json]
```
### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `--user-prompt` | string | One of two | - | User instruction (mutually exclusive with `--user-prompt-path`) |
| `--user-prompt-path` | path | One of two | - | Local file path to read user instruction from (mutually exclusive with `--user-prompt`) |
| `--api-key` | string | No | No hardcoded default | CLI > `SN_TEXT_API_KEY` > `SN_CHAT_API_KEY` > `SN_API_KEY`; raises `MissingApiKeyError` if all are empty |
| `--base-url` | string | No | `https://token.sensenova.cn/v1` | CLI > `SN_TEXT_BASE_URL` > `SN_CHAT_BASE_URL` > `SN_BASE_URL` |
| `--model` | string | No | `sensenova-6.7-flash-lite` | CLI > `SN_TEXT_MODEL` > `SN_CHAT_MODEL` |
| `--system-prompt` | string | No | `""` | System instruction (mutually exclusive with `--system-prompt-path`) |
| `--system-prompt-path` | path | No | - | Local file path to read system instruction from (mutually exclusive with `--system-prompt`) |
| `--llm-type` | string | No | `openai-completions` | CLI > `SN_TEXT_TYPE` > `SN_CHAT_TYPE` |
| `--output-format` | string | No | `"text"` | Output format: `text` or `json` |
`--llm-type` options:
- `openai-completions`: OpenAI-compatible `/v1/chat/completions` endpoint
- `anthropic-messages`: Anthropic Messages `/v1/messages` endpoint
### Response Examples
**text format**:
```
Optimized text content...
```
**json format**:
```json
{
"status": "ok",
"result": "Optimized text content...",
"model": "sensenova-6.7-flash-lite",
"base_url": "https://token.sensenova.cn/v1",
"interface_type": "openai-completions",
"elapsed_seconds": 0.83
}
```
### Parameter Priority
`--api-key`, `--base-url`, `--model`, and `--llm-type` use priority: **CLI parameter > command-specific environment variable > shared `SN_CHAT_*` environment variable > global `SN_*` environment variable > built-in default**.
| Parameter | Built-in Default | Environment Variable |
|-----------|-----------------|---------------------|
| `--api-key` | None (required) | `SN_TEXT_API_KEY` -> `SN_CHAT_API_KEY` -> `SN_API_KEY` |
| `--base-url` | `https://token.sensenova.cn/v1` | `SN_TEXT_BASE_URL` -> `SN_CHAT_BASE_URL` -> `SN_BASE_URL` |
| `--model` | `sensenova-6.7-flash-lite` | `SN_TEXT_MODEL` -> `SN_CHAT_MODEL` |
| `--llm-type` | `openai-completions` | `SN_TEXT_TYPE` -> `SN_CHAT_TYPE` |
Compatibility note: host-only chat base URLs such as `https://token.sensenova.cn`
are also accepted. If the base URL has no path, the runner inserts `/v1` before
the interface endpoint; if it already has a path such as `/v1`, the runner
appends only the interface endpoint path.
---
## Error Handling
### Error Types
| Type | Source | Trigger | Output Format |
|------|--------|---------|---------------|
| `MissingApiKeyError` | Custom business exception | API Key not provided for `sn-image-generate` | text: `Error: ...` / json: `{"status": "failed", "error": "..."}` |
| `ValueError` (prompt) | `_resolve_prompt` | `--user-prompt` and `--user-prompt-path` both provided, neither provided, or file read failure | text: `Error: ...` / json: `{"status": "failed", "error": "..."}` |
| argparse missing param | argparse standard error | Missing required parameters for `sn-image-recognize`/`sn-text-optimize` | `usage: ...` + exit 2 |
| HTTP error | httpx request layer | API returns non-2xx status code | `{"status": "failed", "error": "HTTP NNN", "message": "..."}` |
| Request exception | httpx request layer | Network error, timeout, etc. | `{"status": "failed", "error": "<ExceptionType>", "message": "..."}` |
### text format
Error messages are written to stderr and do not affect stdout content.
### json format
```json
{
"status": "failed",
"error": "error type",
"message": "detailed error message",
"elapsed_seconds": 0.05
}
```
---
## API Key Environment Variables
| Tool | Environment Variables (high → low priority) | Notes |
|------|---------------------------------------------|-------|
| `sn-image-generate` | `SN_IMAGE_GEN_API_KEY` -> `SN_API_KEY` | CLI > optional image generation key > global key; raises `MissingApiKeyError` if all are empty |
| `sn-image-recognize` | `SN_VISION_API_KEY` -> `SN_CHAT_API_KEY` -> `SN_API_KEY` | CLI > command-specific key > shared chat key > global key; raises `MissingApiKeyError` if all are empty |
| `sn-text-optimize` | `SN_TEXT_API_KEY` -> `SN_CHAT_API_KEY` -> `SN_API_KEY` | CLI > command-specific key > shared chat key > global key; raises `MissingApiKeyError` if all are empty |
`SN_API_KEY` is the global key for all capabilities. `SN_CHAT_API_KEY` is the shared key for both text and vision chat calls. Use command-specific keys only when a command needs a different provider.

58
sn-image-base/references/sensenova-config.md Normal file
View File

@@ -0,0 +1,58 @@
# SenseNova Skills 配置参考
## 安装日期
2026-05-09
## API 配置
| 项目 | 值 |
|------|-----|
| Base URL | `https://token.sensenova.cn/v1` |
| API Key | `SN_API_KEY` (保存在 `~/.hermes/.env`) |
| 协议 | OpenAI 兼容 |
## 模型列表
| 模型 | 用途 | 调用限制 |
|------|------|----------|
| `sensenova-6.7-flash-lite` | 多模态智能体（文本+图像理解+工具调用） | 每 5 小时 1500 次 |
| `sensenova-u1-fast` | 信息图/图像生成专用 | 每 5 小时 1500 次 |
| `deepseek-v4-flash` | DeepSeek 高性能对话 | 每 5 小时 150 次 |
## 已安装 Skills（13个）
### 🔗 绑定 SenseNova（2个）
- `sn-image-base` — 文生图、图像识别、文本优化
- `sn-infographic` — 信息图生成（87种布局/66种风格）
### 🔄 可自由替换模型（11个）
- 深度研究系列（6个）：`sn-deep-research`, `sn-research-planning`, `sn-dimension-research`, `sn-research-synthesis`, `sn-research-report`, `sn-report-format-discovery`
- 搜索系列（4个）：`sn-search-academic`, `sn-search-code`, `sn-search-social-cn`, `sn-search-social-en`
- `sn-md-to-html-report` — Markdown 转 HTML 阅读视图
## 依赖安装
```bash
# Pillow (sn-image-base 需要)
~/.hermes/hermes-agent/venv/bin/pip3 install Pillow
```
## 测试结果（2026-05-09）
| Skill | 状态 | 备注 |
|-------|------|------|
| sensenova-6.7-flash-lite | ✅ | 文本对话正常 |
| deepseek-v4-flash | ✅ | 文本对话正常 |
| sn-image-generate (u1-fast) | ✅ | 图像生成正常，质量中等偏上 |
| sn-search-academic | ✅ | ArXiv 搜索正常 |
| sn-search-social-cn | ✅ | B站搜索正常 |
| sn-search-code | ✅ | GitHub 搜索正常 |
| sn-md-to-html-report | ✅ | HTML 转换正常 |
## 注意事项
1. **限流策略**：按 5 小时窗口限流，不是按分钟
2. **DeepSeek 限流最严**：只有 150 次/5小时，是其他模型的 1/10
3. **图像生成质量**：中等偏上，中文文字是伪汉字（通病），细节不如 Midjourney V6
4. **生图依赖**：需要 Pillow 库，安装到 hermes-agent 的 venv
5. **Chrome sandbox 问题**：容器/VM 环境中需要 `--no-sandbox` 参数