dsh-visual-skin

DeepSeek Harness Skin Studio — A one-click visual skinning 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 can automatically complete the full skinning workflow of image upload → theme creation → isolated preview → manual confirmation and application with just one image; you can also open the standalone Studio web page to visually adjust the skin and write it to DSH with one click.

✨ Features

Related MCP server: dstools

🎬 Demo

Animation by huashu-design · Storyboard cards at docs/demo/storyboard.md · Direction boards at docs/demo/direction-boards.html

📦 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 this skill);

3. Register DSH plugin (cordis.patch.yml managed block, includes 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. If Codex is detected, automatically sync Skill and register Codex MCP.

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

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

Give this repository to any agent and tell it:

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

The agent will complete the installation following the above process (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 opens: http://127.0.0.1:11862 (or click Start menu / tray icon)

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

🚀 Usage

After installation and restart, simply say to 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;

• Manually adjust in Studio (background, zones, tokens, separators) → Click Write to my DSH, manually confirm in the pop-up plan confirmation window → Restart DSH to apply.

Skinning 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; no arbitrary CSS/JS/URL.

• Preview uses an isolated temporary DSH owned by the Controller; confirmation and writing must be done manually 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, keys never land 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