coloured-favicon

Readme

# coloured-favicon 🐳🌈

> 为 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai) 网页提供**彩色渐变持续流动的小鲸鱼 favicon**,并把页面内的鲸鱼图标、"deepseek" 文字、hero 标题与「预览版」徽章一并彩色化的 Cordis 客户端插件。

看到 DeepSeek 在官网 WebChat、OpenPlatform、Harness 三处用了不同颜色的小鲸鱼 favicon 后,萌生了「给 Harness 自己做一个彩色小鲸鱼」的想法。本插件把小鲸鱼轮廓 + 流动彩虹渐变渲染到浏览器标签页的 favicon 上。

本仓库提供**两种安装形态**:

| 形态 | 分支 | 分发方式 | 适用 |
| --- | --- | --- | --- |
| 动态插件 | `main` | 会话内 `cordis_define` + `cordis_run`(分享 `src/index.js`) | 只给自己 / 单会话用,带运行卡片控制面板 |
| 静态 bundle | `bundle`(当前分支) | `npx @deepseek-ai/dsh plugin ... add`,整个部署生效 | 分发给其他用户、一次装全部署 |

> 你正在看的是 `bundle` 分支:主产物是 dual-face npm 包;`src/index.js`(动态形态)与
> `src/client.js`(bundle 客户端)仍共用同一份小鲸鱼图形与参数。

## ✨ 特性

- 🌈 **彩色渐变流动**:7 段彩虹色相循环 + 渐变方向旋转,颜色在小鲸鱼身上持续「流动」。
- 🐳 **页面内彩色化**:导航栏与会话页的鲸鱼图标(`FishLogo`)、"deepseek" 文字(`BrandWordmark`)、hero 标题「探索未至之境」以及「预览版」徽章同样流动彩虹渐变。
- 🎨 **可配置**(动态形态):运行卡片内可在「渐变变色 / 整体变色」间切换页面内颜色的呈现方式。
- 🖥️ **作用于主页**:直接替换整个 DSH Web 页面的 `favicon`,无需刷新页面。
- 🎛️ **运行卡片控制**(动态形态):在 `cordis_run` 卡片内提供实时彩虹圆点、「暂停 / 恢复」按钮与变色模式配置。
- 🧹 **干净卸载**:停用 / 更新插件时自动恢复原始 favicon,不留残留。
- 🧱 **零依赖**:纯客户端 JS,无构建步骤、无运行时依赖。

## 📁 目录结构

```
coloured-favicon/
├── src/
│   ├── index.js          # 动态形态:可直接部署的客户端函数体(code.client)
│   ├── client.js         # bundle 客户端源码(占位符 __WHALE_PATH__)
│   └── node.js           # bundle node 半区源码(no-op 宿主挂载点)
├── lib/                  # 构建产物(已提交):lib/index.js + lib/client.js
├── scripts/
│   ├── check.mjs         # 校验动态形态 src/index.js 语法
│   └── build.mjs         # 构建 bundle:src/* → lib/* 并做语法校验
├── cordis.patch.yml      # bundle patch 层(insert 一行客户端插件条目)
├── docs/
│   ├── 快速开始.md        # 动态形态如何部署到 DSH
│   ├── 打包分发.md        # bundle 形态如何打包并分发给其他用户
│   ├── 架构设计.md        # 工作原理与设计取舍
│   └── 开发指南.md        # 本地开发、校验与版本迭代
├── README.md
├── CONTRIBUTING.md       # 贡献指南
├── CHANGELOG.md          # 变更日志
├── NOTICE.md             # 第三方素材声明(小鲸鱼图形版权)
├── LICENSE               # MIT
└── package.json
```

## 🚀 快速开始(动态形态)

> 完整步骤见 [`docs/快速开始.md`](docs/快速开始.md)。

1. 在 DSH 会话中加载 `cordis-plugin-development` 技能。
2. 调用 `cordis_define`,把 `src/index.js` 的内容作为 `code.client` 传入(纯客户端,无 Host 半区)。
3. 调用 `cordis_run` 激活返回的 `pluginId` / `packageId`。
4. 在运行卡片上批准授权,浏览器标签页的小鲸鱼 favicon 随即开始彩色流动。

## 📦 打包分发(bundle 形态)

把插件装进整个 DSH 部署,其他用户无需在会话里 define/run。DSH 没有独立可执行文件,以下
命令统一以 `npx @deepseek-ai/dsh` 前缀运行(全局安装 `npm i -g @deepseek-ai/dsh` 后
可直接敲 `dsh`):

```bash
npx @deepseek-ai/dsh plugin --profile web add ./coloured-favicon-2.0.0.tgz   # 装包;自动加入 profile bundles
npx @deepseek-ai/dsh web                                                     # 直接启动即可(勿再加 --patch,会重复 insert 报错)
```

> `npx @deepseek-ai/dsh plugin add` 检测到 `dsh.bundle` 清单会自动把包加入
> `dsh.profile.bundles`,启动时自动插入条目。`npx @deepseek-ai/dsh web --patch ./cordis.patch.yml`
> 只在包未进 bundles 时使用(叠加两次会报 `duplicate loader entry id: coloured-favicon`)。

完整说明(打包、三种安装方式、卸载、调参)见 [`docs/打包分发.md`](docs/打包分发.md)。

## ⚙️ 可调参数

`src/index.js` 顶部集中了三个参数,两种形态共用;动态形态改完重新部署, bundle 形态改完
`npm run build` 再重新打包:

| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| `SPEED` | `1.6` | 每帧色相前进的度数,越大流动越快 |
| `STOPS` | `7` | 彩虹渐变的分段数 |
| `INTERVAL_MS` | `100` | favicon 刷新间隔(毫秒),越小越流畅 |

## 🧠 工作原理

小鲸鱼轮廓用官方 SVG path 绘制;每帧按相位 `phase` 生成一段
`hsl` 彩虹线性渐变(色相循环 + 渐变方向旋转),拼成 SVG 后以
`data:image/svg+xml` 写入 `<link rel="icon">` 的 `href`。定时器在动态形态下使用
DSH 的 `timer` 服务(`ctx.interval`),bundle 形态下直接使用浏览器原生 `setInterval`;
所有副作用都挂在插件 Fiber 上,卸载时自动清理。
页面内的鲸鱼与 `deepseek` 文字则通过注入共享 `linearGradient` + CSS `fill` 覆盖实现,
与 favicon 共用同一相位。详见 [`docs/架构设计.md`](docs/架构设计.md)。

## 🤝 贡献

欢迎提交 Issue 与 Pull Request。请先阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md)。

## ⚖️ 版权与许可

- 插件代码、文档与脚本:遵循 [MIT License](LICENSE)。
- 小鲸鱼图形:版权归 **DeepSeek** 所有,本项目仅用于个人学习与界面美化,
  不构成官方授权。详见 [`NOTICE.md`](NOTICE.md)。