dsh_theme_terraria

把 DeepSeek Harness 的 Web UI 换成一整块泰拉瑞亚（Terraria）像素世界——向导陪你写代码。

English Version

---

目录

1. 项目概述与核心定位
2. 安装与部署指南（含避坑）
3. 视觉设计系统（UI/UX 细节）
4. 音效交互系统（听觉反馈）
5. 隐藏彩蛋（叙事互动）
6. 性能优化与可访问性护栏
7. 项目维护信息（卸载、结构与许可）

---

1. 项目概述与核心定位

dsh_theme_terraria（npm 包名 dsh-theme-terraria）是 DeepSeek Harness（dsh）的泰拉瑞亚主题插件。它用一个自包含的 index.html（约 76 KB，零外部 JS 依赖）替换官方 React 前端，把「AI 编码代理控制台」包装成一场像素冒险：

• 标准 dsh 插件包：本仓库本身就是一个 npm 包——入口 index.js 导出插件规范硬性要求的 apply(ctx)，cordis.patch.yml 声明 dsh.bundle 补丁层，一条 dsh plugin --profile web add dsh-theme-terraria 即可安装/卸载，不改动 dsh 安装中的任何文件。
• 不是纯皮肤：主题直连 dsh 宿主的 JSON-RPC（HTTP 上行）+ WebSocket（事件下行）协议，会话创建、消息发送、流式输出、工具审批、模型切换、工作空间管理全部真实可用。填入 DeepSeek API 密钥即可与模型对话。
• 四个难度档 = 四个 Agent 预设：旅途（standard，全功能编码代理）、软核（code，Code Mode SDK）、中核（minimal，极简双工具）、硬核（cordis，自定义 preset 模板）。切难度就是切预设，插件的组合随难度实时变化。
• 单文件交付：整块 UI 内联在一个 HTML 文件里，由插件直接伺服，无任何运行时框架、无构建步骤。

核心定位一览

官方 UI 概念	泰拉瑞亚主题映射
Agent Preset（预设）	难度档：旅途 / 软核 / 中核 / 硬核
会话（Session）	旅途 / 冒险
用户消息	冒险者
工具审批请求	审批石板
任务清单（todo）	任务清单 HUD
API 密钥状态	生命水晶指示灯
插件组合	随难度更换的装备

---

2. 安装与部署指南（含避坑）

环境要求

• 已安装的 dsh（DeepSeek Harness）CLI，命令行 dsh --version 可用
• Node.js ^22.19 || >=24 与 pnpm（dsh plugin 内部转发给 pnpm 管理依赖）
• DeepSeek API 密钥（对话功能必需，其他界面可无密钥浏览）

安装步骤（标准插件安装）

# 1. 把主题作为插件安装进 web profile
dsh plugin --profile web add dsh-theme-terraria

# 2. 启动 Web 服务
dsh web
# 默认地址：http://127.0.0.1:3080/

dsh plugin add 会把 dsh-theme-terraria 写入 web profile 的依赖与 dsh.profile.bundles 层列表；本插件的 cordis.patch.yml 补丁层停用官方 web-runtime 行并插入同构的 terraria-theme 行，插件入口 index.js 导出的 apply(ctx) 再把官方 @deepseek-ai/dsh-web-app 的前端解析器指向本包的 web/index.html——除换皮外，官方 Web 运行时的全部行为（dist 伺服、/api 信任边界、DSH_WEB_URL、URL 打印）保持不变。

包尚未发布到 npm 时

# 从 GitHub 仓库安装（把 your-owner 替换为实际仓库所有者）
dsh plugin --profile web add github:your-owner/dsh_theme_terraria

# 或从本地检出的本仓库安装
dsh plugin --profile web add /path/to/dsh_theme_terraria

在 deepseek-harness 仓库内以源码方式运行 dsh 时，上述命令加 pnpm 前缀（如 pnpm dsh plugin --profile web add ...、pnpm dsh web）。

配置 API 密钥并开始对话

1. 打开 http://127.0.0.1:3080/ ，点击「新的会话」；
2. 首次进入会自动弹出「设置」——在「DeepSeek API 密钥」输入框填入 sk-...，点「保存密钥」；
3. 密钥经 credentials.set 存到宿主机（.dsh-home/.credentials.yaml），页面本身不持久保存明文；
4. HUD 面板显示「API 密钥：已配置」后，在对话框输入任何指令即可开始真实对话。

避坑指南（实测踩过的坑）

坑	现象	解法
浏览器缓存旧 UI	更新插件后页面还是旧样子	强制刷新 Ctrl+F5，或地址加 ?v=2 绕过缓存
dsh plugin add 失败	报 pnpm not found on PATH 或 pnpm 错误	dsh plugin 内部转发给 pnpm：安装 pnpm 并重开终端；git 方式安装的报错按提示在 profile 的 pnpm-workspace.yaml 补 allowBuilds 后重试
密钥保存失败	toast 报「保存失败」	确认 dsh web 由本机终端启动；沙箱化环境可能拦截宿主目录写入
图片壁纸存不下	「图片过大，保存失败」	localStorage 上限约 5 MB，主题已自动把非 GIF 图片压缩到 1920px JPEG；仍失败请换更小的图或用视频壁纸
文件夹选择器拿不到完整路径	选择文件夹后只有文件夹名	浏览器安全限制（所有网页一致）。主题会用「使用 E:\完整\路径」按钮智能回填已注册的同名目录，否则提示手动补全
WebSocket 断线	顶部提示「连接已断开，重连中…」	属正常自动重连（2 秒间隔）；宿主进程退出则需重启 dsh web

---

3. 视觉设计系统（UI/UX 细节）

设计语言：像素三原色 + 石板质感

整个 UI 的视觉基调由三层构成：

…