dsh-visual-skin

DeepSeek Harness Skin Studio — A one-click visual skin tool for DeepSeek Harness

A visual skin studio for DeepSeek Harness (DSH): design, preview and safely apply skins with one click — no config files to touch. Ship as an Agent Skill + MCP server + DSH plugin, with a one-shot PowerShell installer.

After installation, your AI assistant only needs one image to automatically complete the full skin process: image upload → theme creation → isolated preview → manual confirmation to apply; you can also open the standalone Studio web page to visually adjust the skin and write it to DSH with one click.

✨ Features

📦 Installation

Prerequisites

Method 1: Command Line Installation (Recommended)

# 1. 获取项目
git clone https://github.com/trrrrrryg/dsh-visual-skin.git
cd dsh-visual-skin

# 2. 一键安装（默认目标：%USERPROFILE%\.dsh，profile: web，Controller 端口 11862）
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1

The installer automatically completes:

1. Build/reuse self-contained portable runtime (Controller + Studio + MCP + plugin, ~51MB, installed under Skill directory);

2. Install Skill to %DSH_HOME%\skills\deepseek-harness-skin-studio (DSH assistant immediately gains the skill);

3. Register DSH plugin (cordis.patch.yml managed block, contains Skin Settings settings card);

4. Register MCP server (mcp__skin-studio__*, pointing to the installed self-contained runtime);

5. Start Studio (Controller, default port 11862, browser access http://127.0.0.1:11862);

6. When Codex is detected, automatically sync Skill and register Codex MCP.

After installation, restart DSH once (or restart in the desktop launcher) to apply the profile patch and MCP client changes.

Optional Parameters

Example (custom installation + auto restart DSH after installation):

.\install.ps1 -DshHome C:\Users\me\.dsh -ProfileName web -ControllerPort 12000 -RestartDsh

Method 2: AI Installation

Provide this repository to any agent and tell it:

Please read the README and the install.ps1 in this repository, then perform the installation.

The agent will follow the above process to complete the installation (it can also run install.ps1 directly).

Verify Installation

# 插件健康检查（在 DSH 端口上，应返回 ok:true；默认 DSH 端口 10402）
Invoke-RestMethod http://127.0.0.1:10402/dsh-skin/health

# Controller / Studio 状态检查（应返回 ok:true、capabilities.compatible:true）
Invoke-RestMethod http://127.0.0.1:11862/api/v1/status

• Studio opened: http://127.0.0.1:11862 (or click Start menu / tray icon)

• A "Skin Settings" card should appear in the DSH settings page; telling the assistant "change skin" will trigger the mcp__skin-studio__* tools.

🚀 Usage

After installation and restart, directly tell the DSH assistant:

• "Give me a new skin" / "Use this image as background" → The assistant automatically calls mcp__skin-studio__* to create the design and preview it in Studio;

• "Replace the current skin background" → The assistant modifies the current design;

• Adjust manually in Studio (background, zone, tokens, separator) → Click Write to my DSH, confirm in the pop-up plan confirmation window → restart DSH to take effect.

Skin Process Flowchart

用户指令 / 图片 ──▶ Agent Skill ──▶ MCP (design_create → asset_upload → theme_patch
                                      → theme_validate → preview_start)
                                              │
                                              ▼
                              隔离 DSH 预览（真实渲染，不碰你的 DSH）
                                              │
                                              ▼
                          Studio 可见确认（theme_apply_plan → theme_apply）
                                              │
                                              ▼
                              你的 DSH 皮肤生效（可随时 Restore 还原）

🗂️ Directory Structure

├─ install.ps1                     # 一键安装器（命令行 / AI）
├─ apps/
│  ├─ controller/                  # Studio 后端（API、隔离预览、apply/restore、GC）
│  └─ studio/                      # Studio Web UI（React + Vite）
├─ packages/
│  ├─ dsh-plugin/                  # DSH 插件（host 路由 + client 皮肤渲染）
│  ├─ theme-schema/                # ThemeSpec v2 数据契约
│  ├─ design-session-core/         # 设计会话 / 确认票据 / 操作日志
│  ├─ shared/                      # 跨端类型与错误码
│  ├─ agent-cli/                   # dsh-skin JSON CLI
│  ├─ mcp-server/                  # MCP stdio 服务器（26 个工具）
│  └─ portable-runtime/            # 便携运行时聚合
├─ agents/codex-skill/deepseek-harness-skin-studio/
│  ├─ SKILL.md                     # Agent Skill 指令（自动换肤流程）
│  └─ scripts/                     # open-studio / build-portable / install-local
├─ research/                       # 同类项目调研材料（16 个项目 README）
├─ docx/                           # 项目文档（实施计划 / 需求分析 / 架构设计）
└─ tests/                          # 回归测试（含真实 rc.6 隔离 Chromium 预览）

🛠️ Development

pnpm install          # 安装依赖（需要 Node 22+ / pnpm 11+）
pnpm build            # 构建全部包
pnpm test             # 回归测试（会启动真实 rc.6 隔离预览）
pnpm controller       # 本地启动 Controller（开发）
pnpm dev              # Studio 开发模式（Vite）

🗑️ Uninstallation

1. Remove all entries between # >>> dsh-skin-studio and # <<< dsh-skin-studio comment blocks in %DSH_HOME%\profiles\<profile>\cordis.patch.yml;

2. Delete %DSH_HOME%\profiles\node_modules\@dsh-skin and %DSH_HOME%\skills\deepseek-harness-skin-studio;

3. Restart DSH;

4. To clean up Studio data, delete %LOCALAPPDATA%\DeepSeekHarnessSkinStudio.

🔒 Security & Compatibility

• Target DSH version: 0.1.0-rc.6 (capability pinned; plugin fails closed if version mismatch).

• Skin model (ThemeSpec) only allows structured data: literal CSS colors, content-addressed images (sha256), controlled tokens; arbitrary CSS/JS/URL is not accepted.

• Preview uses an isolated temporary DSH owned by the Controller; confirmation and writing must be done manually by a human in the visible Studio.

• Balance query: API Key is only parsed on the host side (DSH_SKIN_BALANCE_API_KEY → DEEPSEEK_API_KEY → %DSH_HOME%\.credentials.yaml), the browser only sees aggregated balance, the key never lands in the browser.

📄 Documentation

• docx/ — Implementation plan, requirements analysis specification, technical architecture design specification

• CHANGELOG.md — Change log

• RELEASING.md — Release checklist (GitHub Release / npm)

📃 License

MIT © 2026 trrrrrryg