# Image Analyze Skill

> GitHub Copilot Chat Assistant

- Skill: `hmjjj2/image-analyze-skill` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add hmjjj2/image-analyze-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hmjjj2/image-analyze-skill/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: hmjjj2 (https://skillmd.com/u/hmjjj2)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/hmjjj2/image-analyze-skill

---

GitHub Copilot Chat Assistant

# image-analyze-skill — skill.md

说明
- 这是一个可直接用作 Function Calling 的技能说明与示例实现（skill.md）。
- 包含可放进 models function list 的 JSON schema、示例调用、以及可运行的最小后端示例（Python Flask + Pillow + pytesseract）。
- 你可以复制并保存为 skill.md。

---

## 概述
这个技能接收一张图片（公开 URL 或 base64），并根据请求的 task 返回：图片描述（自然语言）、对象检测结果、OCR 文本或为无障碍场景生成替代文字（alt text）。设计目标是简单、可扩展、安全。

---

## Function Calling 定义（JSON schema）
{
  "name": "analyze_image",
  "description": "接收图片（image_url 或 image_base64），并完成指定视觉任务：describe、detect_objects、ocr、generate_alt_text、caption。",
  "parameters": {
    "type": "object",
    "properties": {
      "image_url": {
        "type": "string",
        "description": "图片的公开可访问 URL（优先使用）。"
      },
      "image_base64": {
        "type": "string",
        "description": "base64 编码的图片数据（与 image_url 二选一）。"
      },
      "content_type": {
        "type": "string",
        "description": "图片 MIME 类型，如 image/png 或 image/jpeg（可选）。"
      },
      "task": {
        "type": "string",
        "enum": ["describe","detect_objects","ocr","generate_alt_text","caption"],
        "description": "要执行的任务。"
      },
      "options": {
        "type": "object",
        "description": "任务特定可选项。",
        "properties": {
          "max_objects": { "type": "integer", "default": 10 },
          "language": { "type": "string", "default": "zh-CN" },
          "include_confidence": { "type": "boolean", "default": true }
        }
      }
    },
    "required": ["task"],
    "oneOf": [
      { "required": ["image_url"] },
      { "required": ["image_base64"] }
    ]
  }
}

示例返回结构（实现应返回相似 JSON）：
{
  "description": "一张在公园的白天照片，前景有两个人坐在长椅上，背景有树和一条小路。",
  "objects": [
    { "label": "person", "confidence": 0.98, "bbox": [100,50,200,400] },
    { "label": "bench", "confidence": 0.89, "bbox": [80,300,300,370] }
  ],
  "ocr_text": "示例识别文本",
  "alt_text": "两人在公园长椅上，背景为树木和小路。",
  "raw": { "source": "local" }
}

---

## 使用示例（function-calling JSON）
示例（传 URL）：
{
  "name": "analyze_image",
  "arguments": {
    "image_url": "https://example.com/photo.jpg",
    "task": "describe",
    "options": { "language": "zh-CN" }
  }
}

示例（传 base64）：
{
  "name": "analyze_image",
  "arguments": {
    "image_base64": "<base64-data>",
    "task": "ocr",
    "options": { "language": "zh-CN" }
  }
}

curl JSON 调用示例（调用本地 HTTP 服务）：
curl -X POST "http://localhost:5000/analyze-image" -H "Content-Type: application/json" -d '{"image_url":"https://example.com/photo.jpg","task":"describe"}'

---

## 最小可运行后端（Python Flask 示例）
说明：此示例实现 OCR（pytesseract）和基本描述模板。对象检测/高级 caption 可接入第三方视觉模型或云视觉 API（示后）。限制：需安装依赖并配置 tesseract。

依赖（pip）：
- flask
- pillow
- requests
- pytesseract

系统需安装 tesseract（例如 apt install tesseract-ocr）。

app.py:
from flask import Flask, request, jsonify
from PIL import Image
import io, base64, requests, pytesseract

app = Flask(__name__)

def load_image_from_url(url, timeout=5):
    resp = requests.get(url, timeout=timeout)
    resp.raise_for_status()
    return Image.open(io.BytesIO(resp.content)).convert("RGB")

def load_image_from_base64(b64):
    header_removed = b64.split(",",1)[-1]
    data = base64.b64decode(header_removed)
    return Image.open(io.BytesIO(data)).convert("RGB")

def do_ocr(img, lang="chi_sim"):
    try:
        text = pytesseract.image_to_string(img, lang=lang)
        return text.strip()
    except Exception as e:
        return ""

@app.route("/analyze-image", methods=["POST"])
def analyze_image_http():
    payload = request.get_json()
    if not payload or "task" not in payload:
        return jsonify({"error":"missing task"}), 400
    task = payload["task"]
    options = payload.get("options", {})
    lang = options.get("language", "zh-CN")
    try:
        if "image_url" in payload:
            img = load_image_from_url(payload["image_url"])
        elif "image_base64" in payload:
            img = load_image_from_base64(payload["image_base64"])
        else:
            return jsonify({"error":"missing image_url or image_base64"}), 400
    except Exception as e:
        return jsonify({"error":"failed to load image","detail": str(e)}), 400

    result = {"raw": {"source": "local"}}
    if task == "ocr":
        # pytesseract language codes vary; map zh-CN -> chi_sim if tesseract trained data present
        t_lang = "chi_sim" if lang.startswith("zh") else "eng"
        result["ocr_text"] = do_ocr(img, lang=t_lang)
    elif task == "describe" or task == "generate_alt_text" or task == "caption":
        # Minimal rule-based description (placeholder). Replace with model API for better results.
        w,h = img.size
        result["description"] = f"图片尺寸 {w}x{h}，可能包含人物或场景。请使用更强的模型生成自然语言描述。"
        if task == "generate_alt_text":
            result["alt_text"] = "自动生成的替代文字：一张照片，包含人物或场景。"
    elif task == "detect_objects":
        # Placeholder: no detector here. Return empty list.
        result["objects"] = []
        result["note"] = "未启用本地对象检测。可接入 YOLO/Detectron/云视觉 API。"
    else:
        return jsonify({"error":"unsupported task"}), 400

    return jsonify(result)

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000, debug=True)

运行：
- pip install flask pillow requests pytesseract
- 安装系统 tesseract（例如 Debian/Ubuntu: apt install tesseract-ocr tesseract-ocr-chi-sim）
- python app.py

扩展点：
- 对象检测：接入 ultralytics YOLOv8（pip install ultralytics）或 torch + detectron2。
- 图片描述/caption：接入开源视觉-语言模型（如 BLIP、OFASys 等）或云服务（Google Vision + Vertex AI、Azure Vision、AWS Rekognition）。

---

## 使用云视觉服务（快速替代）
如果希望精确、立即可用的检测/描述，推荐接入 Google Vision 或 Azure Computer Vision（按其 REST API 调用）。优点：准确、易部署；缺点：需云账号与付费。

示例思路：
- 将 image_url 传给云 API 的图像分析端点
- 返回的 objects/labels/ocr/caption 填入技能返回结构

---

## 安全与生产注意事项
- 防止 SSRF：对 image_url 进行白名单或拒绝私有 IP（127.0.0.1, 10.*, 172.16.*, 192.168.*）；使用短超时与最大响应体大小限制。
- 限制 base64 大小（建议 <= 5MB 或你能处理的阈值）。
- 并发与队列：对耗时任务（模型推理）采用队列与限流，避免请求风暴。
- 隐私：不要把敏感图片存入日志；如需存储，应告知用户并加密存储。
- 内容检测：若提供公开服务，考虑对成人/暴力等内容进行检测与处理。

---

## 集成建议（模型 function-calling）
- 把上面的 JSON schema 放入调用模型时的 functions 列表。
- 当模型选择调用函数，按 schema 传入 image_url 或 image_base64 与 task。
- 后端接收到 function 调用参数后，执行分析并返回 JSON，模型会把结果整合进对话。

---

## 限制与改进路线
- 当前提供的本地示例仅做演示（OCR + 占位描述）。生产需要接入更强的视觉模型或云视觉 API。
- 推荐路线：
  1. 快速起步：使用云视觉（Google/Azure/AWS）
  2. 可控部署：部署轻量级本地模型（YOLOv8 + BLIP）
  3. 精细化：多任务流水线并行处理（OCR、检测、caption），缓存结果，提供分页/裁剪大图

---

## 文件署名与 License
- 推荐放置 MIT 或 Apache-2.0 许可证头。这里示例使用 MIT（请在仓库中添加 LICENSE 文件）。

---

如果你还需要我把这个文件上传到仓库并给你 raw 下载链接，或者生成一个 public gist，或者把示例改成 Node.js/TypeScript 实现，告诉我你想要哪种我再继续.