@tarot-ai/pixel 0.0.2 → 0.0.4

package/README.md

@@ -1,27 +1,100 @@
-# @tarot-ai/pixel
+# Tarot Pixel
 
-`@tarot-ai/pixel` 是 Tarot Pixel 的 MCP Runtime，向兼容的 MCP Client
-提供本地设计稿读取、分析、渲染和资源生成能力。
+[简体中文](#简体中文) · [English](#english)
 
-通常不需要单独启动该包，Tarot Pixel 的 Qoder 插件会固定 Runtime
-版本并自动建立 stdio MCP 连接。
+Tarot Pixel connects MasterGo, Figma, and Sketch designs with Coding Agents through a local
+MCP runtime and structured visual context.
 
-## 运行要求
+Tarot Pixel 通过本地 MCP Runtime 和结构化视觉上下文，把 MasterGo、Figma、Sketch
+设计稿连接到 Coding Agent。
+
+## 简体中文
+
+### 产品简介
+
+Tarot Pixel 是设计稿与 Coding Agent 之间的桥梁。设计工具插件负责读取并同步设计稿，
+`@tarot-ai/pixel` 在本机保存、分析和渲染设计数据，再通过 MCP 向 Qoder 等兼容客户端
+按需提供布局、样式、文本、资源和视觉预览。
+
+它不会替 Agent 编写业务代码，而是提供持续在线、可精确查询的视觉上下文，让 Agent
+能够像查字典一样理解设计稿。
+
+### 主要能力
+
+- 读取 MasterGo、Figma 和 Sketch 设计稿。
+- 查询页面、模块、节点、文本、尺寸、间距、布局和样式。
+- 为实现任务生成分层的 Design-to-Code 上下文。
+- 生成节点截图、组合图片和本地字体子集。
+- 通过本地 View 检查设计结构与导出资源。
+- 通过 MCP 按需读取信息，避免一次性把完整设计稿塞入上下文。
+
+### 工作方式
+
+```text
+MasterGo / Figma / Sketch 插件
+              ↓ 同步设计数据
+     @tarot-ai/pixel 本地 Runtime
+              ↓ MCP
+        Qoder / Coding Agent
+```
+
+设计数据默认保存在用户本机。设计工具导入只使用受限的本地接口，Coding Agent 的读取、
+分析和渲染能力只通过 MCP 暴露。
+
+### 快速开始
+
+1. 在 Qoder 中安装并启用 Tarot Pixel，或按下文说明手动启动本地 Runtime。
+2. 安装 [Figma 插件](https://www.figma.com/community/plugin/1635645029043726171) 或
+   [Sketch 插件](https://unpkg.com/@tarot-ai/tarot-pixel-sketch-release@latest/Tarot-Pixel.sketchplugin.zip)。
+3. 在设计工具中选择要导出的 Frame、画板或图层，运行 Tarot Pixel 并点击“同步设计稿”。
+4. 将同步后打开的本地链接、`designId`、模块或节点信息提供给 Agent。
+5. 描述需要实现、检查或还原的页面与组件。
+
+### 设计工具插件
+
+#### Figma
+
+- [在 Figma Community 中打开 Tarot Pixel](https://www.figma.com/community/plugin/1635645029043726171)
+- 也可以在 Figma Community 或 Figma 的插件面板中搜索 `Tarot Pixel`。
+
+打开目标设计文件，选择要同步的 Frame 或图层，运行 Tarot Pixel，然后点击
+“同步设计稿”。开始同步前，请确保 Qoder 中的 Tarot Pixel 已启用，或本地 Runtime 已启动。
+
+#### Sketch
+
+- 最低 Sketch 版本：`80.0`
+- [下载 Sketch 插件](https://unpkg.com/@tarot-ai/tarot-pixel-sketch-release@latest/Tarot-Pixel.sketchplugin.zip)
+
+下载 ZIP 并解压后，双击 `tarot-pixel.sketchplugin` 即可安装。插件会优先连接本机运行的
+Tarot Pixel。打开目标文档，选择要同步的画板或图层，运行 Tarot Pixel，然后点击
+“同步设计稿”。安装完成后，Sketch 会自动检查插件更新。组织云端能力可能需要额外的
+网络和账号权限。
+
+### 在 Qoder 中使用
+
+推荐在 Qoder 中安装并启用 Tarot Pixel 插件。Qoder 会使用固定版本的 Runtime，并自动
+建立 stdio MCP 连接，通常不需要手动启动本包。
+
+1. 在 Qoder 中启用 Tarot Pixel。
+2. 使用对应设计工具中的 Tarot Pixel 插件同步设计稿。
+3. 把设计稿链接、`designId`、模块或节点信息提供给 Agent。
+4. 描述需要实现、检查或还原的页面与组件。
+
+### 手动接入 MCP Client
+
+运行要求：
 
 - Node.js 20.19.0 或更高版本。
-- npm 需要具备读取 `@tarot-ai/pixel` 的权限。
+- npm 客户端能够访问 npm 公共仓库。
 - 截图和组合图片功能需要本机安装 Chrome、Chromium、Edge 或 Brave。
 
-## 手动启动
+启动 Runtime：
 
 ```bash
-npx --yes --package=@tarot-ai/pixel@0.0.2 -- tarot-pixel
+npx --yes --package=@tarot-ai/pixel@latest -- tarot-pixel
 ```
 
-该命令启动 stdio MCP Server。标准输出仅用于 MCP 协议消息，运行日志写入标准错误或
-本地日志文件。
-
-MCP Client 可以使用以下配置：
+MCP Client 配置示例：
 
 ```json
 {
@@ -29,21 +102,146 @@ MCP Client 可以使用以下配置：
     "tarot-pixel": {
       "type": "stdio",
       "command": "npx",
-      "args": ["--yes", "--package=@tarot-ai/pixel@0.0.2", "--", "tarot-pixel"]
+      "args": ["--yes", "--package=@tarot-ai/pixel@latest", "--", "tarot-pixel"]
     }
   }
 }
 ```
 
-生产环境应把示例版本替换为经过验证的精确版本，不建议直接使用 `latest`。
+生产环境建议固定经过验证的精确版本，不要直接依赖 `latest`。
 
-## 数据与隐私
+### 数据与隐私
 
-- Runtime 默认在当前用户的本地数据目录保存设计稿、资源和渲染结果。
-- 包内不包含 npm token、设计工具凭据或用户密钥。
+- 设计稿、资源和渲染结果默认保存在当前用户的本地数据目录。
+- 包内不包含 npm Token、设计工具凭据或用户密钥。
+- 完整 Server、View 与 MCP HTTP 只绑定本机回环地址。
 - 本地 URL、资源 URI、数据目录和临时渲染路径不应提交到业务仓库。
-- 生成的资源应复制到目标项目后再由业务代码引用。
+- 生成的资源应复制到目标项目的资源目录后再由业务代码引用。
 
-## 许可证
+### 许可证
 
 该包为专有软件，不授予开源许可。随包分发的第三方组件保留各自的许可证声明。
+
+## English
+
+### Overview
+
+Tarot Pixel is the bridge between design files and Coding Agents. Companion plugins read and
+sync designs from MasterGo, Figma, and Sketch. The local `@tarot-ai/pixel` runtime stores,
+analyzes, and renders that data, then exposes layout, styles, text, assets, and visual previews
+to compatible MCP clients such as Qoder.
+
+Tarot Pixel does not generate application code on behalf of the Agent. It provides clean,
+layered, continuously available visual context that an Agent can query on demand.
+
+### Highlights
+
+- Read designs from MasterGo, Figma, and Sketch.
+- Inspect pages, modules, nodes, text, dimensions, spacing, layout, and styles.
+- Generate layered Design-to-Code context for implementation tasks.
+- Render node screenshots, composite images, and local font subsets.
+- Inspect design structure and exported assets in a local View.
+- Query only the required context through MCP instead of loading an entire design at once.
+
+### How it works
+
+```text
+MasterGo / Figma / Sketch plugin
+               ↓ sync design data
+      @tarot-ai/pixel local runtime
+               ↓ MCP
+         Qoder / Coding Agent
+```
+
+Design data is stored locally by default. Design imports use a restricted local endpoint, while
+all read, analysis, and rendering capabilities for Coding Agents are exposed through MCP only.
+
+### Quick start
+
+1. Install and enable Tarot Pixel in Qoder, or start the local Runtime manually as described
+   below.
+2. Install the [Figma plugin](https://www.figma.com/community/plugin/1635645029043726171) or
+   [Sketch plugin](https://unpkg.com/@tarot-ai/tarot-pixel-sketch-release@latest/Tarot-Pixel.sketchplugin.zip).
+3. Select the artboards, frames, or layers to export, run Tarot Pixel, and click **Sync design**.
+4. Give the Agent the local link opened after synchronization, a `designId`, module, or node
+   reference.
+5. Describe the page or component you want to implement, inspect, or reproduce.
+
+### Design-tool plugins
+
+#### Figma
+
+- [Open Tarot Pixel in Figma Community](https://www.figma.com/community/plugin/1635645029043726171)
+- You can also search for `Tarot Pixel` in Figma Community or the Figma plugin panel.
+
+Open the target design file, select the frames or layers to sync, run Tarot Pixel, and click
+**Sync design**. Before syncing, make sure Tarot Pixel is enabled in Qoder or the local Runtime
+is running.
+
+#### Sketch
+
+- Minimum Sketch version: `80.0`
+- [Download the Sketch plugin](https://unpkg.com/@tarot-ai/tarot-pixel-sketch-release@latest/Tarot-Pixel.sketchplugin.zip)
+
+Download and extract the ZIP, then double-click `tarot-pixel.sketchplugin` to install it. The
+plugin connects to a local Tarot Pixel runtime first. Open the target document, select the
+artboards or layers to sync, run Tarot Pixel, and click **Sync design**. Sketch checks for plugin
+updates automatically after installation. Organization cloud features may require additional
+network access and account permissions.
+
+### Use with Qoder
+
+The recommended setup is to install and enable the Tarot Pixel plugin in Qoder. Qoder pins a
+verified Runtime version and opens the stdio MCP connection automatically, so you normally do
+not need to start this package yourself.
+
+1. Enable Tarot Pixel in Qoder.
+2. Sync a design with the corresponding Tarot Pixel design-tool plugin.
+3. Give the Agent a design link, `designId`, module, or node reference.
+4. Describe the page or component you want to implement, inspect, or reproduce.
+
+### Connect another MCP client
+
+Requirements:
+
+- Node.js 20.19.0 or later.
+- Access to the public npm registry.
+- Chrome, Chromium, Edge, or Brave for screenshot and composite-image features.
+
+Start the Runtime:
+
+```bash
+npx --yes --package=@tarot-ai/pixel@latest -- tarot-pixel
+```
+
+Example MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "tarot-pixel": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["--yes", "--package=@tarot-ai/pixel@latest", "--", "tarot-pixel"]
+    }
+  }
+}
+```
+
+Pin an exact, verified version in production instead of depending on `latest`.
+
+### Data and privacy
+
+- Designs, assets, and rendered output are stored in the current user's local data directory by
+  default.
+- The package contains no npm tokens, design-tool credentials, or user secrets.
+- The full Server, View, and MCP HTTP endpoints bind to the local loopback interface only.
+- Do not commit local URLs, resource URIs, data directories, or temporary render paths to an
+  application repository.
+- Copy generated assets into a directory owned by the target project before referencing them in
+  application code.
+
+### License
+
+This package is proprietary and does not grant an open-source license. Third-party components
+retain their respective license notices.