susirial/dsh-traebao

DeepSeek Harness 的 TRAE 宝
住在 DSH Desktop 里的会话感知型数字宠物。
不是循环播放的 GIF。TRAE 宝会跟随 Agent 的思考、工具调用、完成与失败状态实时行动。

English
·
快速开始
·
观看宣传片

点击截图播放宣传片。本项目是独立社区插件，并非 TRAE 或 DeepSeek 官方产品。

为什么是 TRAE 宝？

编程 Agent 本来就有自己的生命周期，TRAE 宝把它变成看得见的陪伴：

- 真正感知会话：九种动画对应新会话、消息排队、思考、工具执行、成功和失败，不是随机播图。
- 原生融入 DSH Desktop：使用官方 shell.overlay 与 settings.section 扩展位，不替换产品布局。
- 每个动作都能定制：为九种状态替换 WebP，并给全部状态及左右键互动配置内置或自定义音效。
- 用户资源留在本机：文件存入 $DSH_HOME/pet-assets/dsh-juan-pet/，不会修改插件，也不会上传到外部服务。
- 桌面级文件选择体验：文件对话框由 Host 打开；macOS 使用附着于父窗口的 sheet，避免 renderer 文件输入导致的整窗白闪。
- 可验证的工程实现：严格 TypeScript、44 个单元测试，以及 Loader / 导出 / 资源完整性冒烟测试。

界面一览

| 对话中的数字伙伴 | 完整状态设置 |
| --- | --- |
| TRAE 宝在对话中 | TRAE 宝设置页 |

| 替换单个动作 | 配置内置或自定义音效 |
| --- | --- |
| 替换 TRAE 宝动作 | 配置 TRAE 宝音效 |

快速开始

环境要求

- 已安装并运行 DSH Desktop，当前 profile 为 desktop
- Node.js ^22.19.0 或 >=24.0.0

TRAE 宝装进 DSH Desktop 之后，会出现在对话界面和设置页。安装、更新、卸载走的是 Desktop 自带的 dsh 命令，不是另一个应用。Desktop 不会把 dsh 写进系统 PATH，所以要从托盘打开它的管理终端：菜单项在中文界面是 打开 DSH 终端，英文界面是 Open DSH Terminal。

从 GitHub 一行安装

1. 点击 DSH Desktop 托盘图标，选择 打开 DSH 终端。
2. 在刚打开的终端里执行：

dsh plugin --profile desktop add github:susirial/dsh-traebao

3. 从托盘彻底退出 DSH Desktop，再重新打开。 只关闭窗口不会重启 Host，也不会重新装载 Client bundle。

进入 设置 → TRAE 宝，即可启用、定位、缩放、静音、预览或定制宠物。

从本地源码安装

git clone https://github.com/susirial/dsh-traebao.git
cd dsh-traebao
corepack pnpm install --frozen-lockfile
corepack pnpm run check

在 Desktop 托盘打开的管理终端中运行；"." 会解析到当前 checkout。
dsh plugin --profile desktop add .

仓库提交了经过完整门禁验证的 lib/ 构建产物，所以直接从 GitHub 安装时不需要在用户 profile 中执行构建脚本。

更新、验证与卸载

更新 Git 依赖
dsh plugin --profile desktop update dsh-plugin-juan-pet

确认插件已经进入组合后的 profile
dsh --profile desktop --dump-config

卸载
dsh plugin --profile desktop remove dsh-plugin-juan-pet

更新或卸载后同样需要重启 Desktop。

普通终端提示找不到 dsh 怎么办？

这是正常情况。DSH Desktop 不会修改系统 PATH。请从托盘选择 打开 DSH 终端，它只在当前终端会话中加入与活动 profile 对应的 dsh。

如果本机有 DSH Desktop 源码 checkout，也可以直接调用其中钉住版本的 CLI：

/path/to/su-dsh-desktop/dsh-plugin-desktop/node_modules/.bin/dsh \
plugin --profile desktop add github:susirial/dsh-traebao

最后还可以使用 npx -y --package @deepseek-ai/dsh dsh ...，但它可能下载与 Desktop 当前版本不一致的 CLI，因此不作为首选。

Agent 生命周期如何变成动作

| DSH 活动 | TRAE 宝状态 |
| --- | --- |
| 新会话 | waving 挥手 |
| 消息入队 / 回合开始 | jumping 跳跃 |
| 工具执行 | waiting 等待工具 |
| 思考或产生 partial 输出 | review 思考 |
| 回合成功完成 | happy 完成 |
| 新工具错误或回合错误 | failed 失败 |
| 向左 / 向右拖动 | running-left / running-right |
| 其他情况 | idle 待机 |

边沿状态有优先级和保持时间，相同快照不会重复触发同一反应；失败优先于成功，工具执行优先于普通思考。

定制你的 TRAE 宝

在 设置 → TRAE 宝 中可以：

- 开关宠物、气泡和音效；
- 在 64–320 px 范围调整尺寸并保存位置；
- 预览任意状态；
- 为每个状态和鼠标交互选择音效；
- 替换单个动作、恢复默认动作，或批量导入全部动作；
- 导入和删除 MP3、WAV、OGG、M4A 音效。

批量导入动作图片时，请使用下面这些文件名（不区分大小写）：

idle.webp
waving.webp
running-left.webp
running-right.webp
waiting.webp
review.webp
jumping.webp
happy.webp
failed.webp

既可以使用系统选择器，也可以把文件拖到目标行或直接粘贴。WebP 上限为 10 MB，音频文件上限为 20 MB。

架构

TRAE 宝是一个可安装包，内部包含两套独立构建的运行面：

cordis.patch.yml
│
├── Host（ESM / Node）
│   ├── SettingsScope 设置源
│   ├── 静态资源和用户资源路由
│   ├── $DSH_HOME 下的校验型资源库
│   └── 可选 Electron 原生文件选择器
│
└── Client（CJS / 浏览器 Loader row）
├── shell.overlay → 可拖动动态宠物
├── settings.section → 预览和资源管理
└── CurrentConversation → PetStateController

浮层是 additive contribution，同时兼容 Desktop compatibility 与 advanced 外壳。纯浏览器 DSH 没有 Electron 文件选择器时，界面会自动退回拖放和粘贴。

开发与验证

corepack pnpm install --frozen-lockfile
corepack pnpm run build
corepack pnpm run typecheck
corepack pnpm run test
corepack pnpm run verify:loader

构建 + 类型检查 + 全部测试 + Loader 冒烟
corepack pnpm run check

源码以 src/ 为准。仓库保留 lib/，因为 DSH 会把 Git 托管插件当成已经可以装载的 package 安装。

兼容性与限制

- 当前针对 DSH 0.1.1-rc.2 包族和 Cordis 4.0.1 验证。
- 受浏览器自动播放策略限制，首次用户手势前不会播放声音。
- 位置按窗口像素保存；窗口缩小时不会自动改写位置。
- 内置角色只有 TRAE 宝，角色选择不在当前范围内。
- Desktop profile 必须提供 WebServer、settings、slots、sessions 和 SettingsScope。

安全与隐私

TRAE 宝没有遥测，也不会把宠物数据发送到外部服务。变更路由要求同源请求；静态路由拒绝路径穿越；导入文件会检查大小、扩展名、MIME 和文件魔数；用户文件使用私有权限原子写入。安全问题请按 SECURITY.md 报告。

参与贡献

欢迎提交缺陷报告、平台验证、测试，以及授权清晰的宠物资源。提交 PR 前请先阅读 CONTRIBUTING.md。

许可证与致谢

插件代码使用 MIT License。随仓库提供的视觉与音频素材有独立来源，不会自动继承代码许可证；再分发前请阅读 ASSETS.md。

TRAE、DeepSeek 及相关商标归各自权利人所有。本社区项目与其权利人没有隶属或背书关系。