dsh-visual-skin

DeepSeek Harness Skin Studio — 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.

설치 후, AI 어시스턴트는 이미지 한 장만으로 이미지 업로드 → 테마 생성 → 격리 미리보기 → 수동 확인 적용의 완전한 스킨 변경 프로세스를 자동으로 수행합니다. 또는 독립형 Studio 웹 페이지에서 시각적으로 스킨을 조정하고 원클릭으로 DSH에 적용할 수 있습니다.

✨ 기능

Related MCP server: dstools

🎬 데모

애니메이션 제작: huashu-design · 스토리보드: docs/demo/storyboard.md · 방향 보드: docs/demo/direction-boards.html

📦 설치

사전 요구 사항

방법 1: 명령줄 설치 (권장)

# 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

설치 프로그램이 자동으로 수행:

1. 자체 포함 휴대용 런타임(Controller + Studio + MCP + 플러그인, 약 51MB, Skill 디렉토리에 설치) 빌드/재사용;

2. Skill을 %DSH_HOME%\skills\deepseek-harness-skin-studio에 설치(DSH 어시스턴트가 즉시 해당 스킬 획득);

3. DSH 플러그인 등록(cordis.patch.yml 호스팅 블록, 스킨 설정 설정 카드 포함);

4. MCP 서버 등록(mcp__skin-studio__*, 설치된 자체 포함 런타임을 가리킴);

5. Studio 시작(Controller, 기본 포트 11862, 브라우저에서 http://127.0.0.1:11862 접속);

6. Codex 감지 시 자동으로 Skill 동기화 및 Codex MCP 등록.

설치 완료 후 DSH를 한 번 재시작(또는 데스크톱 런처에서 재시작)하여 profile patch와 MCP 클라이언트를 활성화합니다.

선택적 매개변수

예시 (사용자 지정 설치 + 설치 후 DSH 자동 재시작):

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

방법 2: AI 설치

이 저장소를 모든 agent에 전달하고 다음을 지시:

README와 이 저장소의 install.ps1을 읽고 설치를 실행하세요.

agent가 위 프로세스에 따라 설치를 완료합니다(직접 install.ps1을 실행할 수도 있음).

설치 확인

# 插件健康检查（在 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 열기: http://127.0.0.1:11862(또는 시작 메뉴/트레이 아이콘 클릭)

• DSH 설정 페이지에 '스킨 설정' 카드가 나타나야 함. 어시스턴트에게 "스킨 변경"이라고 말하면 mcp__skin-studio__* 도구가 트리거됩니다.

🚀 사용

설치 및 재시작 후 DSH 어시스턴트에게 직접 말하기:

• "스킨을 변경해줘" / "이 이미지를 배경으로 사용해줘" → 어시스턴트가 자동으로 mcp__skin-studio__*를 호출하여 제작을 완료하고 Studio에서 미리보기;

• "현재 스킨 배경을 바꿔줘" → 어시스턴트가 현재 디자인 수정;

• Studio에서 수동 조정(배경, 영역, 토큰, 구분선) → 내 DSH에 쓰기 클릭, 팝업 계획 확인 창에서 수동 확인 → DSH 재시작 후 적용.

스킨 변경 흐름도

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

🗂️ 디렉토리 구조

├─ 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 预览）

🛠️ 개발

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

🗑️ 제거

1. %DSH_HOME%\profiles\<profile>\cordis.patch.yml에서 # >>> dsh-skin-studio와 # <<< dsh-skin-studio 주석 블록 사이의 모든 항목 제거;

2. %DSH_HOME%\profiles\node_modules\@dsh-skin 및 %DSH_HOME%\skills\deepseek-harness-skin-studio 삭제;

3. DSH 재시작;

4. Studio 데이터 정리가 필요한 경우 %LOCALAPPDATA%\DeepSeekHarnessSkinStudio 삭제.

🔒 보안 및 호환성

• 대상 DSH 버전: 0.1.0-rc.6(기능 고정, 버전 불일치 시 플러그인 fail-closed).

• 스킨 모델(ThemeSpec)은 구조화된 데이터만 허용: 리터럴 CSS 색상, 콘텐츠 주소 지정 이미지(sha256), 제어된 토큰; 임의의 CSS/JS/URL은 허용되지 않음.

• 미리보기는 Controller가 소유한 격리된 임시 DSH를 사용. 확인 및 쓰기는 보이는 Studio에서 수동으로 완료해야 함.

• 잔액 조회: API Key는 호스트 측에서만 구문 분석(DSH_SKIN_BALANCE_API_KEY → DEEPSEEK_API_KEY → %DSH_HOME%\.credentials.yaml), 브라우저는 집계된 잔액만 표시, 키는 브라우저에 저장되지 않음.

📄 문서

• docx/ — 구현 계획, 요구 사항 분석 명세서, 기술 아키텍처 설계 명세서

• CHANGELOG.md — 변경 기록

• RELEASING.md — 릴리스 체크리스트 (GitHub Release / npm)

📃 License

MIT © 2026 trrrrrryg