# 参与贡献

这个仓库是 DeepSeek Harness（DSH）的摸鱼歌词插件。它只在 Windows 上真正工作，因为依赖系统媒体传输控件（SMTC）。欢迎提交缺陷报告、改进建议和代码，但请先读完下面几节，避免白做工。

## 环境要求

在本地跑起来需要同时满足：

- Windows 10 或 Windows 11
- DeepSeek Harness，Web 端与宿主进程同一台机器
- 桌面版网易云音乐，并在设置中打开系统媒体控件开关
- Node.js 18 或更高版本，仅用于语法检查

以上是当前实现的要求。做跨平台或换音乐平台的适配不受此限，但请在 PR 里写清实测的系统版本、客户端版本与取数方式。没有实测过的平台适配不会合并，因为这类改动一旦出错，表现是静默不显示，没有报错可查。

## 本地开发循环

把当前目录以本地 bundle 方式装进 DSH 的 profile：

```
dsh plugin --profile web add "<仓库路径>" --save-exact
```

改动后按改动位置区分生效方式：

- 只改 client.js：刷新浏览器页面即可
- 改 index.js、smtc-worker.ps1、cordis.patch.yml、package.json：重启 dsh web

调试信息在两处：宿主进程的终端输出会打印 worker 退出与重启原因，浏览器控制台的 netease-lyrics 前缀告警会打印 worker 不可用与平台不支持。

## 提交前自查

以下命令与验证由贡献者自行执行，维护者不会代跑。请把实际结果写进 PR，不要只写通过。

```
npm run check
npm test
```

`check` 对两个入口文件做语法解析，`test` 覆盖客户端挂载逻辑：slots 服务缺失、服务延迟就绪、注册过程抛错这三种情况都不允许向外抛异常。原因是客户端插件抛错会让宿主拒绝启动整个 web 端，代价远大于歌词不显示。两项都不覆盖运行时行为，仍需在 DSH 里人工确认三条路径：

1. 放歌并在 DSH 中发起对话时，歌词出现在状态行右侧，且字体、字号、颜色与状态行一致
2. AI 空闲、状态行消失时，歌词同时消失，不残留
3. 暂停再继续播放，歌词行不跳跃、不整句回退

## 代码约定

- Host 端只负责数据搬运与缓存，不参与任何 DOM 操作；Client 端只负责取值与渲染，不发起除本插件路由以外的请求
- 颜色、字体、字号、行高一律从状态行现场读取计算样式，不在代码里写死。写死会在宿主换主题时立刻穿帮
- 新增面向用户的文案要同时补 locale/en.json 与 locale/zh.json，只加一种语言会造成另一种语言下空白
- smtc-worker.ps1 必须保持纯 ASCII。Windows PowerShell 5.1 会把无 BOM 的文件按 ANSI 读取，一旦写入中文就会解析失败
- 涉及歌词文本的渲染只作为文本节点输出，不拼接 HTML，避免第三方接口返回内容被当作标记执行
- 路由改动必须保留回环地址校验与 Origin 校验，这是该插件唯一的安全边界
- 不要在 apply 里从 ctx 上取配置或探测未声明属性。宿主内核启动早期对 cordis 上下文上未注册属性的访问会直接抛异常，异常被 fiber 吞掉后插件静默进入 failed，宿主随即拒绝启动整个 web 端。配置一律从 apply 的第二个参数取，日志用 console 而不是 ctx.logger，因为错误处理路径本身也可能因同样的访问而抛异常
- 客户端插件的 apply 不允许向外抛异常。这是硬约束，`npm test` 里有一组用例专门守着它，改动挂载逻辑前先看那组测试

## 提交规范

采用 Conventional Commits：

```
<type>(<scope>): <subject>
```

- type 取 feat、fix、docs、chore、refactor、perf
- scope 取 host、client、worker、i18n、docs，可省略
- subject 用英文祈使句，小写开头，不加句号，不超过 72 个字符
- 正文说明为什么改、影响哪些行为，不复述代码
- 一个提交只做一件事。格式化、无关重构不要混进功能提交

分支命名与 type 对应，例如 feat/hover-tooltip、fix/anchor-config、docs/contributing。

## 缺陷报告

提交前先搜索已有 issue，避免重复。报告中请包含：

- DSH 版本与安装方式
- 网易云音乐版本，以及系统媒体控件是否已打开
- 复现步骤，从打开哪首歌开始写
- 期望结果与实际结果
- 浏览器控制台里 netease-lyrics 相关告警原文

缺少系统媒体控件开关状态时，问题通常无法定位，这一项请务必写明。

还没定方案的适配想法，比如换系统、换音乐平台、换歌词源，先到 Discussions 聊。这类事通常要先确认取数方式和歌词源能不能对上，开成 issue 容易挂在那里没人动。

## 合并请求

- 从 main 建分支，不要直接提交到 main
- 一个 PR 只解决一个问题，标题与提交规范一致
- 按仓库的 PR 模板填写，关联 issue 用 Closes #编号
- 改动涉及界面时附截图，涉及行为时附复现路径

维护者合并前会确认五件事：能复现原问题、改动范围限于该问题、自查结果真实、没有引入新的外部依赖、没有把本机路径或账号信息带进代码。

## 不要做的事

- 不要在 issue、PR、提交或代码里粘贴 Cookie、MUSIC_U、账号信息或抓包得到的私人数据
- 不要为了让插件跑通去修改宿主安装目录里的文件，插件必须只依赖公开扩展点
- 不要引入需要登录或需要自建服务端的歌词来源
- 不要把本机绝对路径写进代码或文档

## 许可

本仓库采用 MIT 许可。提交合并请求即表示同意你的贡献以同一许可分发。