@hytime/dsh-companion
DSH Companion 鲸鱼 Skill/CLI 前端插件（dual-face Cordis 插件），发布到 npm 公共 registry。
默认在 DSH 右下角显示鲸鱼（二次元娘）悬浮按钮，用户继续使用 DSH 当前对话框输入；DSH Skill 调用 hyc CLI，本插件接收 Host 投影的 CLI 状态并把鲸鱼回复反馈到当前 DSH 对话。
数据流
DSH 当前对话框 ──用户输入──▶ Skill 触发
│
▼
DSH Host 调用 Go CLI（hyc）
（凭据 / 超时 / 取消 / 结构化结果）
│
▼
结构化结果（text / emotion / status）
│
┌───────────────────┴───────────────────┐
▼ ▼
当前 DSH 对话展示最终文本 鲸鱼悬浮窗反馈状态
（唯一输出位置） （idle/connecting/thinking/
replying/success/error/cancelled
+ 表情帧切换）
本插件不负责 Token、CLI 执行和最终对话消息持久化；不创建第二个聊天输入框，不维护独立 SSE 会话。
安装前置条件（必须按序满足）
安装/激活本插件前，必须先满足：
- hyc CLI 可用：
command -v hyc 命中（系统入口 ~/.local/bin/hyc）。
- DSH 技能已安装：
$DSH_HOME/skills/ 下存在 hy-companion 与 hy-companion-*（先安装 CLI，再执行技能安装器写入 $DSH_HOME/skills）。
任一缺失时按顺序先补齐（先 CLI、再技能、再插件），不得跳步。完整顺序与验证命令见根 README「安装前置依赖」一节。
安装
发布后
本插件发布到 npm 公共 registry，直接添加：
dsh plugin add @hytime/dsh-companion
本地开发（tarball）
本地开发使用 tarball 安装，避免 link: 目录安装带来的双实例 / 产物目录变化 / 可复现性差问题：
# 1) 构建插件产物（生成 lib/ 与鲸鱼帧资源）
pnpm --filter @hytime/dsh-companion run build
# 或监听模式：
pnpm --filter @hytime/dsh-companion run watch
# 2) 打成 tarball
pnpm --filter @hytime/dsh-companion run pack
# 产物：packages/dsh-companion/hytime-dsh-companion-0.1.0.tgz
# 3) 装进 DSH（把 *.tgz 替换为实际文件名）
dsh plugin add ./packages/dsh-companion/hytime-dsh-companion-0.1.0.tgz
# 4) 重启 DSH 使插件生效
发布包名为 @hytime/dsh-companion（scope 已定型，无需再作替换）。仅当整体更换 scope 时，才运行根目录的 node scripts/rename-package.mjs <新scope> 全局替换。
开发命令
pnpm --filter @hytime/dsh-companion run typecheck
pnpm --filter @hytime/dsh-companion run lint
pnpm --filter @hytime/dsh-companion run test
pnpm --filter @hytime/dsh-companion run build # library build → lib/
pnpm --filter @hytime/dsh-companion run pack
公开 API
WhaleFloatingWidget（props：status、emotion?、lastError?、companionName?、
buddyTitle?、buddyMessage?、onReply?、onClose?、frameSrc?）createSkillStatusAdapter(source, onChange?) 与 SkillStatusSource 接口- 纯 JSON 类型与函数：
TravelNoteSkillInput、TravelNoteCLIResult、SkillStatus、
CompanionEmotion、CharacterActivity、parseTravelNoteCLIResult、
normalizeSkillStatus、normalizeCompanionEmotion、skillStatusToActivity、
EMOTION_TO_FRAME、resolveWhaleFrame 等
- 样式：由组件内联注入（CSS Modules，构建时编译进
lib/client.js）
不导出 mock、CLI 执行器或 DSH live 对象。
表情与 Phaser 对齐
CompanionEmotion（idle/thinking/talking/happy/shy/surprised）、CharacterActivity
（idle/listening/thinking/speaking）与既有 Companion 的 Phaser 角色状态机
（COMPANION_EMOTIONS、CHARACTER_EMOTION_MAP、EXPRESSION_TO_FRAME）逐项一致；
鲸鱼娘形象帧位于 public/deepseek-girl-phaser/（atlas + frames/*.png），
build 时由 scripts/copy-assets.mjs 拷贝到 lib/deepseek-girl-phaser/（host 半
defaultAssetRoot() 据此提供静态路由）；resolveWhaleFrame(status, emotion) 负责选择当前表情帧。
运行环境
- React 19（peer dependency），TypeScript 5.6，Vite 6，Vitest 3 + Testing Library。
- 仅浏览器环境；不依赖 Next.js、SSR 或 App Router。
