chore: update version to 1.0.2 and enhance documentation (#60)

Author: zhangmingemma

README.md

@@ -54,18 +54,19 @@ https://github.com/user-attachments/assets/bd0c3f18-e98a-4050-bf22-46b198fadac2
 
 CodeRio can be seamlessly integrated into Cursor as a Skill. Simply input a prompt like **"Create a React project and restore this design with high fidelity,"** along with your output directory, Figma URL([Design Link](https://www.figma.com/design/c0UBII8lURfxZIY8W6tSDR/Top-16-Websites-of-2024---Awwwards--Community-?node-id=30-8264&t=FB3Hohq2nsH7ZFts-4)), and Token. The Agent will guide you step-by-step through the page generation process. For Landing Pages, it achieves **high-fidelity restoration**, accurately reproducing images and styles. It also automatically encapsulates reusable components (such as cards) and strictly adheres to **frontend development best practices**.
 
-
 https://github.com/user-attachments/assets/43817e97-ffd2-40e3-9d33-78ee55b2ec2d
 
 ## 🚀 Quick Start
 
 ### Option 1: CLI (Recommended 👍🏻)
+
 Best for one-click generation.
 
 #### 1. Prerequisites
 
 - Node.js >= 18.0.0 (< 25.0.0)
 - [Figma Personal Access Token](https://www.figma.com/developers/api#access-tokens)
+- **Figma Link**: Select a Frame or Component in Figma, right-click, and choose **Copy link to selection** ([Reference](docs/figma-link.jpg)).
 - LLM API Key ([Anthropic](https://console.anthropic.com/) | [OpenAI](https://platform.openai.com/) | [Google](https://aistudio.google.com/))
 
 #### 2. Installation
@@ -78,35 +79,33 @@ npm install -g coderio
 pnpm add -g coderio
 ```
 
-> **Note for pnpm v9+ users**: If you see a warning about "Ignored build scripts", run:
+> **Note for pnpm v9+ users**: If you see a warning about "Ignored build scripts", run: `pnpm approve-builds` to allow native dependencies (better-sqlite3) to compile properly.
+>
+> **Note**: Validation features (e.g., `d2c --mode full`) require optional dependencies `playwright` and `sharp`. They are not bundled with coderio by default to keep installation lightweight. Please install them globally beforehand for smoother execution:
 >
 > ```bash
-> pnpm approve-builds
+> npm install -g playwright sharp
+> npx playwright install chromium
 > ```
->
-> This allows native dependencies (better-sqlite3) to compile properly.
->
-> **Note**: `playwright` and `sharp` are required only for validation features. They will be automatically installed when you first run a command that needs them (like `d2c --mode full`).
 
 #### 3. Configuration
 
-Create `~/.coderio/config.yaml`:
+> **Important**: Requires a **multimodal (vision)** model (Recommended: `gemini-3-pro-preview`).
 
-```bash
-mkdir -p ~/.coderio
-cat > ~/.coderio/config.yaml << 'EOF'
+Create config file at `~/.coderio/config.yaml` (Windows: `%USERPROFILE%\.coderio\config.yaml`):
+
+```yaml
 model:
-  provider: openai          # anthropic | openai | google
-  model: gemini-3-pro-preview
-  baseUrl: https://api.anthropic.com
-  apiKey: your-api-key-here
+    provider: openai # anthropic | openai | google
+    model: gemini-3-pro-preview
+    baseUrl: https://api.anthropic.com
+    apiKey: your-api-key-here
 
 figma:
-  token: your-figma-token-here
+    token: your-figma-token-here
 
 debug:
-  enabled: false
-EOF
+    enabled: false # set 'true', if you want to save model and request information
 ```
 
 #### 4. Usage
@@ -136,10 +135,7 @@ pnpm dev
 
 #### 6. View Validation Report
 
-```bash
-# Open validation report in browser
-open coderio/<design-name_node-id>/process/validation/index.html
-```
+report path: coderio/<design-name_node-id>/process/validation/index.html
 
 #### 📖 All Commands
 
@@ -152,21 +148,22 @@ open coderio/<design-name_node-id>/process/validation/index.html
 | `images`          | -     | Download and process Figma assets                   |
 
 ### Option 2: Skill (Portable Embedded Workflow)
+
 Best for control and precision using AI Agents.
 
 **Prerequisites**:
 Copy the Skill file to your Cursor configuration directory:
-```bash
-mkdir -p ~/.cursor/skills/design-to-code
-cp docs/skills/SKILL.md ~/.cursor/skills/design-to-code/SKILL.md
-```
+
+Copy `skills\design-to-code` folder to `~\.cursor\skills` (Windows: `%USERPROFILE%\.cursor\skills`)
 
 **Using in Cursor**:
-1. Open Cursor Chat (`Cmd` + `L`).
+
+1. Open Cursor Chat.
 2. Type: **"Use design-to-code skill to convert this design: [Your Figma URL]"**
 3. The Agent will guide you step-by-step through protocol extraction and code generation.
 
 **Using in Claude Code**:
+
 1. Start Claude Code.
 2. Type: **"Read docs/skills/SKILL.md and perform design conversion: [Your Figma URL]"**
 

README_zh-CN.md

@@ -53,18 +53,19 @@ https://github.com/user-attachments/assets/bd0c3f18-e98a-4050-bf22-46b198fadac2
 
 CodeRio 支持作为 Skill 集成到 Cursor 中使用。您只需在对话框中输入 **“请帮我创建一个 React 工程，高保真还原设计稿”**，并提供输出目录、设计稿链接([设计稿链接](https://www.figma.com/design/c0UBII8lURfxZIY8W6tSDR/Top-16-Websites-of-2024---Awwwards--Community-?node-id=30-8264&t=FB3Hohq2nsH7ZFts-4))及 Figma Token，Agent 即可引导您逐步完成网页生成。对于落地页（Landing Page）类页面，CodeRio 能达到 **高保真还原** 标准，精确还原图片与样式，并自动对卡片等组件进行 **复用封装**，生成的代码完全符合 **前端开发规范**。
 
-
 https://github.com/user-attachments/assets/43817e97-ffd2-40e3-9d33-78ee55b2ec2d
 
 ## 🚀 快速开始
 
 ### 方式 1：命令行 CLI（推荐 👍🏻）
+
 适用于一键快速生成。
 
 #### 1. 前置要求
 
 - Node.js >= 18.0.0 (< 25.0.0)
 - [Figma 个人访问令牌](https://www.figma.com/developers/api#access-tokens)
+- **Figma 链接**：在 Figma 中选中 Frame 或 Component，右键选择 **Copy link to selection** ([参考图片](docs/figma-link.jpg))。
 - LLM API 密钥（[Anthropic](https://console.anthropic.com/) | [OpenAI](https://platform.openai.com/) | [Google](https://aistudio.google.com/)）
 
 #### 2. 安装
@@ -76,36 +77,38 @@ npm install -g coderio
 # 或使用 pnpm
 pnpm add -g coderio
 ```
-> **pnpm v9+ 用户注意**：如果看到 "Ignored build scripts" 警告，请运行：
+
+> **pnpm v9+ 用户注意**：如果看到 "Ignored build scripts" 警告，请运行：`pnpm approve-builds`，允许原生依赖（better-sqlite3）正确编译。
+>
+> **注意**：验证功能（如 `d2c --mode full`）依赖可选依赖 `playwright` 和 `sharp`。为了保持安装轻量，coderio 默认不内置它们。建议您提前全局安装，以确保运行更加顺畅：
+>
 > ```bash
-> pnpm approve-builds
+> npm install -g playwright sharp
+> npx playwright install chromium
 > ```
-> 这将允许原生依赖（better-sqlite3）正确编译。
->
-> **注意**：`playwright` 和 `sharp` 仅在验证功能中需要。当您运行需要它们的命令（如 `d2c --mode full`）时，它们将被自动安装。
 
 #### 3. 配置
 
-创建 `~/.coderio/config.yaml`：
+> **重要提示**：本工具需要模型具备 **多模态（视觉）能力**（推荐 `gemini-3-pro-preview`）。
 
-```bash
-mkdir -p ~/.coderio
-cat > ~/.coderio/config.yaml << 'EOF'
+创建配置文件 `~/.coderio/config.yaml`（Windows：`%USERPROFILE%\.coderio\config.yaml`）：
+
+```yaml
 model:
-  provider: openai          # anthropic | openai | google
-  model: gemini-3-pro-preview
-  baseUrl: https://api.anthropic.com
-  apiKey: your-api-key-here
+    provider: openai # anthropic | openai | google
+    model: gemini-3-pro-preview
+    baseUrl: https://api.anthropic.com
+    apiKey: your-api-key-here
 
 figma:
-  token: your-figma-token-here
+    token: your-figma-token-here
 
 debug:
-  enabled: false
-EOF
+    enabled: false # 如果需要保留请求和模型回复，可以设置为 true
 ```
 
 #### 4. 使用
+
 ```bash
 # 将 Figma 设计转换为代码（默认模式：仅代码）
 coderio d2c -s 'https://www.figma.com/design/your-file-id/...'
@@ -114,7 +117,6 @@ coderio d2c -s 'https://www.figma.com/design/your-file-id/...'
 coderio d2c -s 'https://www.figma.com/design/your-file-id/...' -m full
 ```
 
-
 #### 5. 运行项目
 
 ```bash
@@ -132,10 +134,7 @@ pnpm dev
 
 #### 6. 查看验证报告
 
-```bash
-# 在浏览器中打开验证报告
-open coderio/<设计文件名-页面节点编号>/process/validation/index.html
-```
+验证报告目录：`coderio/<设计文件名-页面节点编号>/process/validation/index.html`
 
 #### 📖 全部命令
 
@@ -147,27 +146,24 @@ open coderio/<设计文件名-页面节点编号>/process/validation/index.html
 | `validate`        | `val` | 对生成的代码运行验证                 |
 | `images`          | -     | 下载和处理 Figma 资源                |
 
-
 ### 方式 2：Skill（便携式嵌入工作流）
+
 适用于需要 AI 辅助和更精准控制的场景。
 
 **前置准备**：
-将 Skill 文件拷贝到 Cursor 配置目录：
-```bash
-mkdir -p ~/.cursor/skills/design-to-code
-cp docs/skills/SKILL.md ~/.cursor/skills/design-to-code/SKILL.md
-```
+将 `skills\design-to-code` 文件夹拷贝到 `~\.cursor\skills`(windows 为`%USERPROFILE%\.cursor\skills`) 目录下，
 
 **Cursor 中使用**：
-1. 打开 Cursor Chat (`Cmd` + `L`)。
+
+1. 打开 Cursor Chat
 2. 输入：**"使用 design-to-code skill 帮我转换这个设计：[你的 Figma 链接]"**
 3. 智能体将引导你分步完成协议提取和代码生成。
 
 **Claude Code 中使用**：
+
 1. 启动 Claude Code。
 2. 输入：**"阅读 docs/skills/SKILL.md 并执行设计转换任务：[你的 Figma 链接]"**
 
-
 ## 💎 核心特性
 
 ### 1. 智能设计协议生成

docs/figma-link.jpg

@@ -1,6 +1,6 @@
 {
     "name": "coderio",
-    "version": "1.0.0",
+    "version": "1.0.2",
     "description": "A modern CLI development tool built with TypeScript",
     "type": "module",
     "bin": {

package.json

@@ -7,36 +7,32 @@ import { runValidation } from './nodes/validation';
 import { parseFigmaUrl } from './utils/url-parser';
 import { workspaceManager } from './utils/workspace';
 import { generateCode } from './nodes/code';
-import { initializeSqliteSaver, promptCheckpointChoice } from './utils/checkpoint';
+import { initializeSqliteSaver, promptCheckpointChoice, clearThreadCheckpoint } from './utils/checkpoint';
 import { logger } from './utils/logger';
-import { callModel } from './utils/call-model';
 
 export async function design2code(url: string, mode?: ValidationMode): Promise<void> {
     const urlInfo = parseFigmaUrl(url);
     const threadId = urlInfo.projectName!;
     const workspace = workspaceManager.initWorkspace(threadId);
 
     // Initialize SqliteSaver with the database path
-    let checkpointer = initializeSqliteSaver(workspace.db);
+    const checkpointer = initializeSqliteSaver(workspace.db);
     const resume = await promptCheckpointChoice(checkpointer, threadId);
 
     logger.printInfoLog(`Starting design-to-code process for: ${urlInfo.projectName}`);
 
     // If not resuming, delete workspace and reinitialize checkpointer
     if (resume !== true) {
-        workspaceManager.deleteWorkspace(workspace);
+        // Exclude checkpoint directory to avoid EBUSY error on Windows (SQLite lock)
+        workspaceManager.deleteWorkspace(workspace, ['checkpoint']);
         logger.printInfoLog('Starting fresh...');
-        // Reinitialize checkpointer after deleting workspace
-        checkpointer = initializeSqliteSaver(workspace.db);
+
+        // Clear existing checkpoints for this thread instead of deleting the file
+        await clearThreadCheckpoint(checkpointer, threadId);
     } else {
         logger.printInfoLog('Resuming from cache...');
     }
 
-    await callModel({
-        question: '请介绍你自己，你是什么模型',
-        streaming: false,
-    });
-
     // Compile graph with checkpointer (after potential reinitialization)
     const graph = new StateGraph(GraphStateAnnotation)
         .addNode(GraphNode.INITIAL, initialProject)

src/graph.ts

@@ -1,5 +1,6 @@
 import type { FigmaFrameInfo, Protocol, FrameData } from '../../../types';
 import type { SimplifiedFigmaNode, ExtendedFrameStructNode, ParsedDataListResponse } from './types';
+import path from 'node:path';
 import { toKebabCase } from '../../../utils/naming';
 import { extractJSON } from '../../../utils/parser';
 import { callModel } from '../../../utils/call-model';
@@ -237,12 +238,9 @@ export function postProcessStructure(structure?: Protocol | Protocol[] | null, f
         return;
     }
 
-    // Utility to join path segments and normalize slashes
+    // Utility to join alias path segments (always POSIX '/')
     const joinSegments = (...segments: (string | undefined)[]): string =>
-        segments
-            .filter((segment): segment is string => Boolean(segment && segment.length))
-            .join('/')
-            .replace(/\/{2,}/g, '/');
+        path.posix.join(...segments.filter((segment): segment is string => Boolean(segment && segment.length)));
 
     const nodes = Array.isArray(structure) ? structure : [structure];
     let rootPath = '@/components';

src/nodes/process/structure/utils.ts

@@ -197,7 +197,7 @@ function saveIterationAndProcessedJson(
 
 export async function validationLoop(params: ValidationLoopParams): Promise<ValidationLoopResult> {
     // Ensure dependencies are installed before starting validation loop
-    await ensureValidationDependencies();
+    ensureValidationDependencies();
 
     const { protocol, figmaThumbnailUrl, outputDir, workspace } = params;
 

src/nodes/validation/core/validation-loop.ts

@@ -325,7 +325,15 @@ export const createDownloadTask = async (image: ImageNode, imageDir?: string): P
 
     try {
         const localPath = await downloadImage(image.url, filename, imageDir);
-        const aliasPath = `@/${localPath.split('src/')?.[1] || ''}`;
+        const normalizedImageDir = imageDir ? path.normalize(imageDir) : '';
+        const dirParts = normalizedImageDir.split(path.sep).filter(Boolean);
+        const srcIndex = dirParts.lastIndexOf('src');
+        const srcDir =
+            srcIndex >= 0 ? (normalizedImageDir.startsWith(path.sep) ? path.sep : '') + path.join(...dirParts.slice(0, srcIndex + 1)) : '';
+
+        const relativeFromSrc = srcDir ? path.relative(srcDir, localPath) : '';
+        const normalizedRelative = relativeFromSrc.split(path.sep).join('/');
+        const aliasPath = `@/${normalizedRelative}`;
 
         return {
             id: image.id,

src/tools/figma-tool/images.ts

@@ -65,11 +65,14 @@ class FigmaTool {
 
         const document = await fetchFigmaNode(fileId, nodeId, token);
         if (!document || !document?.children?.length) {
-            return undefined;
+            throw new Error('Failed to fetch Figma document');
         }
 
         const images = await fetchFigmaImages(fileId, nodeId, token);
         const thumbnail = images?.[nodeId] || '';
+        if (!thumbnail) {
+            throw new Error('Failed to fetch Figma document thumbnail');
+        }
         document.thumbnailUrl = thumbnail;
 
         const cleanedDocument = cleanFigma(document);