texteye — 图片转字符画（DeepSeek Harness 插件）
Image → ASCII art + 逐格颜色映射，让纯文本模型也能“看懂”图片。
一个面向 DeepSeek Harness（DSH）的图片可视化插件：把任意图片（PNG / JPEG / WebP / GIF / BMP …）转换成纯文本，让没有视觉能力的文本模型也能读取图片的形状、明暗和颜色。
English abstract: a DeepSeek Harness plugin that converts any image into plain-text ASCII art plus an optional per-cell color map and legend, so text-only models can "see" images — with configurable detail, a color-mapping layer, and a fast no-color grayscale mode.
特性
- 灰度字符画（ASCII art）：把亮度映射成字符，呈现形状与明暗。
- 逐格颜色映射（color map）：每个字符格对应一个颜色代号，附图例（代号 = 颜色名 + 十六进制），让模型能“读出颜色”。
- 多种清晰度：用
width（字符列数）控制细节，20–200 可调。
- 多种字符集：
ascii / block（░▒▓█ 平滑）/ detail（更细）三种亮度梯度。
- 两种颜色板：
basic（8 色）与 full（16 色，含橙/棕/粉等）。
- 多种输出模式：
both（灰度 + 颜色）、gray（快速检查）、color（只看颜色）。
- 纯 Python + Pillow，无其它依赖；单文件、可独立命令行运行，也可作为 DSH 插件内嵌。
- 智能降级提示：若当前模型已支持图像输入（
inputModalities 含 image），工具会在结果顶部提示「优先用 read_image/原生视觉」，字符画只作为有损回退；纯文本模型则直接得到字符画。
效果预览
输入一张 320×240 的测试图（四个象限分别是红/绿/蓝/黄，中央白色圆 + 黑点）：
=== 灰度字符画 (brightness -> character) ===
------------------:-++++++++++++++++++++
------------------:-++++++++++++++++++++
--------------------++++++++++++++++++++
----------------::::++++++++++++++++++++
--------------::-+**###*++++++++++++++++
-------------:-#@@@@@@@@%*++++++++++++++
:::::::::::::-%@@@@##@@@@@++++++++++++++
-------------+@@@@* +@@@@#*************
==============%@@@@##%@@@@%%%%%%%%%%%%%%
=============-=#@@@@@@@@@%%%%%%%%%%%%%%%
==============--=*##%%%%%%%%%%%%%%%%%%%%
================---=#%%%%%%%%%%%%%%%%%%%
====================#%%%%%%%%%%%%%%%%%%%
==================-=#%%%%%%%%%%%%%%%%%%%
==================-=#%%%%%%%%%%%%%%%%%%%
=== 颜色映射 (one code per cell) ===
RRRRRRRRRRRRRRRRRRRRGGGGGGGGGGGGGGGGGGGG
RRRRRRRRRRRRRRRRRRRRGGGGGGGGGGGGGGGGGGGG
RRRRRRRRRRRRRRRRRRRRGGGGGGGGGGGGGGGGGGGG
...
BBBBBBBBBBBBBBBBBBBBYYYYYYYYYYYYYYYYYYYY
=== 图例 (code = name, hex) ===
R = red #E00000
G = green #00A000
B = blue #0040E0
Y = yellow #FFD000
W = white #FFFFFF
K = black #000000
模型据此即可判断：左上红、右上绿、左下蓝、右下黄，中间有一个白色圆、圆心有个黑点。
想看一张真实动漫插画的完整转换效果（含颜色图例与「模型能看到什么」的解读），见 examples/real-world-example.md。
环境要求
- Python 3.7+
- Pillow：
pip install Pillow
pip install Pillow
插件通过 ctx.shell 调用 python，请确保 python 在宿主机的 PATH 中（Windows / Linux / macOS 均可）。
安装与使用
方式一：作为 DSH 动态插件（推荐，零配置文件）
- 打开 DSH Web GUI，进入动态 Cordis 插件面板（
cordis_define）。
- 把
plugin.host.js 的全部内容粘贴为 code.host。
- 运行（
cordis_run）。插件会注册一个模型可见的工具 image_to_ascii。
之后模型（或你在对话里）直接调用它即可：
image_to_ascii(path="examples/test.png", width=80, mode="both", palette="full")
说明：动态插件是会话级的，随当前 DSH 进程/会话存在，进程重启后不保留。若要永久挂载，用下面的「方式三」。
方式二：永久安装为 profile 插件（out-of-tree）
plugin.mjs 是自包含的 Host 插件模块，配合 cordis.patch.yml 与 package.json 的 dsh.bundle 声明，可作为 out-of-tree 插件装进某个 dsh profile，重启后依然生效。
发布到 npm 后（推荐，最省心）：
dsh plugin --profile web add texteye
本地源码安装（未发布时）：
cd texteye && dsh plugin --profile web add .
⚠️ Windows 已知坑：pnpm 对 file:/link: 的跨盘绝对路径（如 F:/...）解析有 bug，会生成失效的 junction。跨盘本地安装时，可改为把 plugin.mjs、cordis.patch.yml、package.json 三个文件手动拷贝到 $DSH_HOME/profiles/<name>/node_modules/texteye/，并在该 profile 的 cordis.patch.yml 里加一行 - insert: [{ id: tool-image2ascii, name: 'texteye' }]。发布到 npm 后走 registry 名则无此问题。
方式三：命令行直接运行（不依赖 DSH）
# 灰度模式，快速看个大概
python image2ascii.py photo.png --width 60 --mode gray
# 灰度 + 颜色映射（默认）
python image2ascii.py photo.png --width 80 --mode both --palette full
# 只看颜色
python image2ascii.py photo.png --width 40 --mode color --palette basic
输出是 JSON：ascii（灰度网格）、colorMap（颜色网格）、legend（图例）。
配置说明
| 参数 | 类型 | 默认值 | 可选值 | 说明 |
|---|
path | string | —（必填） | 任意图片路径 | 相对工作区或绝对路径 |
width | number | 80 | 20–200 | 输出字符列数，越大越清晰（细节越多） |
mode | string | both | both / gray / color | both=灰度+颜色；gray=仅灰度（快速检查）；color=仅颜色 |
charset | string | ascii | ascii / block / detail | 亮度→字符的梯度：ascii(10级) / block(░▒▓█ 5级平滑) / detail(25级) |
palette | string | full | full / basic | 颜色映射的命名色板：full(16色) / basic(8色) |
颜色映射是怎么工作的
- 图片被缩放到
width × rows（行数按字符高宽比 ≈ 2:1 折半，避免拉伸）。
- 灰度：每个像素算亮度（
0.2126R + 0.7152G + 0.0722B），映射到字符梯度的某一级。
- 颜色：每个像素用感知色差（redmean 近似）匹配到最近的命名色，记下它的代号。
- 图例汇总每个代号对应的颜色名 + 十六进制 + 占比。
所以模型同时拿到两幅对齐的网格：一幅看明暗/形状，一幅看颜色，配合图例即可理解“这里是什么颜色”。
目录结构
texteye/
├── README.md # 本文件
├── LICENSE # MIT
├── package.json # 仓库元信息
├── image2ascii.py # 唯一事实来源：转换逻辑（可独立 CLI 运行）
├── build.py # 把 image2ascii.py 内嵌进插件，重新生成 plugin.host.js
├── plugin.host.js # 生成产物：DSH Host 插件（粘贴即用）
└── examples/
├── make_test_image.py # 生成一张测试图
└── test.png # 测试图
修改转换逻辑请编辑 image2ascii.py，然后运行 python build.py 重新生成 plugin.host.js（会校验脚本里没有反引号与 ${）。
常见问题
- 报错 “Pillow is required”：宿主没装 Pillow，
pip install Pillow 即可。
python 找不到：把 Python 加入系统 PATH，或确认插件宿主机能直接执行 python --version。- 输出被截断：
width 太大时字符画很长；默认已给 4MB 输出预算，一般无需担心。
- 透明 PNG 变黑：已自动把透明背景合成到白色，避免 alpha 变黑。
License
MIT
