jarvislee90s-dot/dsh-foxbell-pet

dsh-foxbell-pet

中文 · English

DeepSeek Harness（DSH）Web 网页右下角可拖拽的多宠物桌宠系统：多项目状态监控 + 语音提醒 + 外部宠物体系（商店 / 四来源导入 / 热切换 / 完整性守卫）+ 🦊显隐开关。内置一只 Foxbell 小狐狸随包自带：一键安装即用，其余宠物随时导入、一键热切换。

v2.3.0 适配 dsh 0.2.0-rc.2 桌面端运行时（设置 API 迁移 entry-config；向下兼容 0.1.2-rc.1，见下方兼容表）。 状态卡片色彩语义自 v2.0.0 起为 MAM 口径（红=待审批 / 黄=运行中 / 绿=完成未读 / 深红+⚠=错误断联），与 v1.x（绿运行/黄待批准/红报错/蓝完成）不同，详见 CHANGELOG。

预览

热切换——内置宠物与导入宠物同场管理，点击即换、即时生效：

右键菜单——开关 / 大小 / 五场景动作绑定（实时预览）/ 切换宠物 / 隐藏 / 关于：

四来源导入——本地文件夹 / zip / Codex 宠物目录 / Petdex 在线仓库：

功能

• 多项目状态监控 —— 桌宠头顶为每个"活跃项目"显示一张状态卡片（MAM 色彩口径）：
  • 🔴 approval 等待审批（红）
  • 🟡 running 正在运行（黄）
  • 🟢 done 已完成未读（绿，点击即确认消失）
  • 🟥 error 本轮报错 / 断联（深红 + ⚠ 标识，与待审批红明确区分）
• 点卡片切换会话 —— 点击卡片直接切到该项目会话（sessions.open）并标记已读；错误/完成卡片点进去即消失，再次出现会重新亮起。
• 语音提醒 —— 完成播 done 组、待审批播 approval 组（10s 限流）、报错播 error 组；字幕=语音文件名，与音频时长对齐。
• 语音交互 —— 单击形象：只挥手（不出声）；双击形象：说话 + 「双击动作」；点卡片：只切换（不出声）。
• 状态驱动动画（Codex V2 图集 11 行全用；外部宠物 v1 9 行图集运行时自适应）—— 动画优先级：拖拽 > 瞬时动作 > 任务态 > 环视 > 待机；拖动方向（左跑/右跑/上拎跳）、任务姿态（待审批→等待、运行→工作）、空闲 6s 环视 16 向扫视。
• 拖拽物理手感 —— 松手重力坠落（1400 px/s²）、水平抛掷惯性（150ms 采样窗）、落地压扁回弹 + 补跳（可关）；视口为工作区，位置记忆与边界钳制。
• 右键菜单 —— 🔊出声 / 💬语音字幕 / 🧲物理坠落 开关（无语音/无字幕宠物自动禁用带提示），📏大小三档，🖱️双击 / 🔴红灯 / 🟡黄灯 / 🟥深红灯 / 🟢绿灯 五场景动作绑定（子页实时预览），🔁切换宠物（当前项打勾，点击即热切换），🦊隐藏桌宠，ℹ️关于。
• 外部宠物体系（MAM v0.3.0 移植）——
  • 磁盘商店 ~/.dsh/foxbell-pet/pets/<id>/；清单 v2（原子写 + .bak 备份）；
  • 四来源导入：本地文件夹 / zip 包（宿主安全解压：总量 ≤100MB、文件数 ≤200、路径防穿越）/ Codex 宠物目录 ~/.codex/pets/ / Petdex 在线仓库（petdex.dev，列表与下载均由宿主代理：域名 allowlist、体积上限、8s 超时）；
  • 统一导入向导：宠物 id 实时校验（字符集/长度/保留字 foxbell/查重/Windows 保留设备名，前后端双重校验）、显示名/描述、字幕开关、语音分组编辑（并行时长探测；1s<时长<20s 且 ≤10MB；四组齐全判定「有语音」）；
  • 管理对话框：改名（id 同步目录与清单）、编辑显示名/描述、按组增删语音、字幕开关、安全删除（二次确认后移入 ~/.dsh/foxbell-pet/.trash/，不物理删除）、查看目录路径；编辑激活中宠物自动闪切保护；
  • 热切换：卡片式列表（内置 foxbell + 外部宠物）→ 激活即时生效（精灵/语音/清单热替换，无需刷新页面）；
  • 激活守卫：激活与每次切换校验完整性（图集缺失/被改动、语音缺失/变动/多余、清单缺失），问题随状态快照下发，弹修复对话（更新清单 / 换回 foxbell / 忽略 / 隐藏宠物）；宠物本体运行中不弹；
  • 无语音宠物：完成只播动画不出声、音效开关禁用带提示；无字幕宠物：不显示气泡。
• 三档缩放（0.75 / 1 / 1.25）—— 作用于精灵/卡片/菜单整体（设置卡与右键菜单同款档位）。
• 设置卡（单卡双分区） —— 「配置」区（声音/字幕/物理/五场景动作/大小）+「宠物管理」区（当前宠物、切换/导入/管理按钮、Petdex 入口）；与右键菜单读写同一份配置（localStorage + settings scope 双后端，Host 持久化到 ~/.dsh/settings.yaml）。
• 🦊 显隐开关 —— 侧栏底部（语义与 v1 相同），状态存 localStorage。
• 错误码体系 —— 对齐 MAM PetError 码表（宿主 50 码 + 客户端本地 8 码），路由错误统一 {code, params, detail} JSON，客户端按插件内部 zh/en 字典映射文案、内联呈现于对话框（浏览器语言自动选择，不依赖 harness locale）。

效率看板（v2.1.0 移植）

v1.4.0 效率看板一期整体移植到 v2 架构：宿主聚合、随 /state 快照下发，零新增常驻 UI（迷你条仅悬停期间存在）；用量一律纯 token 口径，不折算金额，按五口径呈现——请求输入 / 缓存命中 / 命中率 / 产出 / 你的输入(估)。v2.4.0 起「含子代理」为真实口径：子代理会话与已收尾会话经 sessionQuery 全语料并入除迷你条「本会话」行（最近主会话）外的全部 token 统计（活会话内存折叠、冷会话一次性重放缓存）。

1. 时长档位表盘（节奏姿态引擎）—— 宠物姿态随事件时间轴自动变档：高强度 / 活跃 / 长任务（turn 开着静默 ≥3 分钟，防挂机干等）/ 空闲 / 摸鱼四阶（turn 关着静默 ≥15 分钟起小憩→躺平→咸鱼→咸鱼干渐进）。换动画变体、不变速，档位跃迁只播一次短动画，新事件立即复位。
2. 五口径迷你条 —— 悬停宠物 ≈0.5s 浮现：节奏表盘（当前档位读数）+「今日 × · 本会话 ×」五口径用量 +「N 等审批 / N 运行 / N 完成」状态行；唯一可点元素为尾部「详情 »」钻取按钮（容器仍不拦截点击），移开即消失（右键「🏷 今日用量」可手动唤出，点外部 / ESC 关）。
3. 警报举牌 + 看板音效链 —— 日阈值 dayLimitTokens 达 80% / 100% 各举牌一次「今日已消耗 X」，里程碑过 milestoneUnit 整数关口气泡一句话；警报音效自 v2.2.0 起走 MAM 四组机制 + 默认音效：宠物语音四组配齐时播 general 组，否则播内置合成提示音（三轮换）；TTS 不参与看板警报（ttsEnabled 仅用于台词朗读）。
4. 小黑板 + 📖 限时入口 —— 任务完成后宠物旁限时出现「📖 总结」入口（默认 15s，可配 10/15/20s）→ 点开浮现总结浮窗（会话 / turn / 五口径 token 三分账 / 工具 Top3 / 最长单 turn / 报错数），boardTtlSec 自动消失，✕ / 点外部 / ESC 均可关；右键「📊 查看最近总结」随时唤回。
5. 关宠 farewell —— 隐藏桌宠时自动分发一次「今日收工」黑板，收工有交代。

两个小增强：标题闪烁——审批等待 ≥N 分钟（approvalFlickerMin 可配）且页面不可见时，标签页标题轮换「🦊 审批等待中…」，批准或回到页面即恢复；年龄标注——状态卡动态行尾灰色「×s/×m」，分清「刚发生」还是「已挂 5 分钟」。另有右键「🗂 会话一览」列出全部会话（状态色点 + 点击直达）。

以上共 12 项新配置（paceEnabled / usageEnabled / summaryEnabled / ttsEnabled / dayLimitTokens / milestoneUnit / paceIntenseEvents / paceLongrunMin / paceLoafStartMin / approvalFlickerMin / summaryEntrySec / boardTtlSec），设置卡草稿 + 统一保存（编辑先入草稿，保存/放弃统一生效，保存自动收起）。

效率看板交互速查（一目标一行为）

用量看板（v2.2.0，三级披露）

一个数据核、三级呈现，越点越深：L1 迷你条 → L2 小黑板 → L3 主列大看板（另有右键「📈 用量看板」直达）。宿主一次聚合（会话事件 usage 按日/小时/路由/工具折叠），随 /state 快照与按需路由下发；纯 token 口径，无任何金额字段；性能上按「末事件指纹」增量缓存 + /state 短路 + 页面不可见降频，空闲开销近乎为零。

• L2 小黑板加料：五口径明细之后追加 7 日 sparkline、模型 Top3 与「查看完整看板 →」入口行；黑板锚定宠物侧（左优先、越界自动翻右），出现即顶替迷你条。
• L3 大看板（复刻 Codex++ 排版，占主列）：选项卡【近 5 小时 | 近 7 天 | 近 30 天 | 自定义 ≤31 天】+「复制文本」「导出图片」；区间 hero 大数字 + 本周/上周命中率对比；五口径网格；蓝→紫渐变趋势图（hover tooltip / 数据点 / 峰值 / 轴标签）；模型分布通栏进度条（≤6 行）；2×2 工具格 + Top5 工具；底部口径说明。
• 模型/供应商分布（F05 清偿）：按 (turn, step) 结算样本的 provider/model 路由记账（同槽替换冲回、跨日不污染）；聚合结果已与会话官方 tokenUsage totals 四口径逐字节对账。
• 导出分享：720×1560 竖版卡片（对齐 Codex++ 排版）——标题/日期范围、累计 Token hero（完整千分位）、五口径指标行、趋势卡（峰值+渐变折线）、按 Model 分布（模型全名+进度条）、工具调用 2×2；最下方为聊天式评语气泡 + 宠物立绘（姿态随机或自选，气泡不遮挡宠物）。评语来自规则池（zh/en 优先级匹配），或经头部「按自定义评语导出」内联填写模板（{range} {tokens} {hitPct} {models}）；「复制文本」为同数据纯文本摘要。
• 看板音效：警报（日阈值 / 里程碑）四组配齐播 general 组语音，否则播内置合成提示音（/sounds/ 路由）。
• 设置卡新增：「侧栏看板入口」（默认关，开启后侧栏出现看板图标）、「导出姿态」；自定义评语在看板头部「按自定义评语导出」内联填写（不再占用设置项）。注：rc.2 真机上「侧栏看板入口」图标可能不投影（上游子槽生命周期待排查）；右键菜单与黑板链为实测可用入口。

环境要求（兼容表）

依赖结构（v2.3 根因修复）：@deepseek-ai/dsh-settings 不在 dependencies 中—— settings 服务一律由宿主运行时提供。插件自带副本会以 hoisted 依赖遮蔽运行时内置的 settings 插件行，导致 0.2 桌面端兼容性禁用与启动崩溃（详见 CHANGELOG [2.3.0] C2）。

内置素材随包自带，无需额外下载；外部宠物素材由用户导入。

安装（一键）

dsh plugin --profile web add github:jarvislee90s-dot/dsh-foxbell-pet#release

#release 是稳定版通道（仓库 release 分支，只在版本发布时更新）。想尝鲜开发中的 最新改动，可改用 github:jarvislee90s-dot/dsh-foxbell-pet#main（跟随 main，不保证稳定）。

桌面端/网页端粘贴 GitHub 仓库首页链接安装也可以：仓库的 GitHub 默认分支已设为 release，不带分支后缀的地址（如 https://github.com/jarvislee90s-dot/dsh-foxbell-pet） 解析到的就是稳定版通道。

插件的 lib/ 构建产物随仓库提交，安装即用、无需本地构建；只有从源码开发时才需要 npm run build（见「开发」节）。

然后重启 dsh web 并硬刷新浏览器（Cmd/Ctrl+Shift+R）。右下角即出现桌宠，设置旁有 🦊 开关，设置页出现「foxbell-pet」配置卡。

桌宠运行时从插件包自带目录 assets/ 读取内置精灵图/语音；外部宠物商店在 ~/.dsh/foxbell-pet/（插件专属目录，首次启动自动创建）。

本地源码安装（开发/尝鲜最新源码）

想在本地改代码并立即在 dsh 里测试时，把源码目录以 link 方式装进 profile——安装的是“活”的源码目录，改完重新构建、刷新页面即生效：

# 1) 获取源码并构建（需要 Node ≥ 20 与 pnpm）
git clone https://github.com/jarvislee90s-dot/dsh-foxbell-pet.git
cd dsh-foxbell-pet && pnpm install
npm run build            # 产出 lib/（dsh 实际加载 lib/，不是 src/）

# 2) 以 link 方式装进 web profile（自动写入启动清单；在插件目录执行）
dsh plugin --profile web add .

# 3) 启动/重启 dsh web，打开网页即见（重装/更新后建议硬刷新 Cmd/Ctrl+Shift+R）

日常开发热更：

npm run build:watch      # 常驻监视 src/，改动即重建 lib/

• 纯客户端改动（src/client/**）：刷新网页即生效；
• 宿主侧改动（src/host/**）：需重启 dsh web；
• 卸载（不影响源码目录）：dsh plugin --profile web remove dsh-foxbell-pet。

本地源码版 harness（deepseek-harness 仓库）跑 pnpm dsh web 同样适用以上 link 安装； 若 profiles 里曾装过旧版，add . 会覆盖为本地 link。

启动 / 重启 dsh web（本地源码版）

本地源码版 harness 没有图形启停入口，dsh web 通常跑在后台终端里。两种重启方式：

# 方式一：自带脚本（在 deepseek-harness 仓库根目录，自动停旧进程→重启→打印新链接）
./dsh-web-restart.sh

# 方式二：手动（杀掉占用 3080 的进程后再起）
lsof -nP -iTCP:3080 -sTCP:LISTEN -t | xargs kill    # 停（若有）
cd <deepseek-harness 目录> && pnpm dsh web          # 前台起（Ctrl+C 停）

启动成功的标志是终端打出 dsh web: http://127.0.0.1:3080/?token=…；日志在 /tmp/dsh-web.log。 重启后记得硬刷新浏览器（Cmd/Ctrl+Shift+R）。

使用

状态灯（MAM 口径）：红 待审批 · 黄 运行中 · 绿 完成未读 · 深红+⚠ 报错/断联。

语音分组

voice/ 按状态分 4 个固定分组（内置素材在包内 assets/voice/，外部宠物在 ~/.dsh/foxbell-pet/pets/<id>/voice/），文件名即字幕文字：

运行（黄）不播语音。空组静默跳过；四组齐全才判定宠物「有语音」能力。

自定义（外部宠物）

• 导入：设置卡 →「导入宠物」→ 四来源任选（文件夹 / zip / codex / petdex 链接或搜索）→ 向导配置（id/显示名/描述/字幕/语音分组）→ 执行导入 → 立即激活。
• 素材规格：Codex V2 图集 spritesheet.webp（8 列；11 行 1536×2288 = v2，9 行 1536×1872 = v1，运行时自适应），见 docs/SPRITESHEET-CONTRACT.md；语音 .m4a/.mp3/.wav/.ogg/.opus/.flac/.aac，单条 1–20s 且 ≤10MB。
• 换形象不换语音：管理对话框按组增删语音后「保存修改」（清单自动备份更新）。

开发

npm install
npm run build      # esbuild：src/host → lib/index.js（ESM），src/client → lib/client.js（单文件 iife）
npm run validate   # 静态校验（既有检查 + 产物纯度 / 声明一致 / 路由前缀 / 版本 / 错误码表 / 内置清单）
npm run typecheck  # tsc --noEmit（客户端 TSX）
npm test           # vitest（纯逻辑 + 真实临时目录管线 + mock fetch）

dsh-foxbell-pet/
├── assets/         内置 foxbell 素材（精灵图 + 31 条语音 + v2 清单 pet.json）
├── lib/            发布产物（main 与 ./client 入口；esbuild 生成，随包提交）
├── src/host/       宿主半源码（纯 JS：状态聚合/商店/导入/守卫/路由族）
├── src/client/     客户端半源码（TSX：本体/菜单/设置卡/对话框/错误码字典）
├── test/           vitest 套件（含真实临时目录与 mock fetch）
├── scripts/        构建 + 校验 + 发版 + 内置清单生成
├── docs/           图集规格 / QA 清单 / 截图 / 历史设计文档
├── demo/           独立离线预览页
├── package.json  dsh.plugin.json  cordis.patch.yml
├── IMPLEMENTATION_NOTES.md   决策记录 / MAM 对齐索引表 / 前向风险评估
└── README.md  README.en.md  LICENSE  CHANGELOG.md

本机开发安装：dsh plugin --profile web add <仓库路径> 装的是 symlink；改完 src/ 后 npm run build，重启 dsh web 并硬刷新浏览器即生效。

版本发布

• main 是开发分支，随时合并新代码；对外用户的稳定版 = release 分支，只在发版时快进， 外部安装命令固定指向 #release（见「安装」节）。

• 发版：在 CHANGELOG.md 写好 [x.y.z] 条目后执行

  npm run release -- x.y.z        # 加 --dry-run 只校验不执行
  

  脚本会：校验（在 main、工作区干净、与远端同步、CHANGELOG 条目齐全）→ 同步 package.json / dsh.plugin.json 版本号 → build + validate + test → 提交并打 vX.Y.Z tag → 推送 → 把 release 分支快进到该提交并推送。

License

MIT