dsh-plugin-agent-sprite-forge

把 Agent Sprite Forge 的三个 2D 游戏素材技能，封装成一个可直接安装的 DSH 插件。

装上它，DSH 里就多了 generate2dsprite、generate2dmap、video2dsprite 三个技能——不需要再手动往 ~/.agents/skills 或 ~/.dsh/skills 里拷目录。

---

为什么需要封装

原项目以「技能目录」形式分发，使用者要自己把 skills/ 下的目录复制到 DSH 扫描的技能根目录。这样做有两个问题：

1. 路径不可知。技能的 SKILL.md 里写着「运行 scripts/generate2dsprite.py」，但脚本实际装在哪里，随 profile、操作系统、包管理器布局而变。agent 无法自己推出这个绝对路径，于是照着文档敲命令就会找不到文件。
2. 装了就散。技能目录和插件是两套东西，卸载、迁移、换机器都要各管一遍。

本插件解决这两点：技能通过 ctx.skills 服务注册（走 DSH 官方的运行时注册通道），同时在挂载时把自己所在目录解析成绝对路径，追加到每份技能正文末尾，所以文档里写的命令在目标机器上直接就能跑。

技能以 runtime 来源注册，而不是再挂一个文件系统 provider。这是因为 dsh-skill-filesystem 本来就会扫描 $DSH_HOME/skills 和 ~/.agents/skills；如果插件也指向文件系统，就会和你手动装的那一份撞名，最后由目录 rank 决定谁赢——那种「取决于文件放哪」的行为很难排查。运行时注册没有这个歧义。

---

安装

方式零：从 npm 安装（推荐，可被搜索到）

在 DSH 侧边栏 插件 页面的安装框里输入包名：

dsh-plugin-agent-sprite-forge

DSH 会自己完成安装与 bundle 启用，不需要跑下面的脚本。

这条路的前提是这个包已经发布到 npm。若搜索不到，见仓库根目录的 PUBLISH.md。

方式一：一键脚本（本地 zip / 文件夹）

把整个文件夹拷到同事电脑上，在文件夹里执行：

# 若提示"禁止运行脚本"，改用下面那条
.\install.ps1

powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1

脚本会：

1. 把本包复制到 <profile>\plugins\dsh-plugin-agent-sprite-forge\
2. 在 profile 的 package.json 里加上 bundles 条目和 file: 依赖
3. 修改前先备份 package.json

自动找 profile 的顺序：-Profile 参数 → $DSH_HOME\profiles 下唯一带 package.json 的目录 → ~/.dsh/profiles/desktop。

指定 profile：

.\install.ps1 -Profile "$env:USERPROFILE\.dsh\profiles\desktop"

脚本可重复执行：第二次运行会提示 Bundle : already listed，不会写重复条目。

方式二：手动安装

1. 复制到 profile：

   <profile>\plugins\dsh-plugin-agent-sprite-forge\
   

2. 编辑 <profile>\package.json，把包名加进 bundles，并加一条 file: 依赖：

   {
     "dsh": {
       "profile": {
         "bundles": [
           "@deepseek-ai/dsh-base",
           "@deepseek-ai/dsh-web-app",
           "dsh-plugin-agent-sprite-forge"
         ]
       }
     },
     "dependencies": {
       "dsh-plugin-agent-sprite-forge": "file:./plugins/dsh-plugin-agent-sprite-forge"
     }
   }
   

3. 重启 DSH。

本包自带 cordis.patch.yml，加进 bundles 后插件行会自动挂载，不需要再改 cordis.patch.yml。

安装后确认

重启后新开一个会话，问一句：

有哪些可用的技能？

或直接触发一次，例如「用 generate2dsprite 画一个像素风史莱姆 idle 动画」。插件挂载成功时，日志里会有：

agent-sprite-forge: publishing generate2dsprite, generate2dmap, video2dsprite from <...>\skills

---

运行依赖

技能的 Python 脚本需要 numpy 和 Pillow：

python -m pip install numpy Pillow

• Python 3.10 或更高（脚本用到 X | None 类型语法）。
• 如果目标机器上解释器不叫 python（比如只有 python3），改插件配置里的 pythonCommand，见下节。
• 插件本身对 Node 侧没有额外依赖，用的是 DSH profile 已有的包。

---

配置

插件行由本包的 cordis.patch.yml 提供，默认值如下：

- insert:
    - id: agent-sprite-forge
      name: dsh-plugin-agent-sprite-forge
      config:
        skills:
          - generate2dsprite
          - generate2dmap
          - video2dsprite
        exposeScriptsDir: true
        pythonCommand: python

字段	默认值	说明
skills	三个技能全开	要发布的技能目录名，必须是本包 skills/ 下的目录。只想要一部分就删掉不要的。
exposeScriptsDir	true	是否把绝对脚本路径和执行说明追加到技能正文末尾。
pythonCommand	python	文档里使用的解释器名。目标机器只有 python3 时改成 python3，或写绝对路径。
packageRoot	自动探测	本包根目录。默认由模块自身位置推出，一般不用填。

要覆盖配置，在 profile 的 cordis.patch.yml 里按 id 改：

- id: agent-sprite-forge
  config:
    pythonCommand: python3

---

包结构

dsh-plugin-agent-sprite-forge/
├── package.json          插件清单（dsh.bundle 指向 cordis.patch.yml）
├── cordis.patch.yml      挂载行与默认配置
├── install.ps1           安装脚本
├── lib/
│   └── index.js          插件本体：读 SKILL.md → 注册到 ctx.skills
└── skills/               上游技能原样收录
    ├── generate2dsprite/ 精灵图/动画表：角色、怪物、法术、投射物、特效
    ├── generate2dmap/    分层地图：地面底图、装饰参考、道具包、瓦片集、Godot 场景
    └── video2dsprite/    视频转密集 2D 精灵序列

每个技能目录保持上游结构（SKILL.md + references/ + scripts/ + agents/），未做改动。

---

技能怎么被加载

dsh-plugin-agent-sprite-forge 挂载
        │
        ├─ 校验 skills/ 目录存在（不存在就报错，不静默发布残缺目录）
        │
        ├─ 逐个读 skills/<id>/SKILL.md
        │     ├─ 解析 YAML frontmatter（name / description / whenToUse / invocation）
        │     ├─ 校验目录名与 name 一致、name 为 kebab-case
        │     └─ 追加执行环境块（绝对脚本路径 + 解释器）
        │
        └─ ctx.skills.registerProvider(...) + ctx.skills.register(...)

正文末尾追加的块长这样：

## Execution environment (added by dsh-plugin-agent-sprite-forge)

This skill is installed inside the DSH plugin `dsh-plugin-agent-sprite-forge`,
not in a user skills directory. Use these absolute paths when you run its scripts:

- Scripts directory: `<插件安装目录>\skills\generate2dsprite\scripts`
- Interpreter: `python`

Run a script as `python "<...>\generate2dsprite.py" --help` before
using it, so you pass the flags this version actually defines.
...

这样无论插件被装到哪个盘、哪个 profile，agent 拿到的都是一条能直接执行的命令。

---

常见问题

技能没出现？ 检查重启后日志有没有 agent-sprite-forge: publishing ...。没有的话，多半是 bundles 里没加包名，或 profile 的 package.json JSON 语法坏了（脚本改之前有 .bak-* 备份，可以直接还原对比）。

python 不是内部或外部命令？ 机器上没装 Python 或不在 PATH。装完后把 pythonCommand 改成实际命令（如 python3 或绝对路径）。

脚本报 ModuleNotFoundError: No module named 'numpy'？ python -m pip install numpy Pillow。注意要用 pythonCommand 指定的那个解释器装。

和我手动装在 ~/.agents/skills 的旧版冲突怎么办？ 本插件注册的是 runtime 来源，在同一层里优先级高于用户目录。但两份内容不同步时容易看花眼，建议删掉手动那份，统一由插件管理。

改了 skills/ 下的文件会怎样？ 会立即影响该 profile 下所有会话——注册是只读共享的。要改内容请改本包源目录再重新安装。

---

许可

本包包含两部分，均为 MIT：

部分	版权
skills/ 下的三个技能	Copyright (c) 2026 0x0funky，逐字收录自上游
插件外壳（lib/、cordis.patch.yml、install.ps1、文档）	本插件作者

上游 MIT 全文见 LICENSE，收录范围与署名见 THIRD-PARTY-NOTICES.md。

skills/ 的内容不是本插件作者的作品，再分发时请保留 LICENSE 与 THIRD-PARTY-NOTICES.md。