哈基马赛克

发表于 更新于 分类于 阅读次数：

哈基马赛克：让机器人给你的图片打上猫猫码

自动识别人物敏感部位，用可爱的猫猫图案覆盖，让你的图片处理变得有趣又自动化。
作者: 蜥蜴

背景

作为一个混迹于各大二次元社群的群聊机器人维护者，我经常遇到一个需求：群友分享了一些”比较刺激”的图片，需要打码处理。

传统的做法是手动用 Photoshop 或在线工具打码，效率极低。而且群聊中的图片往往来得快去得也快，手动处理根本跟不上节奏。

于是我就想：能不能让机器人自动识别图片中的敏感区域，然后用可爱的猫猫图案来覆盖？

这样既能达到打码的目的，又能让处理结果变得有趣，而不是那种死板的马赛克方块。

于是就有了这个插件——hajimi-lizard。

工具定位

koishi-plugin-hajimi-lizard 是一款基于 Koishi 框架的图片处理插件，核心功能是：

  • 自动识别：使用模型自动检测图片中的指定区域
  • 猫猫覆盖：用预设的猫头和猫纹路图案覆盖检测到的区域
  • 批量处理：支持单次处理多张图片
  • 服务化调用：其他插件可通过 ctx.hajimi 服务轻松调

插件修改自 AutoHajimiMosaic 项目，感谢原作者的开源贡献。

工作流程

1
用户发送图片 → 机器人下载图片 → Python 调用模型检测 → 生成掩码 → 覆盖猫猫图案 → 返回处理结果

整个流程分为六个步骤：

1. 图片接收

用户在群聊或私聊中发送图片，并附带指令 猫赛克：

1
2
用户: 猫赛克 [图片]
机器人: 图片处理中，请稍候...

2. 图片下载

机器人从聊天消息中提取图片 URL，下载到本地缓存目录。

3. 模型推理

启动 Python 子进程，调用两个模型：

  • 分类模型（classification_model.pt）：判断图片内容类别
  • 分割模型（segmentation_model.pt）：生成目标区域的精确掩码

4. 图案覆盖

在检测到的区域上执行透视变换，将猫头和猫纹路图案贴合到目标区域：

1
原始图片 → 识别区域 → 计算透视矩阵 → 变换猫头图案 → 混合叠加 → 输出结果

5. 结果返回

处理完成后，将生成的图片路径返回给调用方，机器人将图片发送到聊天中。

快速开始

1. 安装

1
npm install koishi-plugin-hajimi-lizard

或者在 Koishi 控制台的插件市场搜索 hajimi-lizard 安装。

2. 配置 Python

插件依赖 Python 3.8+ 运行环境，需要确保：

  • Python 已安装并配置到系统环境变量
  • 或在插件配置中指定 Python 路径
1
2
3
4
plugins:
  hajimi-lizard:
    pythonPath: 'C:\Users\yourPC\AppData\Local\Programs\Python\Python313\python.exe'
    autoClean: true

3. 准备模型文件

将模型文件放入 src/models/ 目录：

  • classification_model.pt - 内容分类模型
  • segmentation_model.pt - 分割模型

首次启动时，插件会自动安装 Python 依赖（opencv、ultralytics、imagecodecs 等）。

4. 开始使用

在群聊中发送：

1
猫赛克 [图片]

机器人会自动处理并返回结果。

指令一览

指令 说明 示例
猫赛克 [图片] 单张图片打码 猫赛克 [图片]
猫赛克 [图片][图片] 多张图片打码 猫赛克 [图片][图片][图片]

配置详解

配置项 说明 默认值 推荐值
pythonPath Python 解释器路径 系统环境变量 根据安装路径设置
patternPath 自定义猫纹路图案 内置图片 本地 PNG 路径
headPath 自定义猫头图案 内置图片 本地 PNG 路径
autoClean 自动清理临时文件 true 建议开启

自定义图案

如果你想使用自己的图案，可以准备两张 PNG 图片（支持透明通道）：

1
2
3
4
plugins:
  hajimi-lizard:
    patternPath: 'C:/Users/yourPC/Desktop/my_pattern.png'
    headPath: 'C:/Users/yourPC/Desktop/my_head.png'

服务调用（开发者）

其他 Koishi 插件可以通过 ctx.hajimi 服务调用本插件，实现更复杂的自动化流程。

依赖声明

1
2
3
4
import { Context, Schema, h } from 'koishi'
import {} from 'koishi-plugin-hajimi-lizard'

export const inject = ['hajimi']

调用示例

1
2
3
4
5
6
7
8
9
10
// 批量处理图片
const urls = [
  'https://example.com/image1.jpg',
  'https://example.com/image2.png'
]

const results = await ctx.hajimi.processImages(urls)
for (const filePath of results) {
  await session.send(h.image(`file://${filePath}`))
}

返回值说明

processImages 方法接收一个图片 URL 数组，返回一个本地文件路径数组：

  • 输入：string[] - 图片 URL 列表
  • 输出：string[] - 处理后图片的本地路径
  • 空数组：表示未生成输出文件（可能是图片不符合处理条件）

实际使用场景

场景一：群聊自动打码

在群聊中配置一个自动打码机器人，群友发送图片后自动处理并回复：

1
2
3
4
[群友]：分享了一张"刺激"的图片
[机器人]：猫赛克 [图片]
[机器人]：图片处理中...
[机器人]：[猫猫打码后的图片] 😸

场景二：定时任务批量处理

配合定时任务插件，定期处理指定目录下的图片：

1
2
3
4
5
6
// 每天凌晨自动处理图片
ctx.setInterval(async () => {
  const images = getImagesFromFolder('/path/to/folder')
  const results = await ctx.hajimi.processImages(images)
  saveResults(results)
}, 24 * 60 * 60 * 1000)

场景三：二次开发

在自己的插件中嵌入打码功能，实现更复杂的图片处理流程，比如：

  • 先打码再加水印
  • 根据图片内容选择不同的覆盖图案
  • 与审核系统联动，自动处理违规图片

技术实现

技术栈

技术 用途
Koishi 机器人框架
YOLOv8 目标检测与分割
OpenCV 图像处理与透视变换
Python 模型推理
TypeScript 插件开发

核心算法

透视变换（Perspective Transform）是实现猫猫图案贴合的关键：

1
2
3
4
# 计算变换矩阵
matrix = cv2.getPerspectiveTransform(src_points, dst_points)
# 应用变换
transformed_head = cv2.warpPerspective(head_image, matrix, image.shape[:2][::-1])

通过计算检测区域的四个角点与猫头图案的对应关系，生成透视变换矩阵，将猫头图案精确贴合到目标区域，实现”以假乱真”的覆盖效果。

模型架构

1
2
3
4
5
6
7
8
9
输入图片
  ↓
YOLO 分类模型 → 判断内容类别（正常/敏感）
  ↓
YOLO 分割模型 → 生成目标区域掩码（Mask）
  ↓
OpenCV 处理  → 透视变换 + 图案覆盖
  ↓
输出图片

Python 环境配置指南

Windows

方法一：使用系统环境变量

  1. 下载安装 Python 3.8+（官网）
  2. 安装时勾选 “Add Python to PATH”
  3. 验证安装：python --version

方法二：指定路径配置

路径通常为：

1
C:\Users\你的用户名\AppData\Local\Programs\Python\Python313\python.exe

Linux/macOS

使用系统 Python

1
2
3
4
5
# 检查 Python 版本
python3 --version

# 设置环境变量（可选）
export PYTHON_PATH=/usr/bin/python3

常见问题

问题 解决方法
Python 不可用 检查 Python 是否安装，路径是否正确
pip 安装失败 检查网络连接，尝试更换 pip 源
模型加载失败 确认模型文件是否存在，版本是否匹配
OpenCV 报错 检查图片格式是否支持

性能优化建议

图片大小

建议将输入图片控制在 1920x1080 以下，过大的图片会显著增加处理时间。

批量处理

单次处理建议不超过 5 张图片，过多的并发处理可能导致内存不足。

GPU 加速

如果安装了 CUDA 版本的 PyTorch，YOLO 会自动使用 GPU 加速，处理速度可提升 5-10 倍。

缓存策略

开启 autoClean 自动清理临时文件，避免磁盘空间被占满。

常见问题

Q: 模型从哪里获取？

A: 模型文件提供内置下载功能。

Q: 可以识别哪些内容？

A: 这取决于你使用的模型。默认模型可以识别人物敏感部位，你可以使用自己的训练模型来识别其他内容。

Q: 处理速度太慢了怎么办？

A: 建议：

  • 降低输入图片分辨率
  • 使用 GPU 加速
  • 减少单次处理数量
  • 升级硬件配置

Q: 可以自定义覆盖图案吗？

A: 可以！通过配置 patternPath 和 headPath 指定你的图案文件（PNG 格式，支持透明通道）。

Q: 插件支持 macOS 吗？

A: Python 部分支持 macOS。

开发计划

  • 提供内置模型下载功能
  • 支持 GPU 加速自动检测
  • 添加更多覆盖图案选项（多种动物、文字等）
  • 优化处理性能，支持实时处理
  • 支持视频流处理
  • 提供 Web 管理界面

相关链接

🎉 让猫猫守护每一张图片！下一篇教程会介绍如何搭建自己的 Koishi 机器人，敬请期待！