dsh-pixel-studio
English | 中文
面向 DeepSeek Harness 的
像素画 / 像素动画生成插件。模型可以用 oy-pixel 风格的 shader 脚本程序化
生成，也可以编写调色板索引网格或使用模板 + 动作参数；插件把结果显示为
聊天内原生 Canvas，并同时导出可直接用于游戏开发的素材文件。
特性
- 聊天内原生画布：播放/暂停、逐帧、1-24× 最近邻缩放、网格、洋葱皮、
调色板、craft 分数；不再使用交付物卡片或独立 viewer 作为主界面。 - 三个工具：
pixel_shader用程序化脚本生成形状、渐变、纹理和动画；
pixel_art生成静态像素画；pixel_animation支持显式逐帧或基础精灵 +
动作预设。 - oy-pixel 同构 shader 设计：Canvas 绘图 API、
pal/mix/hsv/alpha/rand/noise、
time/phase/frame_index/frame_count、确定性种子、形状裁剪、stamp。
语言是安全 Lua 子集，不是嵌入完整 Lua；设计契约与 oy-pixel 对齐。 - 真实素材导出：透明 PNG、GIF89a、精灵表 + JSON atlas、OYPX v2 工程、
manifest；独立 HTML viewer 可选。 - 绘画技巧约束：注册 DSH 系统提示词段
pixel-studio:craft，把
oy-pixel 的PIXEL_AGENT_INSTRUCTIONS工作流和PIXEL ART CRAFT/
PIXEL ANIMATION CRAFT技巧注入每次生成。 - Craft 报告：自动检查对比度、孤立像素、循环缝、帧时长、颜色数量和
剪影覆盖率，并写入工具结果与 manifest。 - 零运行时依赖：Host 只用 Node 内置模块；Shader 在受限解释器中执行；
Client 使用 DSH 自带的 React。 - 不访问网络：只读写 Session 工作目录下的文件。
环境要求
- DeepSeek Harness 0.2.1-rc.2 或更高，0.2.x 范围内
- Node.js 20+（开发/测试）
- DSH Web GUI（Client 半侧声明为
platform: "web"）
安装
本包同时是 DSH 组合包（bundle） 和插件：Host 入口 lib/index.js、Client
入口 lib/client.js、dsh.bundle.patch 指向 cordis.patch.yml，以及
dsh.client 声明。安装器会读取该 patch 并自动插入 pixel-studio 行，不要再
手工把这一行复制到 profile 的 cordis.patch.yml。
插件管理器（推荐，Desktop 也可用）
在 设置 → 插件 → 安装 中填入：
https://github.com/Fantety/dsh-pixel-studio
或已配置 GitHub SSH 时：
git+ssh://git@github.com/Fantety/dsh-pixel-studio.git
安装器会安装包、把 dsh-pixel-studio 加入 profile 的 dsh.profile.bundles，
并应用包内 patch。不需要手写 loader 行。
CLI 管理的 profile
把 my-profile 替换为实际名称（如 web、headless 或自定义 profile）：
dsh plugin --profile my-profile add \
"git+ssh://git@github.com/Fantety/dsh-pixel-studio.git"
命令会把包操作转发给 pnpm，并同步 profile 的 bundle 列表。确认
~/.dsh/profiles/my-profile/package.json 的 dsh.profile.bundles 包含
dsh-pixel-studio；之后加载器会应用包内 cordis.patch.yml 插入插件行。
desktop profile 由 Electron 管理，请使用插件管理器安装，不要手改该 profile。
重新加载 profile，然后刷新一次 Web 页面以加载 Client bundle。刷新后工具卡片
仍是通用卡片时，重启一次 DSH。
预构建 Release tarball
每个 v* tag 会发布一个不带版本号文件名的 tarball：
https://github.com/Fantety/dsh-pixel-studio/releases/latest/download/dsh-pixel-studio.tgz
可直接安装：
dsh plugin --profile my-profile add \
"https://github.com/Fantety/dsh-pixel-studio/releases/latest/download/dsh-pixel-studio.tgz"
也可作为商店的 tarball: 地址。文件名刻意不带版本号，避免
releases/latest/download/ 在下个版本后失效。
awesome-dsh-plugin 条目
仓库已声明 dsh.bundle 并提供 Release tarball。可直接提交到
data/plugins/Fantety__dsh-pixel-studio.yml：
url: https://github.com/Fantety/dsh-pixel-studio
name: Fantety/dsh-pixel-studio
category: fun
description:
en: In-chat pixel art and animation tools with a procedural shader, native canvas, and PNG/GIF/OYPX export.
zh: 聊天内像素画与像素动画工具，支持程序化 Shader、原生 Canvas 与 PNG/GIF/OYPX 导出。
tarball: https://github.com/Fantety/dsh-pixel-studio/releases/latest/download/dsh-pixel-studio.tgz
本地开发：
cd ~/.dsh/profiles/my-profile
pnpm add "link:/absolute/path/to/dsh-pixel-studio"
然后在 profile 的 package.json 中把 "dsh-pixel-studio" 加入
dsh.profile.bundles，再重新加载。若 profile 里还留着旧的 pixel-studio
手工 insert 行，请删除；现在由包内 patch 负责该行。
使用
直接用自然语言：
> 画一个 32×32 的苔藓史莱姆，左上打光，做成 8 帧漂浮动画，导出 PNG、GIF 和 OYPX。
直接调用：
{
"name": "moss-slime",
"template": "slime",
"palette": "sweetie16",
"effects": { "outline": true, "shadow": true },
"outputDir": "pixel-art"
}
使用 legend 手绘：
{
"name": "tiny-heart",
"legend": { "O": "#3B0D1A", "R": "#EF4B6B", "L": "#FF9FB2" },
"grid": [
".OO..OO.",
"ORROORRO",
"ORLRRRRO",
"ORRRRRRO",
".ORRRRO.",
"..ORRO..",
"...OO...",
"........"
],
"scale": 12
}
动画：
{
"name": "native-ghost",
"template": "ghost",
"palette": "sweetie16",
"effects": { "shadow": true, "shadowColor": "#00000055" },
"motion": { "preset": "float", "frames": 8, "amplitude": 1 },
"fps": 12,
"loop": 0,
"scale": 10
}
程序化 shader
pixel_shader 对齐 oy-pixel pixel_run_shader 的设计：脚本在 Canvas 上绘制，
使用 pal()、mix()、hsv()、alpha()、rand()、noise()，通过
time / phase 采样动画帧。语言是受控 Lua 子集（不是完整 Lua）：
{
"name": "shader-horizon",
"width": 32,
"height": 32,
"palette": "studio",
"seed": 12,
"code": "for y = 0, height - 1 do\n local t = y / (height - 1)\n for x = 0, width - 1 do canvas.pset(x, y, mix(hex('#0B1026'), hex('#FF8A5C'), t * t)) end\nend\ncanvas.circfill(width * 0.7, height * 0.72, 7, hex('#FFEC27'))"
}
支持 local、赋值、调用、if/elseif/else、数值 for、while、break、
表构造和 [key] 索引；Canvas API 包括 pset/pget/line/rect/rectfill/
circle/circfill/ellipse/ellipsefill/flood/replace/outline/clear/stamp。
没有文件系统、网络、require 或宿主全局，脚本受指令数、时间和像素修改预算限制。
完整 API 和与 oy-pixel 的设计映射见 docs/SHADER.md。
输出
pixel-art/
moss-slime.png 透明 PNG
moss-slime-preview.png 最近邻棋盘格预览
moss-slime.gif 动画 GIF
moss-slime-sheet.png 精灵表
moss-slime-sheet.json 帧图集
moss-slime.oypx oy-pixel v2 工程
moss-slime.json 资源清单 + craft 报告
moss-slime-viewer.html 可选：includeViewer: true
内嵌 Canvas 预算：131,072 像素 / 4,096 色（超过 64 色时每像素使用两个符号），
超限时退回为打开文件的紧凑面板。
GIF 透明度为 1-bit，时间粒度为 10 ms。OYPX 最多 256 色。
开发与测试
git clone git@github.com:Fantety/dsh-pixel-studio.git
cd dsh-pixel-studio
npm test
npm run check
npm run demo
npm run demo:showcase
npm run demo:shader
代码结构：
lib/
index.js Host 入口
plugin.js DSH 工具注册、参数校验、内嵌画布
craft-prompt.js oy-pixel 工作流 + 绘画技巧系统提示词段
client.js Client 工具视图
pixel/ 渲染、编码、导出、craft 检查
pixel/shader.js 程序化 shader 运行时 + Canvas API
pixel/lua/ Lua 子集 lexer/parser/interpreter
scripts/ 示例生成脚本
test/ Node 测试
examples/ 生成结果示例
docs/ 架构说明
许可证与致谢
本项目使用 MIT License，与 DeepSeek Harness 的许可证一致。
绘画技巧文本改编自 oy-pixel
（Copyright © 2026 Fantety）。详见
THIRD_PARTY_NOTICES.md。
