dsh-plugin/ — DSH 侧插件

把「HTML/CSS → 逐节点 PNG + .ai-ui」做成 DSH 内的完整工作台。

状态

| 部分 | 状态 | |---|---| | Host：项目索引、组件编译、浏览器解析、加载等待、节点提取 | ✅ | | Host：check / export 两模式 + 隔离截图 | ✅ | | Host：/html2gameui 路由（API / 预览 / 文件） | ✅ | | Host：agent 工具 html2gameui_check / html2gameui_export | ✅（需 @deepseek-ai/dsh-tools 可解析） | | Host：内置 skill html2gameui-ui-authoring | ✅ | | Host：项目共享样式 style/tokens.css（编译内联 / 注入 system prompt / check 警告） | ✅ | | Client：主面板 / 侧栏入口 / 首页 / 总览 / 编辑器三栏 / 预览联动 | ✅ 已构建 | | Client：右栏 AI 对话（conversation.content 嵌入） | ⏳ 占位，待接入 | | 打包发布（files 只含 lib/ + skill/，不含 src/） | ✅ 独立 DSH_HOME 的 web profile 实测加载通过 |

渲染路径只有一条：headless Chrome（CDP 截图），不引入 snapdom / html2canvas / modern-screenshot 等库。 浏览器顺序：CHROME_PATH / chromePath → 系统 Chrome → 插件缓存 → 下载 chrome-headless-shell。

命令

npm install
npm test                 # 61 个测试（compile / export / routes / client bundle / host / style / server）
npm run build            # 构建发布产物：lib/index.mjs + lib/bin/*（Host 打包）+ lib/client.js（Client）
npm run build:host       # 只重打 Host 半（改 src/host 后）
npm run build:client     # 只重建 Client bundle（改 src/client 后）

# 源码直跑（开发态）
node bin/html2gameui.mjs <projectDir> <entryId> --mode check

# 发布产物直跑（和 npm 包内一致）
node lib/bin/html2gameui.mjs <projectDir> <entryId> --mode check

# 实际导出
node bin/html2gameui.mjs <projectDir> <entryId> --mode export --export-mode assets
node bin/html2gameui.mjs <projectDir> <entryId> --mode export --export-mode mockup

# 只编译组件引用（调试用）
node bin/compile.mjs <projectDir> <entryId>

可选参数：--kind screen|component、--out <dir>、--chrome-path <path>。

安装到 DSH

从 npm（发布后）

dsh plugin --profile web add dsh-plugin-html2gameui

本包声明了 dsh.bundle.patch（cordis.patch.yml），插件管理器把它当组合包安装并自动插入 id: html2gameui 行，不需要手改 profile patch；需要 chromePath 时在 profile patch 里用同 id 覆盖。

本地 link（开发）

npm run build            # link: 安装直接跑 lib/ 产物，必须先构建
dsh plugin --profile web add link:/home/luckyfeng/Desktop/project/dsh-plugins/html2game-ui/dsh-plugin

本地 link 安装不会自动启用组合包，需要在 ~/.dsh/profiles/web/cordis.patch.yml 末尾插入（注意是 - insert: 列表，不是裸的 - id: 行）：

- insert:
    - id: html2gameui
      name: "dsh-plugin-html2gameui"
      config:
        chromePath: "/path/to/chrome-headless-shell"   # 可选；本机没 Chrome 时必须给，或让它首次导出自带下载

patchReload: live 的 profile 会热加载；刷新 GUI 后左侧栏出现 HTML2UI。 验证：curl http://<gui-host>:<port>/html2gameui/api/health → {"ok":true,"version":0}。 （已在独立 DSH_HOME 的 web profile 里用打包产物实测：health / 项目列表 / client 进入 boot manifest 全通。）

发布（npm）

npm run build            # prepublishOnly 也会自动跑 build + test
npm pack --dry-run       # 检查 tarball：只有 lib/、skill/、cordis.patch.yml、README.md、package.json
npm publish              # 或 npm publish --registry <私有源>

发布包不含 src/、test/、spec/：Host 半在 npm run build 时由 esbuild 打成 lib/index.mjs（CLI 打成 lib/bin/*.mjs），资源由 src/host/root.mjs 按「向上找 package.json」 定位包根，打包前后路径一致。改动 Host 源码后记得重新 npm run build 再发布。

客户端插件常见坑（已在代码中修复，改 client 时注意）

1. 不要给 DSH 加载器暴露 default 导出：build 脚本只返回 { apply, inject }，否则组件会被当插件主体执行 → Invalid effect。
2. inject = ['slots'] 必须声明；否则 ctx.slots 未注入就开始执行 apply。
3. 所有槽位注册都要包 ctx.slots.inject(name, () => ctx.slots.register(...))；直接 register('sidebar.panellist', …) 会报 slot is not declared。
4. 安装时 cordis.patch.yml 用 - insert: 语法；改 package.json / 重建 bundle 后需要重启 dsh-web 才会重新组 boot graph（重启会换 token，旧页面会 401）。

HTTP 路由

| 路由 | 说明 | |---|---| | GET /html2gameui/api/health | 健康检查 | | GET /html2gameui/api/projects | 项目列表 | | POST /html2gameui/api/projects | {action:'create', rootDir,name,title,width,height} 或 {path} 注册已有项目 | | GET /html2gameui/api/projects/:id | 项目详情（含界面/组件索引） | | POST /html2gameui/api/check | {projectId, entryId, kind?} → 只校验 | | POST /html2gameui/api/export | {projectId, entryId, kind?, exportMode, outDir?} → 实际导出 | | GET /html2gameui/preview/:projectId/:entryId | 编译后 HTML + 选择脚本（预览 iframe / headless 共用） | | GET /html2gameui/file/:projectId/<rel> | 只读 assets/、fonts/ |

目录

src/host/
  index.mjs      DSH 插件入口（webServer 路由 / agent 工具 / skill provider）
  routes.mjs     /html2gameui 全部路由
  registry.mjs   项目注册表（$DSH_HOME/cache/html2gameui/projects.json）+ 新建骨架
  project.mjs    project.json 加载与校验
  compile.mjs    data-component 展开 + 组件样式提升
  style.mjs      项目共享样式（style/tokens.css 解析 / 编译内联 / 注入文本 / check 校验 / 变更监听）
  browser.mjs    浏览器解析（设置路径 → 系统 → 缓存 → 下载）
  server.mjs     临时预览服务（CLI 用；预览/导出共用加载路径）
  page.mjs       加载 + 显式等待（fonts.ready / 素材 decode / 稳定帧）
  extract.mjs    DOM → .ai-ui 节点树
  export.mjs     check / export 编排 + 隔离截图
src/client/index.jsx   主面板 + 侧栏 + 三栏 UI
src/host/root.mjs      包根定位（skill/、lib/ 的基准；打包前后一致）
skill/SKILL.md         内置 skill 正文（运行时按包根读取，随 npm 包发布）
scripts/build-host.mjs     esbuild → lib/index.mjs + lib/bin/*.mjs（Host 半打包）
scripts/build-client.mjs   esbuild → lib/client.js（ModuleLoader 包装）
bin/                   CLI 源码（开发态直跑；发布时打包进 lib/bin/）
lib/                   构建产物（提交，profile link 安装直接使用）：
  index.mjs            Host 半打包入口（package.json exports["."]）
  bin/html2gameui.mjs  check/export CLI 打包产物
  bin/compile.mjs      组件编译 CLI 打包产物
  client.js            Client bundle（exports["./client"]）
cordis.patch.yml       组合包 patch（npm 安装后自动启用插件行）
test/                  fixtures + node:test

契约见 ../spec/03-manifest-spec.md，流程见 ../spec/01-workflow.md。