|
### 🖼️ 정확한 멀티 프레임 미리보기
설치된 OpenPencil 헤드리스 내보내기가 디자인에 충실한 미리보기를 렌더링합니다. 첫 번째 최상위 프레임은 재생해도 안전한 대형 PNG로, 나머지는 가로로 스크롤 가능한 썸네일 트랙으로 제공되며, 클릭 선택 및 이전/다음 탐색을 통해 멀티 프레임 문서를 살펴볼 수 있습니다.
|
### 🗺️ 인터랙티브 캔버스
"인터랙티브 캔버스 열기"는 팬, 줌, 화면 맞춤이 지원되는 읽기 전용 OpenPencil 웹 SDK를 지연 마운트합니다 — 대화를 떠나지 않고 모든 페이지, 중첩 노드, 비활성 페이지를 검사할 수 있습니다.
|
|
### ✏️ 관리형 편집기
`editable: true`로 설정하면 편집 작업이 관리형 OpenPencil 편집기를 엽니다 — 선택, 레이어, 속성, 그리기 도구, 실행 취소/다시 실행, 명시적 저장 의미론 — 전체 화면 옵션이 있는 크기 조절 가능한 오른쪽 워크벤치에서 제공됩니다.
|
### 🤖 에이전트 네이티브 디자인 도구
직접 캔버스를 다루는 다섯 가지 도구와 여섯 가지 `openpencil_pipeline_*` 도구를 통해 에이전트는 관리형 OpenPencil 런타임에서 실제 캔버스를 생성, 검사, 개선, 게시, 수정, 읽을 수 있습니다.
|
|
### 🔐 권한 기반 승인
이미지 및 문서 승인은 서명되고 해시에 바인딩된 권한입니다. 브라우저 메타데이터는 임의의 호스트 경로를 절대 노출하지 않으며, 서명된 미리보기/편집기 권한은 정식 도구 결과나 모델 컨텍스트에 절대 들어가지 않습니다.
|
### ⚡ 트랜잭션 안전성
전체 파이프라인 문서는 모든 네이티브 및 DSH 품질 게이트를 통과할 때까지 비공개 미게시 초안에 머뭅니다. 게시 시 기존 경로를 덮어쓰지 않으며, 중단되거나 실패한 배치는 빈 대상 파일을 남기지 않습니다.
|
|
### 🌍 DSH의 룩앤필 준수
도구 카드와 관리형 편집기는 편집 세션을 다시 로드하지 않고도 DSH의 중국어/영어 로케일과 라이트/다크 테마를 따릅니다.
|
### 🎯 하나의 완결된 워크플로
"요구사항 → 사이드바의 private live canvas → 사용자에게 정확한 PNG를 보여 주는 두 개의 의미 단위 배치 → 네이티브/DSH 결정론적 품질 게이트 → 원자적 게시" — DSH 안에서 완결되는 하나의 루프입니다.
|
## DSH에 설치하기
DSH는 별도 패키지입니다. 아직 없다면 한 번 설치하세요:
```sh
npm install -g @deepseek-ai/dsh@latest
```
그다음 플러그인을 프로필에 추가하고 웹 앱을 실행합니다:
```sh
dsh plugin --profile web add @zseven-w/dsh-openpencil@next
dsh web
```
로컬 개발에서는 이 체크아웃을 빌드하고 절대 경로를 Web 프로필에 링크한 다음 DSH를 완전히 다시 시작하세요:
```sh
pnpm run build
dsh plugin --profile web add link:/absolute/path/to/dsh-openpencil
dsh web
```
`link:` 의존성은 이후 재빌드 결과를 이 체크아웃에서 바로 반영합니다. 단, 제공되는 Web 프로필은 기본적으로 호스트 번들을 핫 리로드하지 않으므로 프로필 의존성을 교체한 뒤에는 DSH를 완전히 다시 시작해야 합니다.
DSH를 전역 설치하고 싶지 않다면 같은 두 단계를 `pnpm dlx`로 실행하세요:
```sh
pnpm dlx --package=@deepseek-ai/dsh@latest dsh plugin --profile web add @zseven-w/dsh-openpencil@next
pnpm dlx --package=@deepseek-ai/dsh@latest dsh web
```
> OpenPencil 플러그인은 공개되어 npm 토큰이 필요 없습니다. DSH 프리릴리스 자체가 레지스트리 인증을 요구하는 경우, 해당 자격 증명은 체크아웃 외부의 사용자 수준 또는 임시 npm 구성에 보관하세요. 이 저장소에는 의도적으로 레지스트리 자격 증명이 포함되어 있지 않습니다.
## 디자인 도구
선택적 스타일 흐름은 `openpencil_style_plan` → `openpencil_style_confirm` → `openpencil_pipeline_begin`입니다. 원래 brief와 `style_selection`을 전달합니다. 카탈로그와 특정 가이드 선택에는 모델 추천이 필요 없으며 추천 제공자는 기본적으로 꺼져 있습니다. 이 전달은 script를 지원하며 app-agent와 상거래에는 지원되지 않습니다. 일반 app-agent 생성은 계속 사용할 수 있습니다.
| 도구 | 역할 |
| --- | --- |
| `openpencil_new` | 단순 작업을 위한 호환 빠른 경로입니다. 하나의 트랜잭션 QuickJS `batch_design` 스크립트를 실행하고 대상이 없을 때만 게시한 뒤 편집 가능 프레젠테이션을 반환합니다. 프로덕션 디자인에는 아래 전체 파이프라인을 우선 사용하세요. |
| `openpencil_pipeline_begin` | 소유 세션 전용 비공개 초안과 유일한 root를 시작하고, 같은 live canvas를 사이드바에서 즉시 엽니다. 대상 `.op`는 게시되지 않은 상태로 유지됩니다. |
| `openpencil_pipeline_context` | begin contract에 실제로 빠진 guideline, style, theme, UI kit 세부 정보 하나만 제한적으로 불러옵니다. 시작 시 refresh loop가 아닙니다. |
| `openpencil_pipeline_batch` | 직접 QuickJS 생성 스크립트를 최대 두 개 실행합니다. 성공한 각 트랜잭션은 사용자에게 정확한 PNG 표시만 시도하며, 도구가 반환되면 즉시 `next`를 따릅니다. |
| `openpencil_pipeline_inspect` | 사용자가 명시적으로 요청한 경우에만 수동 진단을 제공합니다. 일반 생성에서는 미리보기나 모델의 이미지 검사 단계로 사용하지 않습니다. |
| `openpencil_pipeline_finish` | 네이티브 및 DSH 결정론적 게이트를 실행하고 최종화 후 정확한 PNG를 렌더링한 뒤 `createIfAbsent`로 원자 게시합니다. `needs_correction`, `canContinue: true`, 완전한 비어 있지 않은 `repairTargets`, `omitted: 0`이 모두 있을 때만 U-only 수정 1회와 마지막 finish 1회를 허용하며, 그 밖의 미게시 결과는 terminal입니다. |
| `openpencil_pipeline_abort` | 대상 파일을 만들지 않고 미게시 초안을 버립니다. |
| `openpencil_create` | 트랜잭션 `batch_design` 프로그램을 적용하여 기존 라이브 캔버스에서 노드를 생성하거나 재구성합니다. |
| `openpencil_edit` | 명시된 노드 또는 사용자가 선택한 단일 노드를 수정합니다. |
| `openpencil_render` | 변경 불가능하고 콘텐츠 주소 지정 방식의 `.op` 스냅샷을 만들고 활성 페이지의 모든 최상위 프레임을 렌더링합니다 — 선택적 `scale` 및 `editable`. |
| `openpencil_selection` | 라이브 편집기 캔버스에서 선택된 정확한 노드를 읽습니다. |
## 에이전트 디자인 워크플로
일반 생성에는 고정된 짧은 경로를 사용합니다. `openpencil_pipeline_begin` → 직접 QuickJS `openpencil_pipeline_batch` 두 번 → `openpencil_pipeline_finish` 한 번입니다. Begin은 유일한 root를 만들고 비공개 live canvas를 사이드바에서 즉시 엽니다. 게시가 성공하기 전에는 요청한 워크스페이스 경로가 존재하지 않습니다. begin 또는 batch가 성공할 때마다 설명, 계획, 비교, 검사, 무관한 도구 호출 없이 다음 필수 호출을 즉시 실행합니다. 기본적으로 전체 디자인에는 이미지 하나만 사용하고, 각 Hero/Product/Art/Media frame에는 주 시각 요소 하나만 두며 이미지와 placeholder icon을 함께 두지 않습니다.
성공한 두 배치는 모두 사용자에게 정확한 PNG 미리보기를 표시하려고 시도합니다. 도구가 반환되면 즉시 `next`를 따르세요. `next`가 `previewUnavailable`을 보고해도 스크립트는 이미 live canvas에 커밋된 상태입니다. 배치를 다시 실행하지 말고 `openpencil_pipeline_inspect`나 `read_image`도 호출하지 마세요. `openpencil_pipeline_inspect`는 사용자가 명시적으로 요청한 진단에만 사용합니다.
Finish는 OpenPencil 네이티브 최종화, lint, 대비, 레이아웃 검사와 DSH 결정론적 품질 게이트를 실행하고, 정상 호출 하나에서 정확한 최종 PNG를 렌더링해 대상을 원자 게시합니다. 결과에 `stage: "needs_correction"`, `canContinue: true`, 완전한 비어 있지 않은 `repairTargets`와 `omitted: 0`이 동시에 있고 각 target에 `operation: "U"`, 정확한 비어 있지 않은 `nodeId`, 비어 있지 않은 `patch`가 있을 때만 수정을 허용합니다. 모든 target을 정확히 하나의 U-only batch로 함께 적용한 뒤 설명 없이 finish를 마지막으로 한 번만 호출합니다. 다른 미게시 결과, error, `canContinue: false`는 terminal입니다. 한 번만 보고하고 retry, inspect, image/context 읽기, abort, 대체 draft 시작을 하지 않습니다. 게이트 실패나 `openpencil_pipeline_abort` 시 대상은 생성되지 않습니다. published result의 정확한 최종 PNG와 live editor는 이미 authoritative하므로 이를 반환하고 즉시 종료합니다. 사이드바는 idle 상태일 때만 자동으로 열며 명시적 전환을 위한 **캔버스 편집**을 항상 유지합니다.
동일하게 실행 중인 DSH 서비스 안에서는 브라우저를 바꾸거나 다시 로드한 뒤에도 엄격히 파싱된 `openpencil_new` 또는 `openpencil_pipeline_finish`의 영속 publication을 정확한 PNG와 명시적인 **캔버스 편집** 작업으로 복원할 수 있습니다. 과거 카드는 사이드바를 자동으로 열지 않으므로 사용자가 해당 작업을 클릭해야 합니다. 일반 과거 `openpencil_render`는 읽기 전용으로 유지되며, 비 loopback 연결에는 편집기 권한이 발급되지 않습니다.
번들된 `openpencil-design` skill은 계속 스크립팅 및 품질 가이드를 제공하며, 관리형 런타임은 데스크톱 바이너리에 의존하지 않습니다. `openpencil_new`는 호환 가능한 단일 배치 빠른 경로로 유지되지만 프로덕션 품질 생성에는 전체 파이프라인을 우선 사용해야 합니다.
`openpencil_create`와 `openpencil_edit`은 기존 라이브 캔버스에만 사용하세요. 이들의 편집 내용은 편집기의 저장(Save) 작업 전까지 저장되지 않은 상태로 유지됩니다.
## 웹 뷰어 에셋
DSH는 클라이언트 플러그인에 대해 `client.js`만 제공하므로, OpenPencil ESM SDK, 해당 WASM 및 CanvasKit은 명시적인 동일 출처 에셋으로 준비됩니다:
```sh
pnpm run sync:viewer-assets
```
동기화 명령은 형제 `../openpencil` 체크아웃(로컬 개발)을 우선 사용하며, 벤더링된 `vendor/openpencil` 서브모듈(CI 및 새 클론)로 폴백합니다. `OPENPENCIL_ROOT` 또는 `--openpencil-root`로 재정의할 수 있습니다. `DSHPLUGIN_OPENPENCIL_VIEWER_SOURCE`로 완전한 사전 빌드 에셋 디렉터리를 선택할 수 있으며, `DSHPLUGIN_OPENPENCIL_VIEWER_ASSET_DIR`로 런타임 조회를 재정의할 수 있습니다.
뷰어 에셋은 사용자가 캔버스를 연 후에만 지연 로드됩니다. 에셋이 없거나 유효하지 않으면 PNG 미리보기를 계속 사용할 수 있으며 캔버스 버튼은 표시되지 않습니다.
## 관리형 편집기
편집 가능한 세션은 OpenPencil의 관리형 웹 호스트를 사용합니다 — `op-vscode`에서 사용하는 것과 동일한 아키텍처입니다. 플러그인은 인증된 사용자 작업 후에만 호스트를 시작하고, 데몬 토큰을 메모리에 보관하며, iframe 소스와 출처를 검증하고, 편집기 세션이 끝나면 프로세스를 종료합니다. 편집기 표면은 점진적으로 선택됩니다: 호스트가 해당 접합부(seam)를 선언하면 기본 Tool 세부 정보를, 그렇지 않으면 크기 조절 및 전체 화면 컨트롤이 있는 플러그인의 오른쪽 워크벤치를 사용합니다.
시작 시 느린 마운트에도 안전한 listening handshake를 사용하며, 번들 호스트가 바인딩 주소를 알린 뒤에만 readiness probe를 시작합니다. 데스크톱 OpenPencil 설치는 필요하지 않습니다.
게시된 설치 패키지는 `darwin-arm64`, `darwin-x64`, `linux-arm64`, `linux-x64`, `win32-arm64`, `win32-x64`의 여섯 개 네이티브 플랫폼 패키지 중 현재 OS/CPU에 맞는 패키지를 선택하며, 두 Linux 패키지는 glibc를 대상으로 합니다. 루트 패키지는 이를 정확한 버전의 `optionalDependencies`로 선언하여 패키지 관리자가 올바른 변형(예: `@zseven-w/dsh-openpencil-darwin-arm64`)을 선택하도록 합니다. 이 패키지는 서로 호환되는 `op-host-web-server`, 편집기 웹 번들, CanvasKit을 하나의 런타임으로 함께 제공합니다. 따라서 관리형 편집기는 `/Applications/OpenPencil.app`, `PATH`의 `openpencil-desktop` 또는 OpenPencil 소스 체크아웃에 의존하지 않습니다.
캔버스가 더티 상태인 동안 DSH가 플러그인을 다시 로드하거나 언로드하면, 호스트는 최대 7일 동안 불투명한 로컬 복구 초안을 보관합니다. 동일한 소스를 다시 열면 라이브 캔버스에 복원하기 전에 확인을 요청하며, 복구는 사용자가 명시적으로 저장하기 전까지 `.op` 파일을 절대 덮어쓰지 않습니다.
공식 6개 플랫폼 패키지는 보호된 release 빌드에서 중국/글로벌 협업 bootstrap 엔드포인트를 주입하고 검증한 뒤에만 게시됩니다. 이 주입 없이 로컬에서 직접 빌드한 경우 DSH를 시작하기 전에 `OPENPENCIL_COLLAB_BOOTSTRAP_URL=https://