texteye — 图片转字符画（DeepSeek Harness 插件）

一个面向 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 动态插件（推荐，零配置文件）

1. 打开 DSH Web GUI，进入动态 Cordis 插件面板（cordis_define）。
2. 把 plugin.host.js 的全部内容粘贴为 code.host。
3. 运行（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色) |

颜色映射是怎么工作的

1. 图片被缩放到 width × rows（行数按字符高宽比 ≈ 2:1 折半，避免拉伸）。
2. 灰度：每个像素算亮度（0.2126R + 0.7152G + 0.0722B），映射到字符梯度的某一级。
3. 颜色：每个像素用感知色差（redmean 近似）匹配到最近的命名色，记下它的代号。
4. 图例汇总每个代号对应的颜色名 + 十六进制 + 占比。

所以模型同时拿到两幅对齐的网格：一幅看明暗/形状，一幅看颜色，配合图例即可理解“这里是什么颜色”。

目录结构

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