dsh-ui-mockup

English

在 DSH（DeepSeek Harness）研讨阶段生成 UI 草图 / 高保真设计稿的插件：让用户在写代码之前 确认界面方向，通过「生成 → 看图反馈 → 确认锁定 → 规格实现」闭环，避免实现完成后才发现界面不符合预期。

功能特性

• 内嵌展示：生成图直接以卡片形式显示在对话中（带确认 / 选用 / 修改意见按钮），无需访问文件目录；
• 标注式精准反馈（0.2.0）：点生成图进入标注弹窗；默认“选择/移动”可拖动画布、选择已有标记， 选中后可点删除按钮或在画布聚焦时用 Delete / Backspace 删除；切换矩形 / 画笔 / 箭头后圈选区域，说明栏会按当前工具给出操作提示；支持可撤销删除/清空、自动编号 ①②③，以及适合窗口、50%、100%、150%、200%缩放；编号归一化坐标与意见一并反馈；
• 方向稿与精修（0.2.0）：高保真先用 fastPreview + 「方向稿模型」档快速出方向稿， 确认方向后点「按这版精修」跑精修档，避免 pro 档 1~5 分钟的等待打水漂；
• 设计资产库：生成图 / 锚点 / 历史集中存于 $DSH_HOME/mockups/<工作区>/（slug 与 DSH sessions 同款）， 项目工作区不再落运行时产物；design/spec.md 等交付物仍留在项目内；
• 模型分层：按保真度分层，默认随生效提供方（百炼：线框 qwen-image-3.0 / 高保真 qwen-image-3.0-pro；火山仅承诺高保真 doubao-seedream-5-0-pro-260628 与整图编辑； 对火山的线框请求会在工具层拒绝并提示切换 Provider）；
• 当前万相能力：百炼仅支持 wan2.7-image / wan2.7-image-pro，使用新版异步图像端点， 支持文生图与单参考图 I2I；Wan 2.2/2.6 与旧 text2image 端点已废弃；
• 三提供方：阿里云百炼 DashScope（默认启用）、火山方舟 Volcengine Ark 与 OpenAI 兼容网关 （后两者预置未启用）；设置面板「提供方与模型」页点卡片一键切换——写入 DSH 用户层 patch 并热重载，无需重启；
• OpenAI 兼容网关（0.3.0）：面向 one-api / new-api 等私有聚合网关与官方 OpenAI—— POST {baseUrl}/images/generations 最小参数子集（model/prompt/n/size）与 b64_json/url 双返回格式归一；网关地址在统一的连接设置区中编辑（写用户层配置并热重载落位）； 模型分层为组合框：内置候选 ∪ 网关 /v1/models 拉取建议（失败静默降级），永远可手填； 尺寸按原始比例透传、错误透明透传；不支持参考图与指令编辑（显式 NOT_IMPLEMENTED）；
• 指令编辑：对已生成图传 baseImage + editNote 走整图指令重绘（火山 Seedream 5.0 Pro， 比整体重新生成更快更贴近原稿）；
• 安全语义引用：模型使用 design/images/<文件名> 引用资产；语义路径穿越会在工具层拒绝， 错误不会暴露资产库绝对路径，也无需把图片复制到项目；
• 风格一致：参考图模式（I2I）以已确认页面为基准图，多页面保持同一品牌视觉；
• 设计锁定：用户确认后自动提炼 design/spec.md，未确认的页面不进入实现；
• 限流退避：接口限流自动重试（Throttling 25s × 2）；
• 多语言：客户端 UI 完整支持 DSH 语言切换（zh / en）；
• 设置面板：设置窗口「UI 草图」入口下四页——概览（快速使用三步）、提供方与模型 （三列提供方选择 + 统一连接设置 + 三档模型默认）、生成偏好（持久化到 settings 命名空间， cordis.yml 为组合 base 层）、生成历史（搜索/方向稿筛选/清空/缩略图回看）；
• 风格锚点：历史页把某张生成图设为锚点后，ui_mockup 未显式传 reference 时 自动引用该图走 I2I，多页面风格保持一致；清空历史会一并解除锚点；
• 容错与反馈：损坏历史行不会拖垮面板，无换行坏尾行后的新记录仍可读取；部分图片下载 失败、附件超限和提供方切换未完成均有明确提示。

标注交互

切换到矩形、画笔或箭头后，固定高度的状态栏会提示如何切回“选择/移动”：

选中已有标记后，可点显式删除按钮，也可在画布聚焦时使用 Delete / Backspace：

安装

dsh plugin --profile web add @mackwan84/dsh-ui-mockup-bundle@0.3.0

安装完成后重启 DSH。开发本仓库时可改用本地路径：

dsh plugin --profile web add /path/to/dsh-ui-mockup/bundle/ui-mockup

使用环境

• DSH Web profile；
• 桌面端推荐宽度为 1024px 及以上，这是设置面板和结果卡片的正式验收基线；
• 至少配置一个图像服务凭据：阿里云百炼 DASHSCOPE_API_KEY、火山方舟 ARK_API_KEY， 或 OpenAI 兼容网关的 OPENAI_COMPAT_API_KEY 与网关地址；
• 耗时预期：线框图通常数十秒；高保真 pro 模型默认思考模式，单张 1~5 分钟属正常 （火山同步 API 默认窗口 300s）。生成卡片按工具调用时间显示本地已等待时长，刷新后继续累计； 该数值不能用于判断远端进度或存活状态。

配置

凭据按以下优先级读取，任选其一即可；生效提供方决定凭据名： DashScope 用 DASHSCOPE_API_KEY（阿里云百炼），火山方舟用 ARK_API_KEY，OpenAI 兼容网关用 OPENAI_COMPAT_API_KEY。

1. 进程环境变量：启动 DSH 前 export DASHSCOPE_API_KEY=sk-xxx（CI / 容器同理）；
2. DSH 密钥存储：~/.dsh/.credentials.yaml（在 DSH 设置 · 模型页写入，优先生效于 .env）；
3. 项目 .env：在启动目录（通常是项目根）的 .env 中写 DASHSCOPE_API_KEY=sk-xxx；
4. DSH 主目录 .env：~/.dsh/.env。

也可以不碰任何文件：直接在 设置 · UI 草图 · 提供方与模型 页的凭据卡里填入 新的密钥（写入即覆盖、永不回显，落到方式 2 的密钥存储；该页同时显示当前生效来源， 进程环境变量存在时写入会被拒绝并提示原因），并可点「测试连接」验证。

切换提供方（M4）

安装包预置三行 Provider（阿里云百炼、火山方舟、OpenAI 兼容网关），后两行默认 disabled: true。在 设置 · UI 草图 · 提供方与模型 页直接点击提供方卡片即可切换： 插件按「单选」把全部 Provider 行的 disabled 写入 DSH 用户层 patch（~/.dsh/cordis.patch.yml，只增改这些行的 id/disabled、不触碰其他内容），DSH 热重载 组合后立即生效，无需重启：

- id: image-dashscope
  disabled: false
- id: image-volcengine
  disabled: true
- id: image-openai-compat
  disabled: true # OpenAI 兼容网关默认未启用

详见 bundle README。

使用

在对话中直接说「出个草图」，或由 agent 在需求研讨时主动提议。推荐流程：

1. 先生成线框图验证布局，或用 fastPreview 生成高保真方向稿；
2. 点击生成图进入标注弹窗，用矩形、画笔或箭头标出要修改的区域；
3. 用“选择/移动”调整画布或选择已有标记，通过按钮或 Delete / Backspace 删除；
4. 提交编号区域与修改意见，确认方向后点“按这版精修”或“确认采用”；
5. Agent 按反馈重新生成，或把已确认设计提炼到 design/spec.md。

开发

• docs/README.md — 完整文档导航与维护约定
• docs/README.en.md — 面向国际 npm 用户与集成开发者的英文文档导航
• docs/guides/product-guide.md — 产品使用指南与 FAQ
• docs/architecture/overview.md — 当前架构、能力边界与关键实现事实
• docs/releases/v0.3.0.md — v0.3.0 候选验收结论与尚未执行的发布步骤

常用命令：

pnpm test          # 单元 + 组合测试（无需先构建）
pnpm typecheck     # 全仓 TypeScript 检查（根 tsconfig 统一入口）
pnpm lint          # ESLint（js/ts 推荐 + 类型感知规则）
pnpm lint:fix      # ESLint 自动修复
pnpm format        # Prettier 全仓格式化
pnpm format:check  # Prettier 格式检查
pnpm build         # 构建五个 Provider/工具包的 lib/
pnpm run pack:all  # 打包 6 个 tarball 到 dist/（image + 3 家 Provider + tool + bundle）
pnpm run publish:all # 先由 pnpm 转换 workspace: 协议，再按依赖顺序发布 6 个 tarball

License

详见 LICENSE。