视觉情绪板 Stijnus/dsh-moodboard

dsh-moodboard

English ·

给 DeepSeek Harness 用的视觉参考情绪板。在 Web UI 里收集截图和灵感图，打标签、写注释，把定义你应用视觉语言的那几张钉住，再让智能体在生成或改版 UI 之前先读这份风格指南。

面板采用 Warm Sand Studio 界面：暖沙色画布、白色卡片、单一珊瑚色点缀、深暖墨色、18–22px 柔和圆角、胶囊控件。它由 Harness 主题 token 构建，明暗跟随宿主。详见 docs/UI-REDESIGN.md。

预览

情绪板面板：暖沙色画布、当前风格指南、画廊、标签筛选和参考卡片

安装后快速上手：

1. 从侧边栏打开 Moodboard。页头显示图片数和已钉住数量，还有 Add images、Add from link、Paste image、Copy agent brief、快捷键帮助，以及低调的套件星标链接。
2. 添加参考：把文件拖到页面任意位置，用 ⌘V/Ctrl+V 粘贴，用 Add images 选文件，或打开 Add references 粘贴链接、搜索 Mobbin/Are.na。在那里加标签，并打开 Pin imported references。
3. 选中卡片打开检查器。改名称、标签、备注和来源 URL，把元数据复制/粘贴到另一张参考，或用 Style guide 开关钉住它。Manage 可以移动、替换或删除。
4. 用搜索框和标签 chip，在灯箱里打开参考，或 Cmd/Shift 点选多张卡片调出批量操作栏。按 ? 看快捷键。
5. 用输入框的 Moodboard 按钮插入参考指令，或从页头复制现成的智能体简报。

安装 · 环境要求 · 智能体 API · 限制

快速开始

最快的路径是 Plugins 页面：Add plugin → dsh-moodboard，它会安装包并启用 Moodboard 套件。从命令行：

dsh plugin --profile web add dsh-moodboard

命令行只负责安装包；Moodboard 套件仍需在 Plugins 页面启用。如果侧边栏条目未显示。

同系列更多插件：Moodboard · Composer Predictions · Move to Workspace · Workspace Status · Prompt Rewrite

⭐ 如果这个插件帮你省了一步，点个 star 能让下一位 DSH 用户找到它。

0.4 有哪些新变化

- Warm Sand Studio 重新设计。 暖沙色画布、白色卡片、一种珊瑚色强调色，用于主操作、固定项和激活的筛选器，深暖墨色，18px 卡片 / 22px 对话框 / 12px 输入框，胶囊按钮和标签，柔和暖色阴影。浅色和深色都从宿主 token 派生。
- 重新设计「添加参考」对话框。 渐变头部，分段式 From links / Discover 标签页，实时 n / 20 链接计数，一行真正的固定设置并附说明，底部粘性页脚，珊瑚色主按钮在右侧。
- 重新设计参考检查器。 顶部小标题行带实心 Style guide 胶囊标签，16:10 预览，分区标签带尾部横线，成组的移动按钮对，无边框移除，底部粘性页脚，禁用状态的 Save 看起来就是不可用。
- 响应式并经过验证。 窄屏下检查器变成底部抽屉；真实渲染测试台在浅色和深色下截取运行中的 client.js，覆盖页面、对话框、检查器、灯箱、批量操作栏和手机宽度。

完整历史：CHANGELOG.md。

你能得到什么

- Web UI 里的 Moodboard 面板（侧边栏图标），带珊瑚色标记、标题、图片/固定数量胶囊，以及一行操作：Add images、Add from link、Paste image、Copy agent brief、键盘快捷键帮助，还有低调的系列 star 链接。
- Warm Sand Studio 样式，从 --dsw-alias- 出发，经过本地 --mb- 层构建：暖色画布、卡片表面、细暖色边框、一种珊瑚色强调色、暖色墨色、基于 4px 的间距和柔和阴影。动效遵循 prefers-reduced-motion；焦点环、实时区域和带标签的控件都保留。
- 激活样式指南主区：固定缩略图、固定数量，以及「智能体在设计 UI 前会读这些图片」的提醒。点缩略图打开灯箱，就地取消固定，查看每条参考的顶部标签。
- 画廊：跨名称、标签、备注和来源搜索；同一粘性工具栏里带计数的标签胶囊；拖拽排序；Select all；懒加载分页缩略图；卡片悬停操作可展开、固定、替换和移除；固定徽章和 +n 标签溢出计数。
- 参考检查器：固定时顶部小标题行带实心 Style guide 胶囊标签，16:10 预览，以及分组的 Details（名称、标签、备注、来源 URL）、Metadata（复制/粘贴标签、备注和来源）、Style guide（固定开关以及智能体拿它做什么）和 Manage（移动按钮对、（替换、无边框移除，带行内确认）。粘性页脚显示已保存/未保存状态，并带 Cancel 和 Save。
- 添加参考对话框：From links / Discover 标签页、实时 n / 20 links 计数器、标签编辑器、固定设置行，以及带 Close 和珊瑚色主按钮的粘性页脚。Discover 有来源、查询、平台和结果字段，并带 Mobbin 密钥提示；结果会报告已添加 / 已在板上 / 失败的数量，并提供 Copy workflow。
- 采集：拖放图片文件、用 ⌘V/Ctrl+V 粘贴剪贴板内容、Paste image 和 Add images 按钮、Open Graph/Twitter 链接预览、Mobbin 和 Are.na 发现，以及通过智能体工具从浏览器 MCP 获取的本地截图路径。
- 整理：拖动卡片设置画廊顺序；Shift/Cmd 点击选中多张；浮动批量栏可固定、取消固定、打标签或移除所选内容；标签管理器可重命名标签，或在所有参考中合并标签，并显示每个标签的数量。
- 复用：从一条参考复制标签、备注和来源，粘贴到另一条，然后保存。
- 查找与查看：搜索和标签筛选可组合使用；以全尺寸灯箱打开任意参考，带上一张/下一张导航、位置计数器、Edit details、Pin/Unpin、标签、备注和来源。
- 实时同步：智能体通过 HTTP API 上传的参考（或在另一个窗口做的编辑）几秒内就会出现——无需刷新页面，也无需重启桌面应用。面板在激活时拉取画板，之后靠低成本的修订轮询加上窗口焦点 / 可见性检查保持最新。
- 键盘与无障碍：⌘V/Ctrl+V 粘贴、/ 搜索、⌘A 全选、⌘⇧A 反选、Alt+←/→ 重排聚焦的卡片、←/→ 浏览灯箱、Esc 清除或关闭、? 查看快捷键列表。对话框有标签且焦点被限制在内部；选中和筛选变化会通过实时状态区域播报。
- 智能体集成：
- moodboard 工具，带 active / query / list / get / brief / import / sources / workflow 动作。active 和 query 把参考图片本身作为图片内容块返回，让模型分析真实像素，外加标签、备注和来源 URL。
- moodboard:style-guide 系统提示词段落告诉智能体 moodboard 存在，设计 UI 前要先加载它。
- moodboard:inspiration-workflow 提示词段落和可复制的工作流，把参考变成 token 和组件，而不是照抄截图。
- 输入框里一个紧凑的 Moodboard 按钮，往草稿里插入指令，指向已固定的参考（它从不发送）。
- 持久化：元数据在重启后仍保留于 <DSH_HOME>/moodboard/board.json；图片字节存放在持久附件存储（<DSH_HOME>/attachments/v1）。跨会话、重载和重启都能存活。

自动拉取灵感

面板的 Add from link 按钮会打开 Add references 对话框，里面有两个入口：

- From links —— 粘贴最多 20 个公开页面 URL。Host 会抓取每个页面，保存它的 Open Graph/Twitter 预览图，以及标题、作者、站点、描述和规范来源 URL。直接粘贴图片 URL 也可以。
- Discover —— 搜索 Mobbin 截图（官方 REST API，需要 Team/Enterprise key）或 Are.na（公开，无需 key），一键添加结果。Mobbin 的图片 URL 会过期，所以插件会立即下载字节；Mobbin 的应用名和两个服务商的来源链接会保留为标签/备注。Discover 只接受 mobbin 和 arena 作为来源；其他 id 会在发出任何请求之前以 invalid-argument 拒绝。Are.na 搜索返回文本/图片混合的结果列表，所以只有图片块计入请求的结果数量 —— 文本块会跳过，不计数，也不报告为失败。

Add references dialog: From links and Discover tabs, live link counter, tags and pin setting

对话框是重新设计的录入界面：渐变标题栏配珊瑚色链接徽标、图标分段标签页、实时 n / 20 links 计数器、规整的 pin 设置行，以及带 Close 和最右侧珊瑚色主按钮的吸底页脚。导入完成后，它会显示已添加 / 已在板上 / 失败的数量、前几条失败信息，以及 Copy workflow 操作。导入不会关闭对话框；板子会在它背后静默刷新。

智能体通过 moodboard 工具拥有同样的能力：action: "import" 搭配 urls、paths（来自浏览器 MCP 的本地截图）或 source + query；action: "sources" 列出已配置的来源；action: "workflow" 返回从参考到组件的方法。

配置 Mobbin 可以用 MOBBIN_API_KEY 或 <DSH_HOME>/moodboard/sources.json（{ "mobbinApiKey": "…" }；默认 DSH home 是 ~/.dsh）。每次导入都会重新读取该文件，环境变量优先。Dribbble 会拦截服务端页面抓取，所以请用浏览器 MCP 抓取，或上传截图 —— 浏览器 MCP 的配置、来源矩阵和尊重设计师的规则见 docs/INSPIRATION-WORKFLOW.md。

查看与完善参考

选中画廊卡片，会在画廊旁边打开参考查看器。

Reference inspector: Style guide pill, 16:10 preview, Details and Metadata sections, sticky Save footer

查看器把工作界面放在参考旁边：

- Details —— 名称、带自动补全和逐标签删除的标签、备注、来源 URL 及 Open source link 操作，还有「Only http and https links are kept」提示。
- Metadata —— Copy tags & notes 会捕获标签、备注和来源 URL； 粘贴复制的元数据会把这些数据套用到另一个参考上，并把表单标记为已修改，直到你保存。
- 风格指南 —— 用作风格指南参考开关，提示语说明智能体在设计 UI 前会先读取这些固定图片。标题栏的风格指南胶囊标签同步显示固定状态。
- 管理 —— 一组左移/右移按钮，键盘和触屏都能用；一个替换操作；以及一个无边框的移除，带行内确认。
- 页脚 —— 已保存/未保存状态，加上取消和珊瑚色的保存按钮。禁用的保存按钮呈现为中性未激活表面，而不是一块坏掉的灰色方块。

检查器在宽屏上是 360px 的侧栏，低于 1100px 时收窄到 330px，1024px 及以下变成可关闭的底部抽屉。画廊、灯箱、批量操作栏、标签合并对话框和快捷键对话框都使用同一套 Warm Sand token。

从灵感走到组件

插件把这套方法做成提示词段落和可复制的工作流，而不只是一个画廊：

1. 收集 5–10 个针对同一任务的参考，附上来源链接。
2. 筛选，用角色标签（layout、type、palette、component、motion、flow）标注，并固定其中 2–4 个来定义方向。
3. 提取借鉴/规避笔记：结构、间距节奏、字号阶梯、颜色角色、圆角/阴影、图标风格、动效 —— 以及哪些不要照抄。
4. 转化成你自己的 token 和内容，适配页面原型。
5. 构建每个角色一个代表性组件，包含状态、深色模式、键盘/焦点、响应式行为和减弱动效。
6. 验证，在同一视口下：先看结构/节奏，再看字体/颜色，最后看交互；检查对比度、点击目标、溢出和动效降级。
7. 记录组件，并把固定的参考复用为风格指南。

完整指南：docs/INSPIRATION-WORKFLOW.md。

要求

DeepSeek Harness >=0.2.1-rc.3 <0.3.0-0，带 Web 配置档（Host 部分需要 attachments、tools、systemPrompt、webServer 和 connection；浏览器部分需要插槽和 locale 服务）。

安装

0.2.7 中已改名。 这个插件发布为 dsh-moodboard。早先的带作用域名 @stijnus/dsh-moodboard 已下架，所以现在固定到它会返回 404 —— 请安装 dsh-moodboard，并从你的配置档里删掉旧条目。

Plugins 页面一步完成安装包并启用 bundle。智能体的 plugin_manager 工具做同样的事：

plugin_manager action: "install_bundle" target: "dsh-moodboard"

install_bundle 安装包并选中 bundle；target 是包名或本地 bundle 的绝对目录。命令行命令只安装包：

dsh plugin --profile <profile> add dsh-moodboard

然后在 Plugins 页面启用 Moodboard bundle。如果侧栏图标没有立刻出现，重新加载 Web UI。

或者给 Discover 添加插件市场索引（Plugins → Discover → Index sources）：

- 套件索引： https://raw.githubusercontent.com/Stijnus/dsh-composer-predictions/main/market-index.json
- 仅用于 Moodboard 的索引： https://raw.githubusercontent.com/Stijnus/dsh-moodboard/main/market-index.json

开发

CI 运行 Node 24。插件没有运行时依赖，所以新克隆的仓库无需安装步骤：

git clone https://github.com/Stijnus/dsh-moodboard.git
cd dsh-moodboard
npm test # syntax checks + the full node:test suite
npm run pack:check # verify the published tarball file list

真实渲染测试台会在桩化的 Harness 宿主下执行实际的 client.js，并截取面板、Add references 对话框、检查器、灯箱、批量操作栏和响应式状态：

node verification/harness/capture.mjs

它通过 Playwright 的 playwright-core 驱动 Chrome；自定义入口请设置 HARNESS_PLAYWRIGHT_CORE，换用其他浏览器通道请设置 HARNESS_CHANNEL。生成的 PNG 只留在本地；shots/console.json 记录本次运行。详见 verification/harness/REPORT.md。

把本地检出的代码安装到配置档里做手动测试：

plugin_manager action: "install_bundle" target: "/absolute/path/to/dsh-moodboard"

Host 与 Client 两部分的当前构建约定见 docs/CONTRACT.md。

智能体 API

工具 moodboard

| action | 含义 |
| active（默认） | 已固定的风格指南；没有固定任何内容时返回整个画板。返回元数据和图片本身。 |
| query | 按标签过滤：tags: ["dark","typography"]，match: "any" \| "all"。返回匹配的图片。 |
| list | 每张图片的元数据，不含图片字节（轻量概览）。 |
| get | 按 id 取一张图片，附带完整备注、标签和来源 URL。 |
| brief | 纯文本风格简报（名称、标签、备注、来源）。 |
| import | 添加参考：urls（抓取链接）、paths（本地截图），或 source + query（Mobbin/Are.na 发现）。可选 tags、notes、pinned；发现时可用 platform（ios/web）和 limit（1–12）。 |
| sources | 列出已配置的灵感来源、本地配置路径和浏览器 MCP 桥接提示。 |
| workflow | 从参考到组件的方法，加上当前简报。 |

includeImages: false 会抑制图片内容块。每次调用最多返回 6 张图片内容。active 和 query 返回带参考 ID 的简略概览；要完整元数据请用 get，要找出所有参考 ID 请用 list。import 返回已导入的图片、duplicates（画板上已有的）和逐项的 failures；单项失败不会让整批失败。

HTTP 端点

Host 部分提供一个带鉴权的前缀路由 /moodboard（需要所有者会话 cookie，与 Web UI 同源）。智能体通常用工具；这些端点供面板和程序化读取使用：

| 方法 + 路径 | 用途 |
| GET /moodboard/api/state | 完整画板 + revision |
| POST /moodboard/api/images | 上传 { data, mediaType, name?, tags?, notes?, sourceUrl? } |
| PATCH /moodboard/api/images/<id> | 更新 name、tags、notes、sourceUrl、pinned、order |
| POST /moodboard/api/images/<id>/replace | 替换字节，保留元数据 |
| DELETE /moodboard/api/images/<id> | 删除 |
| POST /moodboard/api/images/reorder | 设置完整画廊顺序 { ids: [...] } |
| POST /moodboard/api/images/bulk | 批量 { ids, pinned?, addTags?, removeTags?, delete? } |
| POST /moodboard/api/tags/merge | 在整个画板范围内重命名/合并 { from, to } |
| GET /moodboard/api/active | 当前活动指南，含 tags/notes/sources/brief |
| GET /moodboard/api/query?tag=…&match=any&limit=50 | 按标签查找（limit 1–200，默认 50） |
| GET /moodboard/api/health | 存活检查 + 图片数量 |
| GET /moodboard/api/revision | 给打开的面板用的轻量变更检测器 { revision, updatedAt, images } |
| GET /moodboard/api/sources | 已配置的灵感来源、工作流文本、配置路径 |
| POST /moodboard/api/import | { urls } / { paths } / { source, query, platform?, limit? } + tags?、notes?、pinned?；返回 { imported, duplicates, failures } |
| GET /moodboard/image/<id>?v=<attachmentId> | 该 revision 对应的规范化图片字节 |

所有 JSON 响应都用 { ok: true, … } 或 { ok: false, error: { code, message } }。GET /moodboard/api/state 携带的进程内 revision 与 /api/revision 相同；面板把它（以及画板时间戳，这样 Host 重载也能被发现）与上次应用的值比较，只有任一发生变化时才重新读取完整画板。

数据

- 元数据：<DSH_HOME>/moodboard/board.json（原子写入；损坏文件会备份为 board.corrupt-<timestamp>.json，画板以空状态启动）。
- 图片：内容寻址，存放在 harness 附件存储中。上传时会做规范化（WebP/JPEG， UI 上传最大边 1600 px），且永不自动删除；移除画板条目只移除引用。
- 来源配置：<DSH_HOME>/moodboard/sources.json（可选；目前支持 { "mobbinApiKey": "…" } 和 snake_case 别名 mobbin_api_key）。环境变量 MOBBIN_API_KEY 优先。每次导入都会重新读取该文件。
- 如果保存的画板读不出来，或恢复备份写不进去，插件会报告存储错误并阻止变更。修好存储问题后重载插件；已有画板数据会保留。

视觉语言

插件界面通过一层小的本地变量（--mb-）组合 Harness 主题 token （--dsw-alias-）：暖沙色画布、白色卡片、暖色细边框、单一珊瑚色强调、深暖色墨色、18px 卡片、22px 对话框、12px 输入框和胶囊控件。亮色与暗色都从宿主 token 派生，所以面板跟随主题切换，无需主题钩子。动效安静克制（180ms；prefers-reduced-motion 会关掉过渡和上浮效果），焦点环可见，图片缩略图用的是用户自己的作品。设计说明和 token 表在 docs/UI-REDESIGN.md。

限制

- 最多 200 张图片，每张图 20 个标签（每个标签 48 字符），备注 4000 字符，名称 200 字符，来源 URL 2000 字符。
- 上传前会在客户端重新编码（最长边 1600 px，质量 0.85）；源文件上限 25 MiB，API 图片负载上限为 32 MiB 的 base64。
- 导入：每次调用最多 20 个链接或路径，每次调用最多 12 个发现项（默认 6）；远程页面上限 4 MiB，远程图片上限 12 MiB；只接受 http(s) URL，私有地址和回环地址会被拦截。
- Are.na 发现只把图片块计入请求的结果上限（文本块跳过）；source 只能是 mobbin 或 arena，其他值会在发出请求前以 invalid-argument 失败。
- moodboard 工具每次调用最多返回 6 个图片内容块。
- HTTP 端点对同源/浏览器调用方做所有者认证。bash/curl 调用方没有会话 cookie——请改用 moodboard 工具。

发布与来源

发布由 tag 驱动，从 GitHub Actions 用 npm 可信发布（OIDC）发布。仓库里不存长期有效的 npm token：npm 信任本仓库在打 tag 的提交上的 release.yml 工作流，那次运行签发的短期凭证无法在别处复用。

从 0.2.8 起，dsh-moodboard 的每次发布都附带来源证明，把 tarball 绑定到本仓库、工作流文件和提交。0.2.7（当前名称下的首个发布）没有证明，更早的 @stijnus/dsh-moodboard 版本已取消发布。npm 包页面会为有证明的版本显示 Provenance 徽章。

验证某个发布：

npm view dsh-moodboard@<version> dist.attestations
npm view dsh-moodboard@<version> dist.integrity

证明 URL 会解析到签名的 in-toto 声明；发布期间 npm 会打印对应的 Sigstore 透明日志条目。一次性的发布者设置、打 tag/发布步骤和发布后检查见 RELEASING.md；版本历史见 CHANGELOG.md。

许可证

MIT。图标和截图：本插件的原创作品；截图使用项目自己的参考板。