dsh-gpt-image-playground 0.2.1 → 0.2.2

package/README.md

@@ -1,5 +1,9 @@
 # GPT Image Playground for DeepSeek Harness
 
+[![npm](https://img.shields.io/npm/v/dsh-gpt-image-playground?label=npm)](https://www.npmjs.com/package/dsh-gpt-image-playground)
+[![license](https://img.shields.io/npm/l/dsh-gpt-image-playground)](LICENSE)
+[![node](https://img.shields.io/node/v/dsh-gpt-image-playground)](package.json)
+
 把 [CookSleep/gpt_image_playground](https://github.com/CookSleep/gpt_image_playground) 的**原版工作台**装进 [DeepSeek Harness](https://github.com/deepseek-ai)（DSH）：左栏多一个「生图工作台」，点开就是完整的画廊 / Agent 双模式、参考图与遮罩编辑、多供应商、收藏夹、历史管理。
 
 界面与功能来自上游官方构建（v0.8.3，原样 vendor），插件自己只负责**同源托管**和**可选的 API 代理**。
@@ -8,54 +12,47 @@
 
 ## 安装
 
-### 1. 从 DSH 插件市场（收录后）
-
-DSH 0.2.1+ → **插件 → 发现**，搜索 `GPT Image Playground`。
+### 用 npm 包名（推荐）
 
-### 2. 用 npm 包名
-
-DSH → **插件 → 安装**，填：
+在 DSH 里打开 **插件 → 安装**，填：
 
 ```
 dsh-gpt-image-playground
 ```
 
-命令行等价：`dsh plugin --profile desktop add dsh-gpt-image-playground`
+装完在插件列表里启用，刷新页面（Ctrl+R），左栏出现「相框」图标。
 
-### 3. 从本仓库（本地目录）
+命令行等价：
 
 ```bash
-git clone https://github.com/southcul/dsh-gpt-image-playground
+dsh plugin --profile desktop add dsh-gpt-image-playground
 ```
 
-DSH → 插件 → 安装 → 填克隆下来的目录**绝对路径**。装完在插件列表里启用。
+### 从 Release 压缩包
 
-### 4. 从 Release 压缩包
+下载 [最新 Release](https://github.com/southcul/dsh-gpt-image-playground/releases/latest) 里的 `gpt-image-playground-<版本>.zip`，解压后二选一：
 
-下载 Release 里的 `gpt-image-playground-<版本>.zip`，解压后二选一：
+- DSH 插件页 → 安装 → 填解压目录的**绝对路径**（推荐）
+- 或右键 `install.ps1` → 使用 PowerShell 运行
 
-- DSH 插件页 → 安装 → 填解压目录的绝对路径（推荐）
-- 或右键 `install.ps1` → 使用 PowerShell 运行（内部是 `node install.mjs --copy`）
-
-### 5. 直接链接开发
+### 从仓库源码
 
 ```bash
-node install.mjs             # junction 到桌面 profile，改代码即热加载
-node install.mjs --uninstall # 卸载
+git clone https://github.com/southcul/dsh-gpt-image-playground
 ```
 
-装好刷新页面（Ctrl+R），左栏出现「相框」图标。
+DSH → 插件 → 安装 → 填克隆目录的绝对路径。
 
 ## 第一次使用
 
 1. 打开工作台 → 右上角齿轮 → **API 配置**，填 API URL 与 Key（存在本机浏览器存储，不上传）。
-2. 如果报「接口不支持浏览器跨域请求」：点工作台**左下角 ⚙**（iframe 外的小按钮），填真实 API 地址，保存；再把面板里显示的代理地址复制到应用的「API URL」。
+2. 若提示「接口不支持浏览器跨域请求」：点工作台**左下角 ⚙**（iframe 外的小按钮），填真实 API 地址并保存；再把面板里显示的代理地址复制到应用的「API URL」。
 
 代理地址形如 `http://127.0.0.1:13807/plugins/dsh-gpt-image-playground/proxy`，请求由 DSH 主机转发，`Authorization` 与 multipart 图片体原样透传。
 
 ## 功能
 
-完整继承上游，包括：
+完整继承上游：
 
 - 画廊 / Agent 双模式；批量生成、迭代、多提示词提交、流式预览
 - 参考图（最多 16 张）、遮罩编辑器、画板标注（画笔/文字/图形/像素橡皮擦）、评论定位
@@ -66,78 +63,17 @@ node install.mjs --uninstall # 卸载
 
 ## 与上游的差异
 
-- 隐藏右上角三个按钮（安装为应用 / 下载客户端 / 操作指南），按 `aria-label` 注入 CSS 实现，不改上游代码。
-- 关闭上游公告卡（`vendor-app/announcements.json` 为 `[]`）。
-- 工作台跑在常驻 iframe 里（见下），因此 DSH 的窗口级快捷键不穿透到应用内部。
-
-## 为什么 iframe 常驻在 `shell.overlay`
-
-DSH 的 `main` 槽是 keyed 槽，只渲染当前选中的那一项：切到别的面板会卸载工作台。iframe 若挂在这个面板里，切换面板就会销毁文档，正在跑的生成请求随之中断（表现为「报错但没有原因」）。
-
-所以：`main` 里只放占位盒登记矩形，iframe 住在常驻的 `shell.overlay` 条目里；切走时只是 `display:none`，请求继续跑，回来还是同一个文档。
-
-## 结构
-
-```
-lib/index.js          宿主半侧：静态托管、同源代理、设置读写、精简原生 API
-lib/client.js         浏览器半侧：槽位注册、常驻 surface、代理面板、界面裁剪
-vendor-app/           上游构建产物（index.html / assets / 字体）
-cordis.patch.yml      组合包 patch
-install.mjs           安装/卸载（--link 开发、--copy 分发）
-install.ps1           Windows 一键安装（包装 install.mjs --copy）
-publish.ps1           npm 发布（用 DSH 自带的 pnpm）
-tools/vendor-dist.mjs 重新抓取上游构建
-tools/pack.py         打 zip / tgz
-tools/test-pack.mjs   验证分发包可安装、可卸载、复制后仍可挂载
-test-server.mjs       宿主半侧自测（原生 API + 静态托管 + 代理透传）
-client-test.mjs       浏览器半侧自测（注册 + 样式）
-```
-
-## 发布到 npm
-
-**第一次发布？看 [docs/first-publish.md](docs/first-publish.md)，从注册账号到别人装上，一步一步。**
-
-```bash
-node tools/set-repo.mjs southcul --author "southcul"   # 仓库信息（已配好，换仓库时再跑）
-powershell -ExecutionPolicy Bypass -File .\publish.ps1  # 校验 → 测试 → 发布
-```
-
-- 凭证：`.npmrc` 里放 `//registry.npmjs.org/:_authToken=npm_…`（已在 `.gitignore` 中）
-- `prepublishOnly` 会自动跑两套自测 + `check-package`，任一项失败就不发布
-- 预演：`.\publish.ps1 -DryRun`；双因素认证：`.\publish.ps1 -Otp 123456`
-- 校验可单独跑：`node tools/check-package.mjs`（加 `--strict` 时占位符也算失败）
-- 发布后自查：`node tools/test-npm-tarball.mjs`（把 tarball 装进临时目录并实际挂载）
-
-## 开发
-
-```bash
-node test-server.mjs        # 宿主半侧
-node client-test.mjs        # 浏览器半侧
-node tools/pack.mjs         # 重新打 dist/（zip + tgz）
-node tools/test-pack.mjs    # 分发包回归
-node preview/serve.mjs --port 4518
-node tools/test-switch.mjs  # 切换面板不中断生成的回归测试
-```
-
-更新上游：
+界面裁剪与信息改写都在 iframe 内用注入的方式完成，**不改上游构建产物**：
 
-```bash
-node tools/vendor-dist.mjs  # 从 GitHub Pages 抓官方构建
-node tools/pack.mjs
-```
-
-内置字体默认**不随包分发**（HarmonyOS Sans SC 三个字重 + Maple Mono，约 23 MB）：界面会回退到系统字体，显示正常。需要离线内置字体时：
-
-```bash
-node tools/fetch-fonts.mjs  # 下载到 vendor-app/assets，然后重新打包
-```
+- 隐藏右上角三个按钮：安装为应用 / 下载客户端 / 操作指南
+- 隐藏设置页的「关于」标签（上游的更新检查与赞助入口；第三方许可仍随包提供，见 `THIRD-PARTY-NOTICES.md`）
+- 设置页右上角的版本徽标改为**本插件版本**（不带提示、不显示上游版本）
+- 关闭上游公告卡（`vendor-app/announcements.json` 为 `[]`）
+- 工作台运行在常驻 iframe 中，因此 DSH 的窗口级快捷键不穿透到应用内部
 
-发布：
+![设置页](docs/screenshot-settings.png)
 
-```bash
-powershell -ExecutionPolicy Bypass -File .\publish.ps1   # npm
-git tag v0.2.1 && git push origin v0.2.1                 # GitHub Release（Actions 打包含附件）
-```
+工作台之所以常驻在 `shell.overlay` 而不是 `main` 面板里：DSH 的 `main` 是 keyed 槽，切换面板会卸载工作台，正在跑的生成请求会随 iframe 一起被销毁。现在占位盒只负责定位，iframe 切走时仅隐藏、不卸载。
 
 ## 许可与致谢
 

package/SHARE.md

@@ -1,217 +1,66 @@
 # 分享给你的朋友
 
-产物在 `dist/`：
+插件已经在 npm 上，所以**最省事的方式只需要一句话**：
 
-| 文件 | 大小 | 用途 |
-|---|---|---|
-| `gpt-image-playground-0.2.1.zip` | ~1.5 MB | 直接发给朋友，解压 + 双击安装 |
-| `dsh-gpt-image-playground-0.2.1.tgz` | ~1.5 MB | npm 包，用于 `npm publish` 或 `pnpm add` |
+> DSH → 插件 → 安装 → 填 `dsh-gpt-image-playground`
 
-两个包内容一致（91 个文件）：插件代码、上游构建产物（`vendor-app/`）、许可证与第三方声明、安装脚本。不含测试、预览环境、API Key 或你的配置。
+装完在插件列表里启用，刷新页面（Ctrl+R），左栏出现「相框」图标。
 
 ---
 
-## 方式零：在 DSH 里直接装（不用脚本，朋友最省事）
+## 方式一：让朋友直接装（推荐）
 
-DSH 自带的插件管理器接受**包名、GitHub 地址、本地目录**三种输入：
+DSH 里打开 **插件** 页 → **安装 / 添加插件** → 「包名或地址」填：
 
-1. 让朋友把 zip 解压到任意目录（记住路径）。
-2. DSH 里打开 **插件** 页（侧边栏「插件」，或设置里的插件列表）→ **安装 / 添加插件**。
-3. 「包名或地址」里填解压出来的目录**绝对路径**，例如：
-
-   ```
-   C:\Users\Alice\Downloads\dsh-gpt-image-playground-0.2.1
-   ```
-
-4. 安装完成后在插件列表里**启用**它（`dsh.profile.bundles` 里勾上），刷新页面。
-
-要点：
+```
+dsh-gpt-image-playground
+```
 
-- 必须填**绝对路径**，且该目录里要有 `package.json`（zip 解压后的顶层目录正好）。
-- 装的是包里 `files` 声明的部分，`preview/`、`tools/`、测试不会被复制过去。
-- 这种装法会记成 `file:` 依赖，所以那个目录**别删也别移动**；想搬到别处就重新装一次。
-- 已发布 npm 之后，这里直接填包名 `dsh-gpt-image-playground` 更省事。
-- 推送 GitHub 之后，也能填仓库地址（形如 `https://github.com/你/dsh-gpt-image-playground`）。
-- `.tgz` 只支持 **http(s) 直链**；本地 `.tgz` 文件路径不被当作目录，会报「请输入有效的包名或地址」。
+安装后**启用**它，刷新页面即可。
 
-> 你这台机器上插件已经装好了（链接模式），在本机再走一次会提示「这个包已经安装」。方式是给朋友用的。
+**对方需要**：DSH 桌面端（能打开插件页），以及自己的图片 API（工作台里配置）。
 
 ---
 
-## 方式一：发 zip（兜底，适合不想操作的场景）
-
-1. 把 `dist/gpt-image-playground-0.2.1.zip` 发给朋友。
-2. 朋友解压到任意目录（**不要**放进 DSH 安装目录）。
-3. 右键 `install.ps1` → **使用 PowerShell 运行**（或在 PowerShell 里跑）：
-
-   ```powershell
-   powershell -ExecutionPolicy Bypass -File .\install.ps1
-   ```
+## 方式二：发 Release 压缩包（对方网络不便时）
 
-   脚本会自动找 DSH 自带的 Node，把插件复制进 profile、写进依赖与启用列表，改文件前先备份。
-4. 刷新 DSH 页面，左栏出现「生图工作台」。
+1. 从 [Releases](https://github.com/southcul/dsh-gpt-image-playground/releases) 下载 `gpt-image-playground-<版本>.zip` 发给对方。
+2. 对方解压到任意目录（**不要**放进 DSH 安装目录）。
+3. 二选一：
+   - DSH 插件页 → 安装 → 填解压目录的**绝对路径**（推荐）
+   - 或右键 `install.ps1` → **使用 PowerShell 运行**
 
-**对方需要**：已安装并登录过一次 DSH 桌面端（脚本依赖它的 profile 与 Node 运行时）。不需要自己装 Node。
+**对方需要**：已安装并登录过一次 DSH 桌面端；不需要自己装 Node。
 
 **卸载**：在解压目录执行 `node install.mjs --uninstall`。
 
 ---
 
-## 方式二：发布到 npm（朋友只填一个包名）
-
-你这台机器**没有装 npm 命令**，但有 DSH 自带的 pnpm，够用。仓库里已备好 `publish.ps1`。
-
-### 1. 准备 Token（只需一次）
-
-1. 没有 npm 账号就先在 https://www.npmjs.com/signup 注册。
-2. 打开 https://www.npmjs.com/settings/<你的账号>/tokens → **Generate New Token** → 选 **Automation**（这类 Token 发布时不会被要求输入 OTP）。
-3. 复制 Token（`npm_` 开头，只显示一次）。
-
-### 2. 写凭证（只需一次）
-
-在插件目录新建 `.npmrc`（已加进 `.gitignore`，不会入库）：
-
-```
-//registry.npmjs.org/:_authToken=npm_你的Token
-```
-
-### 3. 发布
-
-先把仓库地址补上（npm 页面会显示源码链接，严格校验也要求它）：
-
-```powershell
-node tools\set-repo.mjs <你的GitHub用户名> --author "你的名字"
-```
+## 方式三：从 GitHub 装
 
-然后：
+让对方在 DSH 插件页填仓库地址：
 
-```powershell
-powershell -ExecutionPolicy Bypass -File .\publish.ps1
 ```
-
-脚本依次做：**包内容校验 → 两套自测 → 预演 → 发布**，任一步失败就中止。
-
-不想用脚本就手动跑（本机没有全局 `node`，要先把它加进 PATH，否则 `prepublishOnly` 会失败）：
-
-```powershell
-$env:PATH = "$env:USERPROFILE\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\node\bin;$env:PATH"
-node "$env:USERPROFILE\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\pnpm\bin\pnpm.mjs" publish --no-git-checks
+https://github.com/southcul/dsh-gpt-image-playground
 ```
 
-- `--no-git-checks` 是因为这个目录可能还不是 git 仓库。
-- 账号开了双因素认证且用的是普通 Token：加 `-Otp 123456`（或 `--otp=123456`）。
-- 包名想加作用域（`@你/dsh-gpt-image-playground`）：改 `package.json` 的 `name`，发布时加 `--access public`。
-- 先预演：`.\publish.ps1 -DryRun`（会跑测试与打包，只是不上传）。
-- 单独校验：`node tools/check-package.mjs`；发布后自查：`node tools/test-npm-tarball.mjs`。
-
-包名 `dsh-gpt-image-playground` 目前 **未被占用**（查注册表返回 404），可以直接用。
-
-### 4. 验证
-
-- 浏览器打开 `https://www.npmjs.com/package/dsh-gpt-image-playground`
-- 或看注册表：`https://registry.npmjs.org/dsh-gpt-image-playground`
-
-### 5. 朋友安装
-
-DSH **插件页 → 安装**，填：
-
-```
-dsh-gpt-image-playground
-```
-
-或命令行 `dsh plugin --profile desktop add dsh-gpt-image-playground`。
-
-### 6. 以后发新版
-
-1. 改 `package.json` 的 `version`（例如 `0.2.1`）
-2. 上游有更新就先 `node tools/vendor-dist.mjs`
-3. `python tools/pack.py` 重打 zip/tgz（可选，npm 路线不需要）
-4. 再跑一次 `publish.ps1`
-
-朋友那边要先**卸载再安装**（插件管理器对非官方包不做原地升级，会提示「其他插件请先卸载再安装新版」）。
-
-### 可能踩的坑
-
-| 现象 | 原因 / 处理 |
-|---|---|
-| `EOTP` / 要求一次性密码 | 用 Automation Token，或加 `-Otp` |
-| `E403 无法发布` | 包名被占（改名）、Token 无 publish 权限、或账号邮箱未验证 |
-| 网络超时 | 你的网络对 npm 有时不稳；重试，或给 pnpm 配代理（`HTTPS_PROXY`） |
-| 发布成功但朋友装不到 | 注册表同步有延迟，等一会儿；或确认他填的是包名不是本地路径 |
+或先 `git clone` 下来，再填本地目录的绝对路径。
 
 ---
 
-## 方式三：放到 GitHub，并进入 DSH 市场
-
-GitHub 负责**存放与分发**，但要让别人在 DSH 里**搜到**，还需要目录收录——而目录只收 npm 包。所以完整顺序是：**npm 发布 → 推 GitHub → 提交目录**。
-
-### 1. 推到 GitHub
-
-仓库里已经准备好 `.gitignore`、`LICENSE`、`THIRD-PARTY-NOTICES.md`、README 截图、Release 工作流。
-
-```bash
-cd dsh-gpt-image-playground
-git init
-git add .
-git commit -m "feat: GPT Image Playground as a DSH plugin"
-git branch -M main
-git remote add origin https://github.com/southcul/dsh-gpt-image-playground.git
-git push -u origin main
-```
-
-提交前确认 `dist/`、`.npmrc`、`preview/.data/` 没被带进去（`.gitignore` 已排除）。
-
-### 2. 打标签，自动出 Release
-
-```bash
-git tag v0.2.1
-git push origin v0.2.1
-```
-
-`.github/workflows/release.yml` 会：跑 `tools/pack.py` 打 zip/tgz → 建 Release 并附上两个包。若在仓库 Secrets 里配了 `NPM_TOKEN`，还会顺便 `npm publish`（带 provenance）。
-
-### 3. 让朋友从 GitHub 装
-
-- 下载 Release 里的 zip，解压后在 DSH 插件页填目录路径
-- 或 `dsh plugin --profile desktop add https://github.com/southcul/dsh-gpt-image-playground`
-
-### 4. 进 DSH 插件市场（关键一步）
-
-市场的索引是 npm 包 `dsh-plugin-catalog`，由 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 自动构建；索引里每个版本都标着 `"source": { "type": "npm" }`——**没有 npm 包就不会被收录**。
-
-1. 先完成方式二（`publish.ps1`），确认 `https://registry.npmjs.org/dsh-gpt-image-playground` 能打开。
-2. 按 [docs/awesome-submission.md](docs/awesome-submission.md) 里给出的条目格式，提交到 awesome-dsh-plugin：
-   - 站点 https://awesome-dsh-plugin.com/ 右上角 **Submit**
-   - 或仓库 issue / PR，贴上条目 JSON + npm 包名 + 仓库地址 + 两张截图
-3. 收录后，DSH → 插件 → 发现 → 搜「Playground」即可一键安装，并能看到更新。
-
-### 5. 以后发新版
+## 朋友第一次用会遇到的两件事
 
-```bash
-# 改 package.json 的 version
-python tools/pack.py
-.\publish.ps1
-git add -A && git commit -m "chore: release v0.2.1"
-git tag v0.2.1 && git push origin v0.2.1
-```
+1. **要配 API**：工作台里点右上角齿轮，填 API URL 与 Key。数据只存在他那台机器的浏览器存储里。
+2. **可能跨域**：如果提示「接口不支持浏览器跨域请求」，点工作台**左下角 ⚙**（iframe 外的小按钮），填真实 API 地址，再把面板里显示的代理地址复制到应用的「API URL」。
 
 ---
 
-## 分享前检查清单
+## 安装小贴士
 
-- [ ] `package.json` 的 `version` 和 `description` 是你想要的
-- [ ] `dsh.upstream.version` 与实际 vendor 的上游版本一致（当前 **0.8.3**）
-- [ ] `THIRD-PARTY-NOTICES.md` 在包里（MIT 要求保留上游版权声明）
-- [ ] 没有把自己的 `settings.json`（代理目标）、API Key、历史图片打进去
-- [ ] 确认 zip 里的 `INSTALL-FIRST.txt` 说明和你的安装方式一致
-
-## 朋友第一次用会遇到的两件事
-
-1. **要配 API**：工作台里点右上角齿轮，填 API URL 与 Key。数据只存在他那台机器的浏览器存储里。
-2. **可能跨域**：如果提示「接口不支持浏览器跨域请求」，点工作台**左下角 ⚙**（iframe 外的小按钮），填真实 API 地址，再把面板里显示的代理地址复制到应用的「API URL」。
+- 填本地目录时必须是**绝对路径**，且目录里有 `package.json`（zip 解压后的顶层目录正好）。
+- 这种装法会记成 `file:` 依赖，那个目录**别删也别移动**；要挪就重装一次。
+- 插件提供方更新后，非官方包需要先**卸载再安装**（插件管理器会提示）。
 
-## 版本与兼容
+## 许可
 
-- 插件面向 DSH 桌面端（0.2.x 运行时）开发，用到 `main` / `shell.overlay` 槽位与 `webServer` 路由。
-- 上游构建固定为 v0.8.3；上游更新需要重新 vendor（见 README「更新上游」）。
-- 你自己继续开发时用链接模式（`node install.mjs`），分发时用复制模式（zip 里的 `install.ps1`）。
+MIT；界面来自上游 GPT Image Playground（作者 CookSleep，同为 MIT），详见包内 `THIRD-PARTY-NOTICES.md`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-gpt-image-playground",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "GPT Image Playground as a DeepSeek Harness plugin: the upstream image generation and editing workbench, vendored, served same-origin, with an optional API proxy.",
   "type": "module",
   "main": "lib/index.js",