像素工坊 Fantety/dsh-pixel-studio

dsh-pixel-studio

面向 DeepSeek Harness 的像素画 / 像素动画生成插件。模型可以用 oy-pixel 风格的 shader 脚本程序化生成，也可以编写调色板索引网格或使用模板 + 动作参数；插件把结果显示为聊天内原生 Canvas，并同时导出可直接用于游戏开发的素材文件。

模板总览

原生幽灵动画

程序化 shader 场景

特性

- 聊天内原生画布：播放/暂停、逐帧、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。