awesome-dsh-plugin 插件截图声明完全指南screenshots.json 约定详解与常见错误避坑【免费下载链接】awesome-dsh-pluginA curated list of plugins for DeepSeek Harness (dsh) · DeepSeek Harness 插件精选列表项目地址: https://gitcode.com/gh_mirrors/aw/awesome-dsh-pluginawesome-dsh-plugin是 DeepSeek Harnessdsh插件的精选列表每个插件以 data/plugins/ 下的一份 YAML 文件收录。想让插件在市场详情页像 App Store 一样展示截图只需在自己的仓库放一个screenshots.json文件即可。本文讲清这个截图声明约定的完整写法以及那些让截图静默消失的常见错误。先拿到列表仓库想对照本文核对脚本行为可克隆列表仓库git clone https://gitcode.com/gh_mirrors/aw/awesome-dsh-plugin截图约定本身的官方说明在 contributing.md 的 Screenshots 一节本文是它的展开版。screenshots.json 是什么让插件拥有截图墙插件市场如 dsh-market 的详情页会读取每个条目的截图字段以横向轮播的形式展示。约定只有一条核心规则截图清单放在你自己的仓库里与package.json并列monorepo 条目则放在对应子包目录里。列出 1–8 张图片路径// 你的仓库/screenshots.json [ assets/screenshot-1.png, assets/screenshot-2.png ]路径相对于该文件本身指向你仓库里已经存在的图片。不声明也没关系——市场会自动从你的 README 里抽取图片作兜底声明的价值在于由你控制展示顺序与取舍。screenshots.json 的 4 种写法纯数组最省心解析器见 scripts/probe-screenshots.mjs接受 4 种形状按顺序识别写法示例评价纯数组[assets/a.png]✅ 推荐最简洁命名对象{screenshots: [assets/a.png]}✅ 同样标准以条目 URL 为键{https://github.com/owner/repo: [...]}复制旧数据时可用任意单键映射{my-plugin: [...]}仅恰好一个键时生效⚠️ 注意第 4 种只有文件里恰好只有一个键才会被识别成数组多写一个键整个声明就失效了——写之前确认自己用的是前两种即可。截图声明的红线5 个常见错误让截图消失1. 图片超过 8 张。上限硬编码为 8probe-screenshots.mjs#L53多一张整份声明作废回退到 README 抽取。2. 绝对 URL 用了 http 或第三方图床。绝对 URL 仅接受https 且域名是 GitHub 自家托管raw.githubusercontent.com、user-images.githubusercontent.com、camo.githubusercontent.com、github.com。第三方图床被拒——否则一张截图可能变成埋在每个市场用户浏览器里的追踪像素。scripts/build-site.mjs#L344-L356 的注释把这条理由写得很直白。3. 相对路径越界。不能以/开头、不能含..probe-screenshots.mjs#L134-L138。一个条目只负责自己的子目录树这是 monorepo 里的边界约定。4. 空声明。空数组、空字符串、不是 JSON 数组——任何一条都会让声明被判无效。文件解析失败时不会报错给站点只是静默回退你以为声明生效了其实市场展示的是 README 里的图。5. 改了图却忘了改路径。这正是相对路径的红利也是风险你在自己仓库里重命名图片构建立刻发现 404你能看到、能修反过来旧约定里写死在别人仓库里的绝对 URL 烂掉时谁也不会知道——历史数据里 773 张已发布截图中有 41 张就是这样变成 404 的。为什么文件必须放在你自己的仓库这是整个约定最值得理解的部分三个理由contributing.md#L183-L187换截图不用求人。推自己的仓库即可下一次夜间构建自动生效——不提 PR、不等维护者。坏链可见。相对路径在你自己仓库里改名就会立刻断掉写死在列表仓库的绝对 URL 只会悄无声息地烂掉。永不冲突。没有别人会编辑你的文件截图投稿之间不再互相踩踏。构建如何校验两个脚本各管一段scripts/probe-screenshots.mjs 逐条读取各插件仓库 HEAD 上的screenshots.json校验形状后做存活性探测404/410 判死结果写入data/screenshots-declared.json与data/screenshots-live.json。死图只会被静默丢弃条目保留其余截图——坏图降级站点而不是阻断构建。scripts/build-site.mjs#L344-L421 在站点构建时校验旧文件、合并两个来源作者自声明优先于列表仓库里的旧记录。CI 里的awesome-lint与站点构建会拦下格式问题失败信息直接告诉你改什么——同一分支推送修复即可无需重开 PR。旧版 data/screenshots.json正在退役的兜底早于该约定的条目截图仍记在列表仓库的 data/screenshots.json按条目 URL 为键的映射。它是有终点的回退不是第二个存放地你的仓库一旦自声明scripts/prune-legacy-screenshots.mjs 会清理掉旧键文件清空后整体删除。请勿再往里面加新键。另外提醒一句若你调整了仓库子包路径记得检查 data/screenshots.json 里是否还挂着旧 URL 的键——过期的截图键会让构建直接失败见 scripts/scan-decay.mjs#L355。提交前 5 问快速自查文件是否和package.json同级monorepo 在子包目录是否为合法 JSON 的数组且 1–8 张每个路径是否非空、不以/开头、不含..图片是否真的已提交到仓库对应分支用绝对 URL 的话是否 https 且域名在 GitHub 托管白名单内全部通过你的插件截图墙就只差下一次构建了。约定不复杂复杂的是静默失败——把这 5 个问题当成习惯截图就永远不会莫名其妙消失。✅【免费下载链接】awesome-dsh-pluginA curated list of plugins for DeepSeek Harness (dsh) · DeepSeek Harness 插件精选列表项目地址: https://gitcode.com/gh_mirrors/aw/awesome-dsh-plugin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考