mirror of https://github.com/ZSeven-W/openpencil.git synced 2026-05-31 19:04:29 +07:00

* fix(renderer): skip paragraph image cache when zoomed in

* refactor(publish-cli): streamline version publishing process

- Removed the check for already published versions to simplify the workflow.
- Updated npm publish commands to handle already published versions gracefully, allowing the process to continue without aborting.
- Added publishing step for the new pen-ai-skills package, ensuring it is included in the deployment process.

* fix(mcp): wire openpencil codex install to config toml (#85)

Co-authored-by: Kaiiiiiiiii <182183652+Smile232323@users.noreply.github.com>

* refactor(mcp): reorganize codex-cli handling in installation process

- Removed the codex-cli configuration from CLI_CONFIGS and adjusted the installation logic to handle codex-cli actions directly.
- Improved error handling for unknown CLI tools and streamlined the installation process for codex-cli, ensuring it uses its own commands for adding/removing components.

* feat(agent): add built-in agent SDK and web integration

Introduces @zseven-w/agent — a domain-agnostic agent SDK with:
- Agent loop (plan→act→observe) with dual execution model
- Anthropic + OpenAI-compatible provider adapters via Vercel AI SDK
- Tool registry with auth levels (read/create/modify/delete/orchestrate)
- Agent team orchestration with delegate tool
- SSE streaming protocol encoder/decoder
- Sliding window context management

Web app integration:
- Built-in provider config UI with presets (Anthropic, OpenAI, OpenRouter, DeepSeek)
- Model search via provider API proxy endpoint
- Built-in models appear in the model dropdown alongside CLI agents
- Server-side agent SSE endpoint with session management
- Client-side tool executor with undo batch support
- Inline tool call blocks in chat UI

* feat(api): implement keep-alive pings for long-running LLM calls

- Added a keep-alive mechanism in the SSE stream for the agent API to prevent timeouts during long-running LLM calls.
- Updated the keep-alive interval to 8 seconds to align with Bun.serve's default idle timeout of 10 seconds.
- Ensured proper cleanup of the ping timer when the stream is closed.

* feat(mcp): enhance live sync diagnostics and port file management

- Implemented a mechanism to probe the live sync server's availability, providing clearer diagnostics for connection issues.
- Updated the port file structure to include a unique token for better management and cleanup.
- Enhanced the `getSyncUrl` and `getLiveSyncState` functions to return detailed status messages based on the server's response.
- Added tests for live sync diagnostics to ensure accurate reporting of server states.

* feat(mcp): implement sync URL caching for improved performance

- Added caching mechanism for sync URLs to reduce repeated reads and health checks, enhancing performance during live document and selection fetches.
- Introduced functions to set and clear the cached sync URL, improving connection management.
- Updated existing functions to utilize the cached URL when available, streamlining the fetching process.

* feat(skia): enhance syncFromDocument error handling and normalize document structure

- Wrapped the syncFromDocument method in a try-catch block to log errors during synchronization, improving debugging capabilities.
- Introduced normalization of external documents in the document store to ensure consistent structure before processing.
- Updated text content resolution to handle both 'content' and 'text' fields, enhancing compatibility with various node formats.
- Refactored text measurement functions to streamline text handling and improve layout consistency.

* chore: update package versions to 0.6.0 across all modules and enhance code generation pipeline

- Bumped version from 0.5.3 to 0.6.0 in package.json files for all modules including core, agent, and various code generation packages.
- Refactored code generation functions to utilize a new AI code generation pipeline, marking previous functions as deprecated with plans for removal in v1.0.0.
- Introduced new export nodes functionality in the MCP server for raw PenNode data export.

* fix(mcp): clear stale sync cache on page load to prevent false dirty state

When refreshing the page or opening a new file, the SSE document:init
event would echo back the old cached document, causing applyExternalDocument
to unconditionally set isDirty=true and trigger a spurious save prompt.

* style(panels): improve AI checklist visual design

Add progress bar, spinner animation, highlighted active items, and
pill-shaped counter badge for a more polished orchestrator progress UI.

* feat(ci): add Homebrew Cask update workflow for OpenPencil releases

- Implemented a new GitHub Actions job to update the Homebrew Cask for OpenPencil upon new version tags.
- The workflow fetches the latest macOS binaries, computes their SHA256 checksums, and updates the cask formula accordingly.
- Includes steps for committing and pushing changes to the tap repository.

* docs: update installation instructions in README and enhance CI workflow for Scoop bucket updates

- Added detailed installation instructions for macOS, Windows, and Linux in the README.
- Introduced a new GitHub Actions job to update the Scoop bucket with the latest OpenPencil release, including versioning and SHA256 checksum computation for Windows binaries.

* docs: add OpenPencil Skill plugin link to all i18n READMEs

Add localized LLM Skill link in CLI section across all 15 README
files, pointing to zseven-w/openpencil-skill repository.

* docs: add same-name project disclaimer to all i18n READMEs

Distinguish from open-pencil/open-pencil (Figma-compatible visual
design with real-time collaboration) — this project focuses on
AI-native design-to-code workflows.

* fix(agent): resolve SSE timeout, routing, and message format issues

- Add 5s keep-alive ping to agent SSE stream (prevents Bun 10s idle timeout)
- Consolidate tool-result and abort into single agent endpoint (?action=result|abort)
- Fix assistant message history: include text alongside tool-call parts
- Fix ToolResultPart format: use 'output' field with {type:'text',value} structure
- Use openai.chat() instead of openai() for Chat Completions API (OpenRouter compat)
- Use proper TOOL_SCHEMAS instead of z.any() for tool parameters

* fix(agent): prevent sliding window from splitting assistant+tool groups

The sliding window context strategy was naively slicing by message count,
which could leave orphaned tool_result messages without their preceding
assistant tool_use — causing Claude API to reject the request.

Now counts "logical turns" (user/assistant starts) and never cuts inside
an assistant→tool group. Also increased default window from 10 to 50 turns.

* fix(agent): use correct AI SDK v6 parameter name maxOutputTokens

streamText() in AI SDK v6 renamed maxTokens to maxOutputTokens.
Default 4096 prevents OpenRouter credit limit errors from requesting
the model's full 65536 token capacity.

* feat(agent): add API error classification and auto-retry without tools

When a model doesn't support function calling (400 errors, missing
arguments), the agent loop now classifies the error and automatically
retries without tools on the first turn. Also provides user-friendly
error messages for common failures: privacy restrictions, credit limits,
rate limiting, and incompatible models.

* fix(agent): improve system prompt with PenNode schema and workflow guidance

- Add PenNode property schema to agent system prompt so models know
valid properties (fills, cornerRadius, padding array, etc.)
- Explicitly forbid CSS properties (backgroundColor, boxShadow, etc.)
- Add workflow steps: plan before creating, avoid create-then-delete
- Change max turns reached from error to normal done event

* feat(agent): align insert_node with CLI batch_design capability

- insert_node now supports nested children arrays (recursive ID generation)
- Post-processing pipeline runs after insertion: role resolution, icon
resolution, layout sanitization, unique ID enforcement — same as MCP
batch_design with postProcess=true
- System prompt teaches model to create entire designs in ONE insert_node
call with nested children, instead of 20+ individual calls
- Includes concrete example of nested PenNode structure in prompt

* fix(agent): deep-clone node before post-processing to avoid Zustand mutation

Zustand state is immutable — post-processing functions mutate in-place.
JSON.parse(JSON.stringify()) creates a mutable copy. Each post-processing
step is individually try-caught so partial failures don't break insertion.

* fix(agent): return node count in insert_node result to prevent model retries

insert_node now returns {id, nodesCreated, message} so the model knows
the full tree was created. System prompt reinforces: when insert_node
succeeds, do NOT retry. Reduces 5+ duplicate insert calls to exactly 1.

* fix(agent): prevent duplicate root-level inserts from weaker models

Track the first root-level insert_node ID per session. Subsequent
root-level insert_node calls return the existing ID with a message
instead of creating duplicates. Fixes M2.5 and similar models that
ignore "do not retry" prompt instructions.

* feat(agent): support Anthropic API format in custom provider settings

Custom provider preset now has an API Format toggle: "OpenAI Compatible"
or "Anthropic". This allows users to configure custom Anthropic-compatible
endpoints (proxies, mirrors) in addition to OpenAI-compatible ones.
Anthropic provider also now accepts optional baseURL for proxy support.

* fix(agent): update Custom option label in provider dropdown

* fix(agent): match 'invalid function arguments' in error classifier for auto-retry

* fix(agent): always auto-retry without tools on first turn errors

Many providers (MiniMax, StepFun) have broken tool call implementations.
Instead of pattern-matching specific error messages, any streaming error
on turn 0 now triggers auto-retry without tools. The model falls back
to generating a text-only response instead of failing entirely.

* fix(agent): use clean JSON Schema for tool definitions (no $schema field)

Replaced Zod schemas with jsonSchema() from AI SDK for tool parameter
definitions. Zod's zodToJsonSchema adds "$schema" and "additionalProperties"
fields that strict OpenAI-compatible APIs (MiniMax, StepFun) reject with
"invalid function arguments". Clean JSON Schema only has type/properties/
required — compatible with all providers.

Also added text-mode fallback prompt for when tools are truly unsupported.

* fix(agent): ensure tool call args is always {} and fix turn>0 retry

Two fixes for MiniMax "invalid function arguments" error:
1. Ensure args is always {} (never undefined/null) when building
conversation history — undefined args causes strict APIs to reject
2. Auto-retry without tools now works on ANY turn (not just turn 0)
by resetting history to original user messages and restarting

* fix(agent): use SDK response.messages for history instead of manual construction

Root cause of MiniMax "invalid function arguments" error: we were manually
constructing ModelMessage[] for conversation history, which the SDK then
failed to convert correctly to OpenAI format (dropping function.arguments).

Fix: use response.response.messages from the SDK — it produces correctly
formatted messages that the provider knows how to convert. Only manually
add tool result messages for client-executed tools (no execute() function).

Also keeps a fetch interceptor as safety net to patch any remaining
edge cases with missing/malformed arguments.

* fix(agent): parse stringified JSON in insert_node data parameter

Some models (MiniMax M2.5) send insert_node data as a JSON string
instead of an object. Now handleInsertNode detects string data and
JSON.parse it before processing. Fixes nodesCreated:1 when model
sends nested children as a stringified object.

* fix(agent): sanitize node data and catch addNode side-effect errors

- Convert model's 'border' property to valid 'strokes' array
- Filter null/non-object children before processing
- Wrap docStore.addNode in try-catch — canvas sync side-effects
(e.g., renderer hitting unknown properties) may throw but the node
IS still inserted. Return success regardless.

* fix(agent): auto-zoom to fit after insert_node to show new design

* fix(agent): align insert_node with batch_design — auto-replace empty root frame

When inserting a frame at root level and an empty root frame exists,
replace it and inherit its position (x:0, y:0). This matches the MCP
batch_design behavior (line 146-161) so the design lands in the visible
viewport instead of off-screen at x:1250.

* fix(agent): use updateNode for empty frame replacement (no duplicate keys)

The remove+add pattern caused React duplicate key errors because two
separate Zustand state updates could leave the node in two places.
Now uses a single updateNode call to replace the empty frame's
properties in-place — atomic operation, no duplicates.

* fix(agent): set replaced=true BEFORE updateNode to prevent duplicate on side-effect throw

* fix(agent): use atomic tree swap for empty frame replacement

updateNode caused canvas sync crash (map on undefined) because the
renderer couldn't handle a complete property replacement on an existing
node. Now uses removeNodeFromTree + insertNodeInTree in a single
setState — same atomic approach as MCP batch_design. The Skia engine
sees the new node as a fresh addition, not an update to an existing one.

* fix(agent): simplify empty frame replacement to removeNode+addNode via store API

* refactor(agent): use applyNodesToCanvas instead of raw addNode

The agent's insert_node was bypassing the design pipeline's
sanitization and canvas sync code, causing blank canvas rendering.
Now delegates to the SAME applyNodesToCanvas function used by the
CLI/MCP design pipeline. This handles:
- sanitizeNodesForInsert (role defaults, layout fixes, unique IDs)
- isCanvasOnlyEmptyFrame → replaceEmptyFrame (empty frame at 0,0)
- icon resolution and image scanning
- proper Skia canvas sync

Removed the custom postProcessNode method — no longer needed since
applyNodesToCanvas does the same work correctly.

* feat(agent): add generate_design tool using internal CLI design pipeline

generate_design delegates to the SAME generateDesign() function the
standard chat uses — orchestrator, sub-agents, streaming insertion,
post-processing. Finds the first connected CLI provider for LLM calls.
Also uses insertStreamingNode with resetGenerationRemapping() for
insert_node, matching the CLI streaming pattern exactly.

* feat(agent): replace insert_node with generate_design as primary design tool

Remove insert_node and find_empty_space from agent tool set — models
should use generate_design for creating designs, not raw PenNode JSON.
generate_design accepts natural language prompts and delegates to the
full internal pipeline. Keeps update_node/delete_node for modifications.

* feat(agent): simplify system prompt to direct models to generate_design

Clear instruction: when user asks to create/design, MUST call
generate_design tool. No JSON output, no manual node construction.

* fix(agent): strip <think> tags from model text output in chat UI

Models like MiniMax M2.5 and DeepSeek output <think>...</think> as
plain text (not via the thinking SSE event). Strip both closed and
unclosed <think> tags from the displayed text during streaming.

* fix(renderer): skip paragraph image cache when zoomed out below 0.5x

Bitmap text cache at fixed DPR resolution produces jagged edges when
scaled down significantly. Now only uses cache at 0.5x–1x zoom range.
Below 0.5x and above 1x, falls back to vector Paragraph API rendering.

* fix(ai): prevent model from using OpenPencil as brand name in generated designs

* fix(agent): strip <think> tags from final message, not just during streaming

The regex was only applied during text-delta events but the final
message (returned by runAgentStream and set in done/error handlers)
used the raw accumulated text. Now stripThinkTags() is applied at
the return point so the final displayed message is always clean.

* fix(ai): reduce keepalive ping interval from 15s to 5s for Bun compatibility

Bun.serve has a 10s idle timeout. The previous 15s ping interval meant
the first ping arrived AFTER Bun killed the connection, causing
"socket connection was closed unexpectedly" errors when waiting for
slow LLM responses (extended thinking, TTFT > 10s). Now pings at 5s.

* fix(renderer): rasterize paragraph image cache at 2x minimum for crisp text on low-DPR

* fix(agent): remove hardcoded TOOL_SCHEMAS and maxOutputTokens

- Server uses client-provided JSON schemas (single source of truth)
- maxOutputTokens configurable per provider, defaults to model limit
- turnTimeout increased to 5min for generate_design pipeline
- Session cleanup wrapped in try-catch
- Re-export streamText from agent SDK for consumer use

* feat(agent): add builtin provider support to /api/ai/chat endpoint

streamViaBuiltin() uses Vercel AI SDK to call LLM directly with API
key — no CLI tool required. ai-service.ts attaches builtin credentials
from agent settings store when provider is 'builtin'. This enables
generate_design to work without any CLI provider connected.

* fix(agent): align generate_design params with CLI pipeline and handle field name variants

- Pass concurrency, variables, themes, designMd to generateDesign()
(was missing, causing lower quality output vs CLI mode)
- Accept both 'prompt' and 'description' field names from models
- Fall back to builtin provider when no CLI provider connected
- Enable animated node insertion

* feat(agent): dynamic system prompt via pen-ai-skills + misc fixes

- Replace hardcoded AGENT_SYSTEM_PROMPT with buildAgentSystemPrompt()
that loads design knowledge from pen-ai-skills (same as CLI pipeline)
- Validate builtin provider apiKey before agent connection
- Client-side tool schema serialization for server (no duplication)
- Update tool_call block status locally as fallback for lost SSE events
- Pass maxOutputTokens from provider config

* refactor(agent): extract builtin provider settings to separate file

Split BuiltinProviderForm, BuiltinProviderCard, BuiltinProvidersSection
from agent-settings-dialog.tsx (1279→730 lines) into
builtin-provider-settings.tsx (394 lines). Both under 800 line limit.

* refactor(agent): extract model selector to separate file

Split ModelDropdown, ConcurrencyButton, resolveNextModel, PROVIDER_ICON
from ai-chat-panel.tsx (915→690 lines) into ai-chat-model-selector.tsx
(183 lines). Both under 800 line limit.

* fix(renderer): guard against undefined fill entries in resolveFillColor/resolveStrokeColor

* feat(ai): extend BuiltinProviderPreset with 9 new providers

Add MiniMax, Zhipu, Kimi, Bailian, DouBao, Xiaomi MiMo, ModelScope,
StepFun and NVIDIA NIM to the builtin provider preset type union.

* feat(ai): add provider presets and region switcher for builtin providers

Add preset configs for MiniMax, Zhipu, Kimi, Bailian (DashScope),
DouBao Seed, Xiaomi MiMo, ModelScope, StepFun and NVIDIA NIM with
correct API base URLs and model placeholders.

Providers with separate China/Global endpoints (MiniMax, Zhipu, Kimi,
Bailian, StepFun) get a region toggle that auto-switches the base URL.
Region inference works both for new providers and when editing existing
ones via REGION_URLS reverse-lookup table.

* style(ai): increase settings dialog height for more provider entries

* feat(ai): add i18n for builtin provider settings (15 locales)

Extract all hardcoded strings in builtin-provider-settings.tsx to
i18n keys under the builtin.* namespace. Add translations for all
15 supported languages: en, zh, zh-TW, ja, ko, fr, es, de, pt,
ru, hi, tr, th, vi, id.

* fix(ai): remove remaining hardcoded strings in builtin provider UI

- Extract error messages, badge text, tooltip, and placeholder to i18n
- Remove unused region label fields from PresetRegion interface
- Add 8 new builtin.* keys across all 15 locales
- Fix ai-chat-model-selector API Key badge and parallel agents tooltip
- Fix ai-chat-panel provider description template
- Fix ai-chat-handlers error messages via i18n.t()

* fix(agent): clean up pending tool calls on exit and improve error handling

P0: Wrap agent loop generator in try-finally to reject all pending tool
call promises and clear timeout timers when the loop exits. Prevents
timeout leaks when sessions end early.

P1: Add HTTP status code matching (429, 402, 403) before regex fallback
in classifyAPIError for more reliable error classification.

P1: Clone tool registry in createTeam instead of mutating the caller's
config.lead.tools. Add doc comment for unused _maxTokens parameter in
sliding-window strategy.

* fix(ai): add error handling and retry for tool result POST

The POST to /api/ai/agent?action=result had no error handling. If it
failed, the agent loop would hang forever waiting for the tool result.
Now retries once on failure and logs the error.

* fix(ai): use lastActivity for session TTL and guard stream init

P1: Add lastActivity timestamp to AgentSession, updated on every event
and tool result. TTL cleanup now checks lastActivity instead of
createdAt, preventing active long-running sessions from being killed.

P1: Wrap ReadableStream construction in try-catch to ensure session
cleanup if stream initialization fails.

* chore: add docs/ to gitignore

* fix(ai): update model lists and fix model search for providers

- Update Anthropic models to include Claude 4.6 (Opus + Sonnet)
- Update model placeholders: OpenAI→gpt-5.4, MiniMax→M2.7,
Zhipu→glm-5, Kimi→kimi-k2.5, Xiaomi→mimo-v2-pro
- Add hardcoded model lists for MiniMax and DouBao (no /models API)
- Generalize ANTHROPIC_MODELS to BUILTIN_MODEL_LISTS lookup table
- Fix provider-models proxy to handle { models: [...] } and array
response formats in addition to OpenAI's { data: [...] }

* docs: update CLAUDE.md and README files for new AI agent SDK and i18n support

- Added new sections in CLAUDE.md detailing the AI agent SDK and its multi-provider capabilities.
- Updated README files in multiple languages to include information about the built-in AI agent SDK and full interface localization in 15 languages.
- Adjusted key technologies and scopes to reflect recent changes in the project structure and features.

* docs(agent): add Agent Team web integration design spec

Phase 3 design: model routing via Agent Team. Lead agent uses fast
model for chat, designer member uses capable model for generation.
SDK changes: source tracking on events, member_start/end events,
auto team suffix. Web changes: team toggle + design model selector
in settings, conditional createTeam in server endpoint.

* fix(electron): fix Scoop/Homebrew tap auto-update in CI

- Add pre_install to Scoop manifest to rename versioned exe to OpenPencil.exe
- Add mkdir -p for Casks/ and bucket/ dirs in tap repos
- Use curl -fSL to fail fast on HTTP errors instead of silent mode

* docs(agent): add Agent Team web integration implementation plan

9 tasks: SDK event types → SSE tests → team source injection →
server team endpoint → settings store → team UI → i18n →
chat handler wiring → e2e verification

* feat(agent): add source field and team events to AgentEvent type

* test(agent): add SSE encoder/decoder tests for source and team events

* feat(agent): inject source field and team events in agent-team

* feat(ai): extend agent endpoint to support team mode with members

* feat(ai): add teamEnabled and teamDesignModel to agent settings store

* feat(ai): wire team mode in chat handlers with member events

* feat(ai): add i18n keys for team settings (15 locales)

* feat(ai): add Team section UI with design model selector

* fix(agent): route resolveToolResult to correct agent in team mode

Member tool calls (e.g. generate_design) were routed to leadAgent
which didn't have them in its pending map. Added toolCallOwners map
to track which agent (lead or member) issued each tool call and
route resolveToolResult accordingly.

* docs(agent): clarify resolveToolResult routing, member tools, and source handling

* fix(agent): force delegation in team mode and add turnTimeout support

Two fixes for team mode generation failures:
1. Remove generate_design from lead's tool registry in team mode,
forcing the lead to delegate design work to the designer member
2. Add turnTimeout to TeamMemberConfig/TeamConfig and pass 5min
timeout to member agents (generate_design needs it)

* fix(ai): make team mode visually distinct in chat UI

- Add source badge on tool call blocks (shows "designer" pill for
member-initiated tool calls)
- Pass evt.source to ToolCallBlockData
- Use blockquote format for member_start/end events so team activity
is clearly visible in the chat stream

* fix(agent): scope designer tools, streamline delegation, add model hint

1. Designer member only gets generate_design + snapshot_layout
(was: all tools, causing 7 wasteful batch_get calls)
2. Team suffix tells lead to delegate immediately without verbose
planning text
3. UI shows amber tip when only 2 providers configured, suggesting
a more capable model for design

* fix(ai): clean up partial nodes on generate_design failure

When generate_design fails midway, partial nodes were left on the
canvas and rootInsertId was not set, allowing a retry that created
a duplicate design. Now:
1. Set rootInsertId='generating' BEFORE calling generateDesign
2. Snapshot node IDs before generation
3. On failure, remove all new nodes and reset rootInsertId to null
4. Remove incorrect same-model warning from Team UI

* fix(ai): show Team section with 1 enabled provider

* refactor(ai): smart team mode — auto-enable when design model is set

Remove manual Team toggle. Selecting a Design Model automatically
enables team mode; "None (single agent)" disables it. Simpler UX:
one dropdown replaces toggle + dropdown. Updated descriptions and
removed obsolete teamTitle/teamSameModelWarning i18n keys.

* fix(agent): properly serialize non-Error objects in error messages

String(err) on plain objects produces "[object Object]". Changed to
err instanceof Error ? err.message : JSON.stringify(err) for readable
error messages in tool results and design generation failures.

* refactor(ai): auto team mode using current chat model

Remove Design Model dropdown from settings. Team mode is now fully
automatic: the designer member always uses the same provider/model
as the current chat selection. Zero configuration needed — the value
is in role separation (different prompts + scoped tools), not model
selection.

* style(ai): use min/max height for settings dialog instead of fixed height

* feat(ai): add Google Gemini to builtin provider presets

Base URL: generativelanguage.googleapis.com/v1beta/openai (OpenAI
compatible). Hardcoded model list: Gemini 2.5 Pro, 2.5 Flash, 2.0
Flash. API key placeholder: AIza...

* feat(ai): update Gemini models to 3.x series

---------

Co-authored-by: Fini <fini.yang@gmail.com>
Co-authored-by: Kaiiiiiiiii <2761362118@qq.com>
Co-authored-by: Kaiiiiiiiii <182183652+Smile232323@users.noreply.github.com>

2026-03-28 23:12:37 +08:00

18 KiB

Raw Blame History

OpenPencil

세계 최초의 오픈소스 AI 네이티브 벡터 디자인 툴.
_{동시 에이전트 팀 • 디자인-애즈-코드 • 내장 MCP 서버 • 멀티 모델 인텔리전스}

English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Français · Español · Deutsch · Português · Русский · हिन्दी · Türkçe · ไทย · Tiếng Việt · Bahasa Indonesia

_{이미지를 클릭하여 데모 영상 보기}

참고: 같은 이름의 다른 오픈소스 프로젝트가 있습니다 — OpenPencil. 해당 프로젝트는 Figma 호환 비주얼 디자인과 실시간 협업에 중점을 둡니다. 본 프로젝트는 AI 네이티브 디자인-투-코드 워크플로에 중점을 둡니다.

OpenPencil을 선택하는 이유

🎨 프롬프트 → 캔버스

자연어로 어떤 UI든 설명하세요. 무한 캔버스 위에 스트리밍 애니메이션과 함께 실시간으로 나타납니다. 요소를 선택하고 대화하여 기존 디자인을 수정할 수 있습니다.

🤖 동시 에이전트 팀

오케스트레이터가 복잡한 페이지를 공간적 서브태스크로 분해합니다. 여러 AI 에이전트가 히어로, 기능 소개, 푸터 등 각기 다른 섹션을 동시에 작업하며 모두 병렬로 스트리밍됩니다.

🧠 멀티 모델 인텔리전스

각 모델의 역량에 자동 적응합니다. Claude는 사고 모드가 포함된 전체 프롬프트를 받고, GPT-4o/Gemini는 사고 모드를 비활성화하며, 소형 모델(MiniMax, Qwen, Llama)은 안정적인 출력을 위해 단순화된 프롬프트를 받습니다.

🔌 MCP 서버

Claude Code, Codex, Gemini, OpenCode, Kiro 또는 Copilot CLI에 원클릭 설치. 터미널에서 디자인하세요 — MCP 호환 에이전트를 통해 .op 파일을 읽고, 생성하고, 편집할 수 있습니다.

📦 디자인-애즈-코드

.op 파일은 JSON입니다 — 사람이 읽을 수 있고, Git 친화적이며, diff가 가능합니다. 디자인 변수는 CSS 커스텀 프로퍼티를 생성합니다. React + Tailwind 또는 HTML + CSS로 코드 내보내기가 가능합니다.

🖥️ 어디서든 실행

웹 앱 + Electron을 통한 macOS, Windows, Linux 네이티브 데스크톱. GitHub Releases에서 자동 업데이트. .op 파일 연결 — 더블 클릭으로 열기.

⌨️ CLI — `op`

터미널에서 디자인 도구 제어. op design, op insert, op export — 배치 디자인 DSL, 노드 조작, 코드 내보내기. 파일이나 stdin에서 파이프 입력 지원. 데스크톱 앱 또는 웹 서버와 연동.

🎯 멀티 플랫폼 코드 내보내기

하나의 .op 파일에서 React + Tailwind, HTML + CSS, Vue, Svelte, Flutter, SwiftUI, Jetpack Compose, React Native로 내보내기. 디자인 변수는 CSS 커스텀 프로퍼티로 변환.

빠른 시작

# 의존성 설치
bun install

# http://localhost:3000 에서 개발 서버 시작
bun --bun run dev

또는 데스크톱 앱으로 실행:

bun run electron:dev

필수 조건: Bun >= 1.0 및 Node.js >= 18

Docker

여러 이미지 변형을 사용할 수 있습니다 — 필요에 맞는 것을 선택하세요:

이미지	크기	포함 내용
`openpencil:latest`	~226 MB	웹 앱만
`openpencil-claude:latest`	—	+ Claude Code CLI
`openpencil-codex:latest`	—	+ Codex CLI
`openpencil-opencode:latest`	—	+ OpenCode CLI
`openpencil-copilot:latest`	—	+ GitHub Copilot CLI
`openpencil-gemini:latest`	—	+ Gemini CLI
`openpencil-full:latest`	~1 GB	모든 CLI 도구

실행 (웹만):

docker run -d -p 3000:3000 ghcr.io/zseven-w/openpencil:latest

AI CLI와 함께 실행 (예: Claude Code):

AI 채팅은 Claude CLI OAuth 로그인에 의존합니다. Docker 볼륨을 사용하여 로그인 세션을 유지하세요:

# 1단계 — 로그인 (최초 1회)
docker volume create openpencil-claude-auth
docker run -it --rm \
  -v openpencil-claude-auth:/root/.claude \
  ghcr.io/zseven-w/openpencil-claude:latest claude login

# 2단계 — 시작
docker run -d -p 3000:3000 \
  -v openpencil-claude-auth:/root/.claude \
  ghcr.io/zseven-w/openpencil-claude:latest

로컬 빌드:

# 기본 (웹만)
docker build --target base -t openpencil .

# 특정 CLI 포함
docker build --target with-claude -t openpencil-claude .

# 전체 (모든 CLI)
docker build --target full -t openpencil-full .

AI 네이티브 디자인

프롬프트에서 UI로

텍스트-투-디자인 — 페이지를 설명하면 스트리밍 애니메이션으로 실시간으로 캔버스에 생성
오케스트레이터 — 복잡한 페이지를 공간적 서브태스크로 분해하여 병렬 생성
디자인 수정 — 요소를 선택하고 자연어로 변경 사항을 설명
비전 입력 — 스크린샷이나 목업을 참조로 첨부하여 디자인

멀티 에이전트 지원

에이전트	설정 방법
내장 (9+ 제공자)	제공자 프리셋에서 선택하고 지역을 전환 — Anthropic, OpenAI, Google, DeepSeek 등
Claude Code	설정 불필요 — 로컬 OAuth로 Claude Agent SDK 사용
Codex CLI	에이전트 설정에서 연결 (`Cmd+,`)
OpenCode	에이전트 설정에서 연결 (`Cmd+,`)
GitHub Copilot	`copilot login` 후 에이전트 설정에서 연결 (`Cmd+,`)
Gemini CLI	에이전트 설정에서 연결 (`Cmd+,`)

모델 역량 프로파일 — 모델 티어에 따라 프롬프트, 사고 모드, 타임아웃을 자동 조정합니다. 풀 티어 모델(Claude)은 완전한 프롬프트를 받고, 스탠다드 티어(GPT-4o, Gemini, DeepSeek)는 사고 모드를 비활성화하며, 베이직 티어(MiniMax, Qwen, Llama, Mistral)는 최대 안정성을 위해 단순화된 중첩 JSON 프롬프트를 받습니다.

i18n — 15개 언어로 완전한 인터페이스 지역화: English, 简体中文, 繁體中文, 日本語, 한국어, Français, Español, Deutsch, Português, Русский, हिन्दी, Türkçe, ไทย, Tiếng Việt, Bahasa Indonesia.

MCP 서버

내장 MCP 서버 — Claude Code / Codex / Gemini / OpenCode / Kiro / Copilot CLI에 원클릭 설치
Node.js 자동 감지 — 설치되지 않은 경우 HTTP 전송 모드로 자동 대체하고 MCP HTTP 서버를 자동 시작
터미널에서 디자인 자동화: MCP 호환 에이전트를 통해 .op 파일 읽기, 생성, 편집
계층적 디자인 워크플로 — design_skeleton → design_content → design_refine으로 더 높은 충실도의 멀티 섹션 디자인
세그먼트 프롬프트 검색 — 필요한 디자인 지식만 로드 (schema, layout, roles, icons, planning 등)
멀티 페이지 지원 — MCP 도구를 통해 페이지 생성, 이름 변경, 순서 변경, 복제

코드 생성

React + Tailwind CSS, HTML + CSS, CSS Variables
Vue, Svelte, Flutter, SwiftUI, Jetpack Compose, React Native

CLI — `op`

전역 설치 후 터미널에서 디자인 도구를 제어하세요:

npm install -g @zseven-w/openpencil

op start                     # 데스크톱 앱 실행
op design @landing.txt       # 파일에서 배치 디자인
op insert '{"type":"RECT"}'  # 노드 삽입
op export react --out .      # React + Tailwind로 내보내기
op import:figma design.fig   # Figma 파일 가져오기
cat design.dsl | op design - # stdin에서 파이프 입력

세 가지 입력 방식을 지원합니다: 인라인 문자열, @filepath (파일에서 읽기), - (stdin에서 읽기). 데스크톱 앱 또는 웹 개발 서버와 연동됩니다. 전체 명령어 레퍼런스는 CLI README를 참고하세요.

LLM 스킬 — OpenPencil Skill 플러그인을 설치하면 AI 에이전트(Claude Code, Cursor, Codex, Gemini CLI 등)에게 op를 사용한 디자인을 교육할 수 있습니다.

기능

캔버스 & 드로잉

팬, 줌, 스마트 정렬 가이드, 스냅 지원의 무한 캔버스
Rectangle, Ellipse, Line, Polygon, Pen(Bezier), Frame, Text
불리언 연산 — 합치기, 빼기, 교차 (컨텍스트 툴바)
아이콘 피커(Iconify)와 이미지 가져오기(PNG/JPEG/SVG/WebP/GIF)
오토 레이아웃 — 수직/수평 방향, gap, padding, justify, align 지원
탭 내비게이션이 있는 멀티 페이지 문서

디자인 시스템

디자인 변수 — 컬러, 숫자, 문자열 토큰, $variable 참조 지원
멀티 테마 지원 — 여러 테마 축, 각 축에 변형(Light/Dark, Compact/Comfortable)
컴포넌트 시스템 — 인스턴스와 오버라이드를 가진 재사용 가능한 컴포넌트
CSS 동기화 — 커스텀 프로퍼티 자동 생성, 코드 출력에 var(--name) 사용

Figma 가져오기

레이아웃, 채우기, 선, 효과, 텍스트, 이미지, 벡터를 유지하며 .fig 파일 가져오기

데스크톱 앱

Electron을 통한 네이티브 macOS, Windows, Linux 지원
.op 파일 연결 — 더블 클릭으로 열기, 단일 인스턴스 잠금
GitHub Releases에서 자동 업데이트
네이티브 애플리케이션 메뉴와 파일 다이얼로그

기술 스택


프론트엔드	React 19 · TanStack Start · Tailwind CSS v4 · shadcn/ui · i18next
캔버스	CanvasKit/Skia (WASM, GPU 가속)
상태 관리	Zustand v5
서버	Nitro
데스크톱	Electron 35
CLI	`op` — 터미널 제어, 배치 디자인 DSL, 코드 내보내기
AI	Vercel AI SDK v6 · Anthropic SDK · Claude Agent SDK · OpenCode SDK · Copilot SDK
런타임	Bun · Vite 7
파일 형식	`.op` — JSON 기반, 사람이 읽을 수 있는, Git 친화적

프로젝트 구조

openpencil/
├── apps/
│   ├── web/                 TanStack Start 웹 앱
│   │   ├── src/
│   │   │   ├── canvas/      CanvasKit/Skia 엔진 — 드로잉, 동기화, 레이아웃
│   │   │   ├── components/  React UI — 에디터, 패널, 공유 다이얼로그, 아이콘
│   │   │   ├── services/ai/ AI 채팅, 오케스트레이터, 디자인 생성, 스트리밍
│   │   │   ├── stores/      Zustand — 캔버스, 문서, 페이지, 히스토리, AI
│   │   │   ├── mcp/         외부 CLI 통합용 MCP 서버 도구
│   │   │   ├── hooks/       키보드 단축키, 파일 드롭, Figma 붙여넣기
│   │   │   └── uikit/       재사용 가능한 컴포넌트 킷 시스템
│   │   └── server/
│   │       ├── api/ai/      Nitro API — 스트리밍 채팅, 생성, 유효성 검사
│   │       └── utils/       Claude CLI, OpenCode, Codex, Copilot 래퍼
│   ├── desktop/             Electron 데스크톱 앱
│   │   ├── main.ts          윈도우, Nitro 포크, 네이티브 메뉴, 자동 업데이터
│   │   ├── ipc-handlers.ts  네이티브 파일 대화상자, 테마 동기화, 환경설정 IPC
│   │   └── preload.ts       IPC 브리지
│   └── cli/                 CLI 도구 — `op` 명령어
│       ├── src/commands/    디자인, 문서, 내보내기, 가져오기, 노드, 페이지, 변수 명령어
│       ├── connection.ts    실행 중인 앱과의 WebSocket 연결
│       └── launcher.ts      데스크톱 앱 또는 웹 서버 자동 감지 및 실행
├── packages/
│   ├── pen-types/           PenDocument 모델 타입 정의
│   ├── pen-core/            문서 트리 연산, 레이아웃 엔진, 변수
│   ├── pen-codegen/         코드 생성기 (React, HTML, Vue, Flutter, ...)
│   ├── pen-figma/           Figma .fig 파일 파서 및 변환기
│   ├── pen-renderer/        독립형 CanvasKit/Skia 렌더러
│   ├── pen-sdk/             통합 SDK (모든 패키지 재export)
│   ├── pen-ai-skills/       AI 프롬프트 스킬 엔진 (단계별 프롬프트 로딩)
│   └── agent/               AI 에이전트 SDK (Vercel AI SDK, 멀티 제공자, 에이전트 팀)
└── .githooks/               브랜치 이름에서 버전 동기화를 위한 pre-commit

키보드 단축키

키	동작	키	동작
`V`	선택	`Cmd+S`	저장
`R`	사각형	`Cmd+Z`	실행 취소
`O`	타원	`Cmd+Shift+Z`	다시 실행
`L`	직선	`Cmd+C/X/V/D`	복사/잘라내기/붙여넣기/복제
`T`	텍스트	`Cmd+G`	그룹화
`F`	Frame	`Cmd+Shift+G`	그룹 해제
`P`	펜 툴	`Cmd+Shift+E`	내보내기
`H`	핸드(팬)	`Cmd+Shift+C`	코드 패널
`Del`	삭제	`Cmd+Shift+V`	변수 패널
`[ / ]`	순서 변경	`Cmd+J`	AI 채팅
화살표 키	1px 이동	`Cmd+,`	에이전트 설정
`Cmd+Alt+U`	불리언 합치기	`Cmd+Alt+S`	불리언 빼기
`Cmd+Alt+I`	불리언 교차

스크립트

bun --bun run dev          # 개발 서버 (포트 3000)
bun --bun run build        # 프로덕션 빌드
bun --bun run test         # 테스트 실행 (Vitest)
npx tsc --noEmit           # 타입 검사
bun run bump <version>     # 모든 package.json에 버전 동기화
bun run electron:dev       # Electron 개발 모드
bun run electron:build     # Electron 패키징
bun run cli:dev            # 소스에서 CLI 실행
bun run cli:compile        # CLI를 dist로 컴파일

기여하기

기여를 환영합니다! 아키텍처 세부 정보와 코드 스타일은 CLAUDE.md를 참고하세요.

포크 후 클론
버전 동기화 설정: git config core.hooksPath .githooks
브랜치 생성: git checkout -b feat/my-feature
검사 실행: npx tsc --noEmit && bun --bun run test
Conventional Commits 형식으로 커밋: feat(canvas): add rotation snapping
main 브랜치에 PR 생성

로드맵

CSS 동기화가 있는 디자인 변수 & 토큰
컴포넌트 시스템 (인스턴스 & 오버라이드)
오케스트레이터를 통한 AI 디자인 생성
계층적 디자인 워크플로가 포함된 MCP 서버 통합
멀티 페이지 지원
Figma .fig 가져오기
불리언 연산 (합치기, 빼기, 교차)
멀티 모델 역량 프로파일
재사용 가능한 패키지를 포함한 모노레포 구조 변경
CLI 도구 (op) 터미널 제어
내장 AI 에이전트 SDK (멀티 제공자 지원)
i18n — 15개 언어
공동 편집
플러그인 시스템

기여자

커뮤니티

Discord에 참여하기 — 질문하기, 디자인 공유, 기능 제안.

18 KiB

Raw Blame History

OpenPencil

OpenPencil을 선택하는 이유

🎨 프롬프트 → 캔버스

🤖 동시 에이전트 팀

🧠 멀티 모델 인텔리전스

🔌 MCP 서버

📦 디자인-애즈-코드

🖥️ 어디서든 실행

⌨️ CLI — `op`

🎯 멀티 플랫폼 코드 내보내기

빠른 시작

Docker

AI 네이티브 디자인

CLI — `op`

기능

기술 스택

프로젝트 구조

키보드 단축키

스크립트

기여하기

로드맵

기여자

커뮤니티

Star History

라이선스

18 KiB Raw Blame History

OpenPencil

OpenPencil을 선택하는 이유

🎨 프롬프트 → 캔버스

🤖 동시 에이전트 팀

🧠 멀티 모델 인텔리전스

🔌 MCP 서버

📦 디자인-애즈-코드

🖥️ 어디서든 실행

⌨️ CLI — op

🎯 멀티 플랫폼 코드 내보내기

빠른 시작

Docker

AI 네이티브 디자인

CLI — op

기능

기술 스택

프로젝트 구조

키보드 단축키

스크립트

기여하기

로드맵

기여자

커뮤니티

Star History

라이선스

18 KiB

Raw Blame History

⌨️ CLI — `op`

CLI — `op`