dsh-ascii-whales

文字蓝鲸

下载安装包 · 安装 · 设置 · 本地预览 · 更新日志

感谢 ascii-sharks，最初的画面灵感来自这个项目。

从海面正上方看，五种鲸鱼用文字和字格组成身体，缓缓摆尾、转向、滑行。鱼身可以使用你自己的文字，也可以按明暗填入 ASCII 字符。鲸体在本地绘制，无需图片素材或外部服务。

安装

在 DSH Web 中可通过命令行安装：

dsh plugin --profile web add github:jryang1997/dsh-ascii-whales

也可以在桌面端或插件管理器中安装安装包：

1. 从 Releases 下载 local-dsh-ascii-ocean-*.tgz 安装包（或在插件管理器填入 github:jryang1997/dsh-ascii-whales）。
2. 在 DSH 插件管理器中安装该文件。
3. 打开 插件 → 文字蓝鲸，调整选项后点击 保存。

目前发布的安装包为 v0.14.0。0.10.0 之后的变化见更新日志。最上面一段是桌面窗口的录屏。下潜和拍尾仍用正式渲染器画出，完全沉在水下的几秒被缩短了。

能做什么

• 用中文、英文或 emoji 组成鲸鱼。留空时使用「探索未至之境」。
• 在蓝鲸、座头鲸、抹香鲸、长须鲸、弓头鲸之间选择，也可以让它们混合巡游。
• 用纯字符呈现轻淡轮廓，或加上彩色字格，显示背部、侧身与鳍尾的明暗。
• 调整数量、体长、速度、浓度和配色。改变体长不会改变游速与摆尾节奏。
• 保存设置后更新鲸群状态，切换模型时继续巡游。
• 本地 0.14.0 加入海面风纹与慢移云影，两个开关独立控制；鲸鱼从四边穿屏，提前避开另一侧的障碍。实现与来源见 海面风云研究。
• 「海上落雨」可独立开关，雨量从 0 到 1 调整。雨丝随海面风向缓慢偏转，落点带出细小水花和逐渐展开的涟漪。关雨后自然收尾，关闭海面风纹后逐渐回到直雨；雨水纹与鲸鱼尾流分别控制。
• 游动和滑行会沿航迹留下逐渐展开、消散的 ASCII 尾流，用力拍尾时仍有少量碎水。设置中的「游动尾流与水花」可统一开关，水纹会让开阅读区。
• 鲸会各自下潜再浮上来。吻端先入水，尾鳍抬起后拍一下。水下仍沿原航线游，只是看不见。浮出时鼻端先回来。不是整群一起，也没有单独开关。详见更新日志。
• 跟随深浅主题与系统偏好。减少动态效果时显示静态姿态，页面隐藏时暂停，装饰层不拦截鼠标操作。

动作

画面与阅读

「文字边缘效果」可选微光、柔和模糊或毛玻璃，默认毛玻璃。微光让文字附近的鲸鱼隐去；模糊和毛玻璃保留半透明鲸影，鲸身经过正文时仍然连贯。这个选项独立于「内容框毛玻璃」。滚动阅读时鲸群暂时隐去，停下后从原位恢复，避免柔边拖影。内容卡片、输入框和右侧边栏各自使用磨砂材质，右侧栏的鲸影更淡、模糊更重；深浅主题分别配色。

浅色主题 · 深色主题 ·

输入框可以保留模糊鲸影，也可以让鲸鱼绕开它。

选项 · 效果 · 默认 内容框毛玻璃 · 内容卡片、输入框和右侧栏显示模糊鲸影，文字区域保持清晰 · 开启 鱼群避让输入框 · 鲸鱼把输入框当作障碍，绕开后继续巡游 · 关闭

内容框毛玻璃与鱼群避让输入框互斥，开启其中一项会关闭另一项。文字保护不受这两个开关影响。

查看输入框避让效果

比较三档鲸鱼大小

这里的截图来自独立预览或仿真环境。真实 DSH 桌面窗口中的最终观感与验证边界见 SOURCE-NOTES.md。

设置

左侧栏的「插件」下方常驻「文字蓝鲸」入口，点击即可打开预览与设置。也可从 插件 → 文字蓝鲸 进入同一设置页。

拖动滑杆时，设置页的静态样例会更新；点击 保存 后，草稿才应用到对话背景。恢复默认值修改草稿，重新载入已保存值丢弃未保存的调整。

数值选项 · 范围 · 默认值 鲸鱼数量 · 1–8 · 3 游动速度 · 0.3–2 · 0.65 背景浓度 · 0.04–0.9 · 0.6 字符大小 · 4–16 · 11 鲸鱼大小 · 0.55–1.55 · 1 玻璃强度 · 0–1 · 0.55 雨量 · 0–1 · 0.45，落雨默认关闭 浏览器左侧留白 · 0–500 px · 280 px

样式选项 · 可选内容 鲸鱼种类 · 混合鲸群、蓝鲸、座头鲸、抹香鲸、长须鲸、弓头鲸 渲染样式 · 纯字符、彩色字格 填充内容 · 自定义文字、ASCII 字符 鲸鱼配色 · 深海蓝、晴空蓝、靛蓝、每条随机配色 其他开关 · 显示蓝鲸、跟随任务状态、减淡阅读区域

选择「每条随机配色」后，每头鲸鱼从八种色系中随机分得一种，鲸体内部仍保留明暗。同一片海里的颜色不会随绘制或保存设置重新抽取；改数量、文字、鲸类和大小也会接续原色。重新打开背景时会生成新的一组配色。

「跟随任务状态」默认开启。第一头对应当前会话，其余按身份绑定子代理、其他活跃会话与当前会话可见的后台任务。列表更新不会让已绑定的鲸鱼互换位置。

实际状态 · 鲸鱼表现 会话、子代理或后台任务运行中 · 更有力地巡游，划水更持续，显示 ··· 空闲或本轮停止 · 慢速滑行，子代理停止不会被当成任务成功 等待回答、审批或计划审阅 · 平滑回到水面，慢游并显示 ! 和任务名称，等待期间不再下潜 已观察到的后台任务完成 / 失败 · 显示 ✓ / × 与任务名称，继续播放六秒后消失

鲸鱼不足时，第一头汇总额外活跃任务的数量，并显示其中最紧急的提醒。关闭联动后恢复装饰游动。系统减少动态效果时不推进动作，状态变化仍会更新静态提示。此功能只读取 DSH 已发布的状态，不回答问题、不批准操作，也不读取后台输出。首次打开时已有的历史任务结果不会弹出提示。

鱼身文字支持中文、英文、emoji 和组合字形，空白会被忽略。输入上限为 40 个 UTF-16 代码单元，部分 emoji 会占用多个单位。切换到 ASCII 不会改写已保存的自定义文字。

桌面版自动跟随左侧栏宽度；在普通浏览器中，可用 浏览器左侧留白 调整鲸群的可见区域。

查看设置页

本地预览

下载或克隆仓库后，用浏览器打开 whale-preview.html。页面使用插件的正式渲染器，不需要启动服务器。

预览包含四种渲染组合和实时鲸群，可以切换鲸类、鱼身文字、大小、速度、玻璃与深浅主题。页面底部的模拟输入框用于比较毛玻璃和避让效果。

开发

src/             实现源码
tests/           测试与 helpers/ 适配器
scripts/         构建、验证和审查工具
preview/         独立预览入口与生成页面
docs/research/   研究与设计记录
docs/images/     截图和动图

根目录保留插件公开入口 index.js、DSH 客户端产物 client.js、安装配置及项目说明。历史截图仍在 docs/archive/。

构建、检查与打包

使用 .node-version 指定的 Node，以及 package.json 中固定的 pnpm 版本。在项目根目录运行：

pnpm install --frozen-lockfile
pnpm verify

修改浏览器源码后，先用 pnpm build 和 pnpm preview 更新两个生成产物，再运行 pnpm verify。验证只检查、不重建，过期产物会直接失败。测试只递归发现 tests/ 下的 *.test.js，排除隐藏目录与 node_modules/；不会扫描仓库中的临时备份、参考项目或 worktree 副本。GitHub Actions 在 Windows 与 Linux 执行同一验证入口。

pnpm check 仅查语法，pnpm test 仅跑测试。pnpm --silent review:snapshot --base 输出包含新增文件的 JSON 审查清单；pnpm --silent agent:probe 探测当前命令进程能否读取入口文件。派单前的原生工具读取预检、审查范围与浏览器证据要求见 工程说明。

打包使用 pnpm --config.ignore-scripts=true pack。

pnpm build 运行 build.mjs，从 browser-entry.js 生成 client.js；pnpm preview 运行 preview.mjs，从 preview-client.js 生成 独立预览页。两个入口共用 browser-build.mjs 和开发依赖 esbuild，自动解析依赖并隔离文件作用域；正式插件运行不依赖 esbuild。两种产物都支持 --check 检查是否与源码一致。包名为 @local/dsh-ascii-ocean，Host 行 id 为 ascii-whale-background。

文件 · 职责 species.js · 五种鲸类的体型与动作参数 model.js · 表面、投影、字格覆盖与配置指纹 motion.js · 巡游、转向、滑行与输入框避让 rig.js · 身体转向与上下尾拍 shading.js · 背部隆起与水深字色 surface.js · 字符选择、色表与字格绘制 glass.js · 阅读区与输入框的面板几何及材质 engine.js · Canvas 绘制与原地更新 reading-layout.js · 真实对话与演示卡片共用的玻璃、遮罩和避让规则 activity.js · DSH 状态读取、任务身份绑定、后台订阅与状态徽记 rain.js · 随风雨丝、雨量过渡与落点水纹 simulation.js · 鲸群状态接续、尺寸变化以及动作与海面效果的推进顺序 config-editor.js · 草稿互斥、校验、差量保存和版本冲突处理 browser-build.mjs · 两种浏览器产物的依赖组装与一致性检查 settings.js · DSH 原生设置页

文档与参考

• 更新日志：版本历史与升级变化。
• 实现与验证记录：实现细节、问题根因与验证边界。
• ASCII 渲染研究：字格与字符密度的机制核对。
• 鲸类造型参考：五种鲸类的俯视照片依据。
• 历史截图：早期版本的视觉记录。

真实参考照片、本地验证证据与第三方参考仓库不随项目发布，目录规则见 .gitignore。