Skip to content

OpenSenseNova/SenseNova-Skills / skills/sn-image-base

sn-image-base

Verified

Base-layer skill for the SenseNova-Skills project, providing low-level APIs for image generation, recognition (VLM), and text optimization (LLM). This skill does not preprocess inputs; it only calls backend services and returns results. This skill is not user-facing and is intended for upper-layer skills only.

FileKindSize
.gitattributesother219 B
.gitignoreother4.3 KB
README.mdmarkdown10.7 KB
README_CN.mdmarkdown10.4 KB
SKILL.mdskill md13.0 KB
references/api_spec.mdmarkdown14.0 KB
requirements.txtmanifest50 B
scripts/.python-versionother4 B
scripts/extract_json.pyscript3.6 KB
scripts/pyproject.tomlmanifest339 B
scripts/ruff.tomlconfig730 B
scripts/sn_agent_runner.pyscript25.1 KB
scripts/sn_image_base/__init__.pyscript24 B
scripts/sn_image_base/configs.pyscript12.5 KB
scripts/sn_image_base/exceptions.pyscript1.2 KB
scripts/sn_image_base/generation/__init__.pyscript358 B
scripts/sn_image_base/generation/atlas_cloud.pyscript9.6 KB
scripts/sn_image_base/generation/core/__init__.pyscript412 B
scripts/sn_image_base/generation/core/client_base.pyscript2.5 KB
scripts/sn_image_base/generation/nano_banana.pyscript11.6 KB
scripts/sn_image_base/generation/openai_image.pyscript12.3 KB
scripts/sn_image_base/generation/sensenova.pyscript19.5 KB
scripts/sn_image_base/llm/__init__.pyscript215 B
scripts/sn_image_base/llm/anthropic_adapter.pyscript5.0 KB
scripts/sn_image_base/llm/chat_completions_adapter.pyscript9.7 KB
scripts/sn_image_base/llm/llm_adapter.pyscript1.8 KB
scripts/sn_image_base/utils/__init__.pyscript0 B
scripts/sn_image_base/utils/error_utils.pyscript7.3 KB
scripts/sn_image_base/utils/httpx_client.pyscript7.0 KB
scripts/sn_image_base/vlm/__init__.pyscript100 B
scripts/sn_image_base/vlm/utils.pyscript3.0 KB
scripts/sn_image_base/vlm/vlm_adapter.pyscript2.1 KB
scripts/tests/test_atlas_cloud.pyscript6.9 KB
tests/conftest.pyscript375 B
tests/test_configs_env_fallthrough.pyscript2.8 KB

README_CN.md

View on GitHub
# sn-image-base

该技能属于 [SenseNova-Skills](https://github.com/OpenSenseNova/SenseNova-Skills) 项目,提供图像生成、图像识别(VLM)和文本优化(LLM)的底层 API 能力。

完整行为请见 [SKILL.md](SKILL.md)。

本文档主要介绍该技能的详细配置。

概览与技能安装、使用方法请参考项目根目录下的 [README.md](../../README.md)(中文可见 [README_CN.md](../../README_CN.md));详细配置以本文档为准。

## 概览

该技能提供以下子命令:

- `sn-image-generate`:图像生成
- `sn-image-edit`:图像编辑(SenseNova U1.5 Lite)
- `sn-image-recognize`:图像识别(VLM)
- `sn-text-optimize`:文本优化(LLM)

支持的模型服务如下:

- 图像生成:
  - [SenseNova](https://platform.sensenova.cn/)
  - Nano Banana API
  - OpenAI 图像生成 API(例如 GPT-Image-2)

- 文本与视觉 Chat:
  - [SenseNova](https://platform.sensenova.cn/)
  - 通过 Anthropic Messages API 接入的模型(例如 Claude Sonnet 4.6)
  - 通过 OpenAI Chat Completion API 接入的模型(例如 GPT、Gemini/Qwen 等 OpenAI 兼容格式模型)

## 配置

### 快速开始

推荐使用 [SenseNova Token Plan](https://platform.sensenova.cn/token-plan)。

前往 <https://platform.sensenova.cn/token-plan/> 注册免费账号,并获取可用于图像生成和 chat 调用的 API Key。

将以下环境变量写入 `~/.openclaw/.env`(OpenClaw)或 `~/.hermes/.env`(Hermes):

```ini
# 如果所有能力都走同一个网关,只需要配置这两个变量。
SN_BASE_URL="https://token.sensenova.cn/v1"
SN_API_KEY="<sensenova-token-plan-api-key>"

# 可选模型覆盖
SN_IMAGE_GEN_MODEL="sensenova-u1.5-lite"   # 或 sensenova-u1-fast,或 Token Plan 中的其他图像生成模型
SN_CHAT_MODEL="sensenova-6.8-flash-lite"
```

**注意:不要将 `.env` 文件或 API key 提交到 git。**

### 详细配置

完成 [快速开始](#快速开始) 后即可使用本技能。

若需更进一步配置(例如使用不同模型、修改 base URL 等),请参考以下内容。

支持多重配置来源,优先级(从高到低)如下:

- (推荐)`~/.openclaw/.env`(OpenClaw)或 `~/.hermes/.env`(Hermes)
- 当前工作目录 `.env`(不一定存在,取决于 agent 运行技能的方式)
- 进程环境变量

> 进阶开发者可查看 [configs.py](scripts/sn_image_base/configs.py) 获取完整变量与默认值。
>
> 便于快速追踪行为的关键符号:
>
> - `prepare_env()`:`.env` 加载顺序
> - `Field.resolve()`:环境变量回退顺序(“第一个已设置值优先”)
> - `Configs`:默认值与环境变量映射

#### 图像生成

环境变量解析优先级为:专用变量 > 领域共享变量 > 全局变量。

| 能力 | API key fallback | Base URL fallback |
| ---- | ---------------- | ----------------- |
| 文本模型 | `SN_TEXT_API_KEY` -> `SN_CHAT_API_KEY` -> `SN_API_KEY` | `SN_TEXT_BASE_URL` -> `SN_CHAT_BASE_URL` -> `SN_BASE_URL` |
| 视觉模型 | `SN_VISION_API_KEY` -> `SN_CHAT_API_KEY` -> `SN_API_KEY` | `SN_VISION_BASE_URL` -> `SN_CHAT_BASE_URL` -> `SN_BASE_URL` |
| 图像生成 | `SN_IMAGE_GEN_API_KEY` -> `SN_API_KEY` | `SN_IMAGE_GEN_BASE_URL` -> `SN_BASE_URL` |

图像生成完整配置如下:

| 配置键 | 说明 | 默认值 |
| ------ | ---- | ------ |
| `SN_API_KEY` | 所有能力共用的全局 API Key | `""` |
| `SN_BASE_URL` | 所有能力共用的全局基础 URL | `""` |
| `SN_IMAGE_GEN_API_KEY` | 可选的图像生成专用 API key 覆盖 | `SN_API_KEY` |
| `SN_IMAGE_GEN_MODEL_TYPE` | 图像生成模型类型 | `"sensenova"` |
| `SN_IMAGE_GEN_MODEL` | 图像生成模型名 | `"sensenova-u1.5-lite"` |
| `SN_IMAGE_GEN_BASE_URL` | 图像生成 API 的基础 URL | `SN_BASE_URL`,然后 `"https://token.sensenova.cn/v1"` |

默认值适用于 [SenseNova](https://platform.sensenova.cn/)。

如果所有能力走同一个网关,只需要设置 `SN_BASE_URL` 和 `SN_API_KEY`。
仅当图像生成需要不同 provider 时,再设置 `SN_IMAGE_GEN_*`。

如需使用非默认图像生成模型,请按以下步骤:

1. 设置 `SN_IMAGE_GEN_MODEL_TYPE` 为对应模型类型,可选值如下:

    ```ini
    # (默认)用于 [SenseNova](https://platform.sensenova.cn/)
    SN_IMAGE_GEN_MODEL_TYPE="sensenova"
    # 用于 Google Nano Banana 模型 API
    SN_IMAGE_GEN_MODEL_TYPE="nano-banana"
    # 用于 OpenAI 图像生成 API
    SN_IMAGE_GEN_MODEL_TYPE="openai-image"
    # 用于 Atlas Cloud 的任务式图像生成 API
    SN_IMAGE_GEN_MODEL_TYPE="atlas-cloud"
    ```

2. 设置 `SN_IMAGE_GEN_BASE_URL` 为图像生成 API 的基础 URL,例如:

    ```ini
    # (默认)用于 [SenseNova](https://platform.sensenova.cn/)
    SN_IMAGE_GEN_BASE_URL="https://token.sensenova.cn/v1"
    # 用于 Google Nano Banana 模型 API
    SN_IMAGE_GEN_BASE_URL="https://generativelanguage.googleapis.com"
    # 用于 OpenAI 图像生成 API
    SN_IMAGE_GEN_BASE_URL="https://api.openai.com/v1"
    # 用于 Atlas Cloud
    SN_IMAGE_GEN_BASE_URL="https://api.atlascloud.ai/api/v1"
    ```

3. 设置 `SN_IMAGE_GEN_MODEL` 为对应类型下的模型名,例如:

    ```ini
    # (默认)用于 [SenseNova](https://platform.sensenova.cn/)
    SN_IMAGE_GEN_MODEL="sensenova-u1.5-lite"
    # 或使用 SenseNova U1 Fast:
    # SN_IMAGE_GEN_MODEL="sensenova-u1-fast"
    # 用于 Google Nano Banana 模型 API
    SN_IMAGE_GEN_MODEL="gemini-3.1-flash-image-preview"
    # 用于 OpenAI 图像生成 API
    SN_IMAGE_GEN_MODEL="gpt-image-2"
    # 用于 Atlas Cloud
    SN_IMAGE_GEN_MODEL="bytedance/seedream-v5.0-lite"
    ```

4. 如果图像生成使用不同于全局 key 的密钥,再设置 `SN_IMAGE_GEN_API_KEY`。如果 `SN_API_KEY` 已可用于图像生成,则无需设置。

    ```ini
    SN_IMAGE_GEN_API_KEY="sk-your-image-generation-api-key"
    ```

#### 文本与视觉 Chat

##### 配置共享 Chat Runtime

文本优化和图像识别现在共享一套 chat runtime。协议、endpoint、API key 与默认模型配置一次,仅在需要时分别覆盖文本或视觉模型:

| 配置键 | 说明 | 默认值 |
| ------ | ---- | ------ |
| `SN_CHAT_API_KEY` | text/vision chat 调用共用 API key | `SN_API_KEY` |
| `SN_CHAT_BASE_URL` | 共享 Chat API 基础 URL | `SN_BASE_URL`,然后 `"https://token.sensenova.cn/v1"` |
| `SN_CHAT_TYPE` | 共享 Chat 协议类型 | `"openai-completions"` |
| `SN_CHAT_MODEL` | text/vision chat 调用共用默认模型 | `"sensenova-6.8-flash-lite"` |
| `SN_TEXT_API_KEY` | 可选文本 provider API key | `SN_CHAT_API_KEY` -> `SN_API_KEY` |
| `SN_TEXT_BASE_URL` | 可选文本 provider 基础 URL | `SN_CHAT_BASE_URL` -> `SN_BASE_URL` |
| `SN_TEXT_TYPE` | 可选文本协议类型 | `SN_CHAT_TYPE` |
| `SN_TEXT_MODEL` | 可选的 `sn-text-optimize` 模型覆盖 | `SN_CHAT_MODEL` |
| `SN_VISION_API_KEY` | 可选视觉 provider API key | `SN_CHAT_API_KEY` -> `SN_API_KEY` |
| `SN_VISION_BASE_URL` | 可选视觉 provider 基础 URL | `SN_CHAT_BASE_URL` -> `SN_BASE_URL` |
| `SN_VISION_TYPE` | 可选视觉协议类型 | `SN_CHAT_TYPE` |
| `SN_VISION_MODEL` | 可选的 `sn-image-recognize` 视觉模型覆盖 | `SN_CHAT_MODEL` |

默认值适用于 [SenseNova](https://platform.sensenova.cn/)。

仅当文本或视觉命令需要使用不同 provider 时,才需要配置 `SN_TEXT_*` 或 `SN_VISION_*`。

对于 chat 调用,runner 也兼容不带路径的 host-only base URL,例如
`https://token.sensenova.cn`:如果 URL 中没有 path,会先补上 API 版本路径再追加具体接口。
为保持和内置默认值一致,建议优先使用带版本路径的 base URL,例如
`https://token.sensenova.cn/v1`。

如需使用非默认 chat 设置,请按以下步骤:

1. 按 chat API 协议设置 `SN_CHAT_TYPE`。可选值如下:

    ```ini
    # (默认)OpenAI 兼容 `/chat/completions` 接口(最常见)
    SN_CHAT_TYPE="openai-completions"
    # Anthropic Messages `/messages` 接口
    SN_CHAT_TYPE="anthropic-messages"
    ```

2. 将 `SN_CHAT_BASE_URL` 设置为共享 chat endpoint 的基础 URL,例如:

    ```ini
    # (默认)用于 [SenseNova](https://platform.sensenova.cn/)
    SN_CHAT_BASE_URL="https://token.sensenova.cn/v1"
    # 用于 Anthropic Messages API
    SN_CHAT_BASE_URL="https://api.anthropic.com/v1"
    # 用于 OpenAI Chat Completion API
    SN_CHAT_BASE_URL="https://api.openai.com/v1"
    # 用于 Google Gemini API(OpenAI 兼容)
    SN_CHAT_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
    ```

3. 设置 `SN_CHAT_MODEL`,仅在文本或视觉命令需要不同模型时再设置 `SN_TEXT_MODEL` / `SN_VISION_MODEL`:

    ```ini
    # (默认)SenseNova 6.7 Flash Lite
    SN_CHAT_MODEL="sensenova-6.8-flash-lite"
    # Anthropic Claude Sonnet 4.6
    SN_VISION_MODEL="claude-sonnet-4-6"
    # Google Gemini 3 Flash Preview
    SN_VISION_MODEL="gemini-3-flash-preview"
    # OpenAI GPT 5.5
    SN_TEXT_MODEL="gpt-5.5"
    ```

4. 设置 `SN_CHAT_API_KEY` 为共享 chat endpoint 的 API key,或使用全局 `SN_API_KEY`:

    ```ini
    SN_CHAT_API_KEY="sk-your-api-key"
    ```

## 故障排查

### 缺少 API key

- 现象:报错包含 "required but not set"、"missing api key" 或请求未授权。
- 处理:如果所有能力使用同一个 key,设置全局 `SN_API_KEY` 即可。不要重复设置 `SN_IMAGE_GEN_API_KEY`,除非图像生成需要不同 provider 或 key;仅当 chat/text/vision 需要不同 provider 时,再设置 `SN_CHAT_API_KEY`、`SN_TEXT_API_KEY` 或 `SN_VISION_API_KEY`。

### base URL 配置错误

- 现象:请求立即失败,或出现 URL 校验 / endpoint 相关错误。
- 处理:检查 `SN_BASE_URL` 或能力专用 base URL 是否为完整基础 URL(包含 scheme + host),例如 `https://token.sensenova.cn/v1`。

### 模型名不支持

- 现象:provider 返回 HTTP 404 / model-not-found / bad request。
- 处理:确认 `*_MODEL_TYPE` / `*_TYPE` 与 `*_MODEL` 来自同一 provider,且模型在当前账号下可用。

### 鉴权 / 权限错误

- 现象:HTTP 401/403、"permission denied"、"forbidden"。
- 处理:确认密钥与所选 provider endpoint 匹配,检查账号配额/权限,并使用已知可用模型重试。

## 安全说明

- **不要**将 `.env` 文件或 API key 提交到 git。
- 若密钥泄露,请立即轮换并更新本地环境变量文件。
- 优先使用本地密钥管理(`~/.openclaw/.env` 或 `~/.hermes/.env`),避免在脚本或提示词中硬编码密钥。
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall