如何给DSH小鲸鱼挂件贡献代码：分支策略、Issue与PR规则的完整指南-拓冰网站定制

如何给DSH小鲸鱼挂件贡献代码：分支策略、Issue与PR规则的完整指南

【免费下载链接】DeepSeek-Balance-Whale-WidgetDeepSeek Harness（DSH）一只住在 DSH 界面右下角的小鲸鱼娘，帮你盯着DeepSeek账户余额。QQ弹弹，支持拖拽吸附、左吸附翻转、数字滚动动画，随界面自动启用，建议直接喊来你的dsh安装项目地址: https://gitcode.com/gh_mirrors/de/DeepSeek-Balance-Whale-Widget

DeepSeek-Balance-Whale-Widget 是 DSH 小鲸鱼余额挂件（DSH Whale Widget），一只住在 DeepSeek Harness（DSH）Web 界面右下角的小鲸鱼娘，帮你盯着 DeepSeek 账户余额、今日已用和每轮对话消耗。本文是一份面向新手的贡献代码完整指南，讲清楚三条分支怎么选、Issue 怎么提才不被白做、PR 必须满足哪些规则，让你第一次提 PR 也能顺利合入。

动代码前：先认识仓库结构

贡献前先花一分钟熟悉几个关键文件（完整说明见 CONTRIBUTING.md）：

文件	作用
package.json	插件元数据，npm 包名`dsh-whale-widget`，发布版本号就写在`version`字段里
cordis.patch.yml	插件挂载声明，DSH 启动时按它把挂件插进 Web profile
lib/index.js	宿主侧本体：23 条路由 + 记账接线 + 音效/图片/角色服务（约 3,953 行）
lib/accounting.mjs	记账内核：定点金额运算 + 余额观测/校正账本
assets/whale-widget.js	前端挂件本体（约 16,853 行，宿主按 mtime 热读这个单文件）
whale-widget-prompt.md	完整规格、视觉参数、路由清单，二次开发的入口文档
tools/z-layer-audit.mjs	浮层 z 层级自检脚本，CI 与发布流程都会跑

💡 如果你的 PR 更新了仓库结构，请顺手更新 CONTRIBUTING.md 里的「仓库结构」一节，保持最新。

分支策略：三条分支怎么选

本仓库有三条互不兼容的产品线，选错分支的 PR 会被直接关闭：

你要改的东西	用哪条分支	说明
DSH Web 界面里的挂件（主产品）	`main`	npm 包`dsh-whale-widget`
Codex 桌面伴随挂件	`For-Codex`	npm 包`api-balance-whale`，独立维护
Windows 桌面版（Tauri）	`For-WinDesktop`	—

三条要点记牢：

平台移植类改动必须提到对应分支，提到main会被关闭；
三条分支未来会整合成同一个 —— 除非你的多平台重构方案 issue 通过了维护者批准；
main和For-Codex各自独立维护，无共享代码、无跨分支依赖。

Issue 规则：怎么提才不白做

Issue 是贡献的起点，项目对 Issue 的态度写得很直白：

🐛bug 一定会修；
✨功能建议不一定会采纳—— 目的是避免代码无限变臃肿；
📝 提 issue 时请明说：是你自己想实现这个 issue，还是希望维护者或别人帮你实现；
未来的 feat（新功能）/ refactoring（重构）PR，必须关联到已被维护者批准的 issue，否则会被关闭。

所以流程建议是：先提 issue 说明想法 → 等维护者认可 → 再动手写 PR。

PR 规则：三条红线必须守住

必须关联 issue 并写close #编号：这是硬性要求，没有关联的 PR 无从审查；
区分 bug 与 feat：自由发起任何关联 bug-issue 的 PR；但 feat / refactoring 的 PR 必须关联已批准的 issue，否则关闭；
PR 正文要自己写：可以完全用 AI 发起 PR（项目对 AI 很友好），但正文描述必须由你自己写清楚做了什么；完全由 AI 生成的 PR 可能被关闭。

代码风格要求：简洁、解耦

仓库里 assets/whale-widget.js 和 lib/index.js 已经很大，维护者计划在慢慢拆分。在拆分落地之前，请按拆分友好的方式写代码：

新逻辑尽量自成一块、少依赖全局状态；
不要加深既有耦合，别增加后续拆解难度。

本地开发：两条命令跑起来

克隆仓库后，用link:.把当前目录以插件方式挂进 DSH，即可边改边看效果：

git clone https://gitcode.com/gh_mirrors/de/DeepSeek-Balance-Whale-Widget cd DeepSeek-Balance-Whale-Widget dsh plugin --profile web add link:.

两种改动的生效方式不同：

改了什么	生效方式
前端`assets/whale-widget.js`	硬刷新页面（Ctrl+F5）即可
宿主`lib/index.js`/ lib/accounting.mjs	必须重启`dsh web`

提交前建议自查一下 CI 会跑的内容（详见 CONTRIBUTING.md）：

图层审计（对应 tools/z-layer-audit.mjs）；
前端 / 宿主文件的语法检查；
「发布副本不得含开发机绝对路径」扫描 —— 你的新代码里不要写死本机路径。

发布流程速览：改版本号前必读

如果你是维护者或想理解发版逻辑，记住这几点（完整说明见 CONTRIBUTING.md）：

发布是手动触发的，push 不会发版：publish.yml只在 GitHub Actions 页面手动运行，支持dry_run演练（跑完全部门禁但不真发）；
版本号不自动递增：发出去的版本号就是 package.json 里的version字段，需要人手动改；
发布副本必须先 strip：发布前要跑一次_strip-dev-paths.mjs --apply删掉开发机候选路径，否则老用户会读到不存在的本机路径；
只允许在main上触发发布，选错分支 workflow 会硬失败。

动 assets/ 素材前：先看许可边界

PROVENANCE.md 明确了：代码是 MIT，但assets/下的图片 / 动图 / 音效不在 MIT 覆盖范围内，仅供运行本插件使用、不授予再许可。所以贡献素材时要格外谨慎，收到权利主张时项目会立即替换或移除。

总结：贡献四步走

📖 读 CONTRIBUTING.md 与 whale-widget-prompt.md，选对分支；
🐛 先提 issue，bug 放心提，feat 等批准；
🚀 写 PR 时关联 issue、写close #编号，正文自己写，代码保持简洁解耦；
🔁 前端改动硬刷新验证、宿主改动重启dsh web，提交前自查 CI 三项检查。

祝你的 PR 顺利合入，小鲸鱼娘会记得你 🐋

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

资讯详情

如何给DSH小鲸鱼挂件贡献代码：分支策略、Issue与PR规则的完整指南