sn-image-doctor

sn-image-doctor

概述

sn-image-doctor 是一项基础设施技能（第 0 层），用于在运行其他技能前验证 SenseNova-Skills 环境。它可确保 SenseNova-Skills 项目已正确安装和配置。

此技能会执行全面检查，包括：

• 验证 SenseNova-Skills 项目是否已安装
• 验证 Python 依赖项
• 检查环境变量配置，并通过交互式提示配置缺失的必需变量并将其保存到 .env
• 配置更改后自动重新加载环境；如果重新加载失败，则建议重启 Agent

用法

运行 doctor 检查以验证环境：

# Basic check
python scripts/check_environment.py

# Verbose output with detailed diagnostics
python scripts/check_environment.py --verbose

输出格式

文本输出

=== SenseNova-Skills Environment Check ===

[1/3] Checking sn-image-base installation...
  ✅ Installation looks good

[2/3] Checking Python dependencies...
  ✅ Python 3.11.0
  ✅ All required packages installed

[3/3] Checking environment variables...
  ❌ SN_IMAGE_GEN_API_KEY: Image generation API key is not set; configure SN_API_KEY, or configure SN_IMAGE_GEN_API_KEY only for an image-generation-specific override

  Some required environment variables are missing.
  Enter values below to save them to /path/to/.env.
  Press Enter to skip a variable.

  SN_API_KEY: <user input>

  ✅ Saved to /path/to/.env: SN_API_KEY
  🔄 Reloading environment...
  ✅ Environment reloaded successfully

=== Summary ===
✅ Environment is properly configured

如果重新加载失败，输出会建议重启 Agent：

  ✅ Saved to /path/to/.env: SN_API_KEY
  🔄 Reloading environment...
  ⚠️  Failed to reload environment: <error message>
  💡 Suggestion: Restart the agent to apply new configuration

错误输出

检查失败时：

=== SenseNova-Skills Environment Check ===

[1/3] Checking sn-image-base installation...
  ❌ sn-image-base directory not found
  Expected location: /path/to/skills/sn-image-base

[2/3] Checking Python dependencies...
  ❌ Missing packages: httpx, pillow
  Run: pip install -r skills/sn-image-base/requirements.txt

=== Summary ===
❌ Environment check failed
Please fix the errors above before using SenseNova-Skills.

故障排除

未找到 sn-image-base

问题： 未找到 sn-image-base 目录

解决方案：

# Ensure you're in the project root
cd /path/to/SenseNova-Skills

# Verify the directory exists
ls -la skills/sn-image-base

缺少依赖项

问题： 未安装必需的 Python 包

解决方案：

# Install dependencies
pip install -r skills/sn-image-base/requirements.txt

# Or use a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r skills/sn-image-base/requirements.txt

缺少环境变量

问题： 未设置必需的环境变量

解决方案：

# If all capabilities use the same gateway, set only the global values.
export SN_API_KEY="your-api-key"
export SN_BASE_URL="https://your-api-endpoint.com"

# Or create a .env file
cat > .env << EOF
SN_API_KEY=your-api-key
SN_BASE_URL=https://token.sensenova.cn/v1
SN_CHAT_TYPE=openai-completions
SN_CHAT_MODEL=sensenova-6.8-flash-lite
EOF

# Load .env file
source .env  # Or use a tool like python-dotenv

回退优先级为：能力专用变量 > 领域共享变量 > 全局变量。例如，文本调用使用 SN_TEXT_API_KEY -> SN_CHAT_API_KEY -> SN_API_KEY；视觉调用使用 SN_VISION_API_KEY -> SN_CHAT_API_KEY -> SN_API_KEY；图像生成使用 SN_IMAGE_GEN_API_KEY -> SN_API_KEY。

API 连接问题

问题： 无法连接 API 端点

解决方案：

1. 验证网络连接

2. 检查防火墙设置

3. 验证 API 端点 URL 是否正确

4. 使用 curl 测试：

   curl -I https://your-api-endpoint.com
   

与其他技能集成

此技能旨在 SenseNova-Skills 项目中用于其他技能之前：

# 1. Run doctor check
python skills/sn-image-doctor/scripts/check_environment.py

# 2. If checks pass, use other skills
python skills/sn-image-base/scripts/sn_agent_runner.py sn-image-generate \
    --prompt "A beautiful landscape"

命令行选项

选项	说明
--verbose	显示详细的诊断信息
--help	显示帮助信息

退出代码

代码	含义
0	所有检查均已通过
1	一项或多项检查失败

另请参阅

• sn-image-base/SKILL.md - 基础层技能文档
• sn-image-base/references/api_spec.md - API 规范
• sn-infographic/SKILL.md - 依赖 sn-image-base 的技能示例