vite-plugin-prism-design 0.1.0

package/README.md

@@ -0,0 +1,238 @@
+# vite-plugin-prism-design
+
+PrismDesign 的 Vite 插件 —— 一行配置，为你的 React / Vue / Svelte 项目接入 AI 可视化编辑能力。
+
+## 功能
+
+- 开发模式自动注入 PrismDesign Widget（悬浮聊天面板）
+- 自动启动 AI Agent 服务，无需手动管理
+- Agent 端口被占用时自动递增
+- 生产构建自动跳过，零影响
+- 支持 Claude API、GLM API 等多种 AI 后端
+
+## 安装
+
+```bash
+pnpm add -D vite-plugin-prism-design
+```
+
+## 快速开始
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import prismDesign from 'vite-plugin-prism-design'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    prismDesign()
+  ]
+})
+```
+
+启动 `pnpm dev` 后，页面右下角会出现 PrismDesign 悬浮按钮。点击展开聊天面板，描述你想要的 UI 修改，AI 会直接修改源码并自动刷新页面。
+
+## 配置选项
+
+```ts
+prismDesign({
+  // ── Agent 配置 ──
+
+  // API Key（传递给 Agent 作为 ANTHROPIC_API_KEY）
+  // 也可以通过项目根目录 .env 文件配置
+  apiKey: 'sk-ant-...',
+
+  // API Base URL（可选，用于 LiteLLM 代理等场景）
+  baseUrl: 'https://your-proxy.com/v1',
+
+  // AI 模型名称（可选，默认 claude-sonnet-4-20250514）
+  model: 'claude-sonnet-4-20250514',
+
+  // Agent 类型（默认 "claude"）
+  agentType: 'claude',  // 'claude' | 'glm'
+
+  // Agent 服务端口（默认 9527，被占用时自动递增）
+  agentPort: 9527,
+
+  // 是否自动启动 Agent（默认 true）
+  // 设为 false 则需要手动运行 Agent
+  agentAutoStart: true,
+
+  // 直接指定已运行的 Agent URL（跳过自动启动）
+  // 适用于 Agent 在远程服务器或 Docker 容器中运行的场景
+  agentUrl: 'http://localhost:9527',
+
+  // ── Widget 配置 ──
+
+  // 悬浮按钮位置（默认 "bottom-right"）
+  position: 'bottom-right',  // 'bottom-right' | 'bottom-left'
+
+  // 语言（默认根据浏览器语言自动检测）
+  locale: 'zh',  // 'zh' | 'en'
+})
+```
+
+## 使用场景
+
+### 基础用法（使用 .env 配置 API Key）
+
+最简单的方式，API Key 放在项目 `.env` 文件中：
+
+```bash
+# .env
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+```ts
+// vite.config.ts
+prismDesign()
+```
+
+Agent 启动时会自动读取 `.env` 文件中的环境变量。
+
+### 使用 LiteLLM 代理
+
+```ts
+prismDesign({
+  apiKey: 'sk-your-key',
+  baseUrl: 'https://your-litellm-proxy.com/v1',
+  model: 'gpt-4o',
+})
+```
+
+### 使用智谱 GLM
+
+```ts
+prismDesign({
+  agentType: 'glm',
+  apiKey: 'your-zhipu-api-key',
+})
+```
+
+### 连接远程 / Docker Agent
+
+如果 Agent 运行在远程服务器或 PrismDesign Platform 容器中：
+
+```ts
+prismDesign({
+  agentAutoStart: false,
+  agentUrl: 'https://your-platform.com/api/workspaces/abc123/agent',
+})
+```
+
+### 手动管理 Agent
+
+如果你想自己启动 Agent 进程：
+
+```ts
+prismDesign({
+  agentAutoStart: false,
+})
+```
+
+然后手动运行：
+
+```bash
+npx prism-design-agent start --port 9527
+```
+
+Widget 会显示连接表单，输入 Agent 地址后连接。
+
+## Widget 功能
+
+### 聊天
+
+在聊天面板中描述你想要的 UI 修改，例如：
+
+- "把标题颜色改成蓝色"
+- "导航栏增加一个用户头像"
+- "这个按钮改成圆角样式"
+
+AI 会直接修改源码，修改完成后页面自动刷新。
+
+### 评论标注
+
+点击聊天输入框左侧的评论按钮，进入元素选择模式：
+
+1. 鼠标移动高亮页面元素
+2. 点击选中元素，弹出评论输入框
+3. 输入评论后确认，评论会作为上下文附在下一条消息中
+4. 支持重选元素（在评论框打开时点击其他元素）
+
+评论功能会自动检测 React / Vue 组件信息和源文件位置，帮助 AI 精准定位代码。
+
+### 移动端适配
+
+在移动设备上（viewport < 640px），面板以底部弹窗形式展示，支持滑入/滑出动画。
+
+## 工作原理
+
+```
+┌─────────────────────────────────────────────┐
+│  Vite Dev Server                            │
+│  ┌───────────────────────────────────────┐  │
+│  │  vite-plugin                          │  │
+│  │  ├─ transformIndexHtml: 注入 widget   │  │
+│  │  ├─ configureServer: 启动 agent       │  │
+│  │  └─ middleware: 服务 widget.js        │  │
+│  └───────────────────────────────────────┘  │
+│                    ↕ spawn                   │
+│  ┌───────────────────────────────────────┐  │
+│  │  Agent Server (port 9527)             │  │
+│  │  ├─ POST /api/chat → Claude SDK      │  │
+│  │  ├─ WebSocket /ws → 实时进度          │  │
+│  │  └─ 读取项目 CLAUDE.md               │  │
+│  └───────────────────────────────────────┘  │
+└─────────────────────────────────────────────┘
+         ↕ HTTP + WebSocket
+┌─────────────────────────────────────────────┐
+│  Browser                                    │
+│  ┌───────────────────────────────────────┐  │
+│  │  Widget (Shadow DOM)                  │  │
+│  │  ├─ FAB 悬浮按钮                      │  │
+│  │  ├─ 聊天面板                          │  │
+│  │  └─ 评论标注                          │  │
+│  └───────────────────────────────────────┘  │
+└─────────────────────────────────────────────┘
+```
+
+## CLAUDE.md
+
+在项目根目录创建 `CLAUDE.md` 文件可以给 AI 提供项目上下文，例如：
+
+```markdown
+# CLAUDE.md
+
+## 项目信息
+- 框架：React 19 + TypeScript
+- 样式：Tailwind CSS v4
+- UI 组件库：shadcn/ui
+
+## 编码规范
+- 使用函数组件 + Hooks
+- 样式使用 Tailwind 工具类
+- 组件放在 src/components/ 目录
+
+## 工作规则
+- 只做 UI 层面的修改
+- 优先使用已有的组件库组件
+```
+
+Agent 启动时会自动读取这个文件。
+
+## 注意事项
+
+- 仅在 `vite dev`（开发模式）下生效，`vite build` 时自动跳过
+- Agent 进程随 Vite Dev Server 一起启动和关闭
+- Widget 使用 Shadow DOM 隔离样式，不会影响你的页面
+- API Key 建议放在 `.env` 文件中，不要提交到代码仓库
+
+## 兼容性
+
+- Vite 5+
+- React / Vue / Svelte / 任何 Vite 支持的框架
+- 现代浏览器（Chrome, Firefox, Safari, Edge）
+
+> **Next.js 用户**：Next.js 使用 Webpack/Turbopack，不支持 Vite 插件。请关注后续的 `@prism-design/next-plugin`。

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { Plugin } from 'vite';
+
+interface PrismDesignOptions {
+    /** Agent server port (default: 9527, auto-increments if occupied) */
+    agentPort?: number;
+    /** Agent type: "claude" | "glm" (default: "claude") */
+    agentType?: "claude" | "glm";
+    /** Disable auto-starting agent (if you run it manually) */
+    agentAutoStart?: boolean;
+    /** Agent URL override (skips auto-start, connects to existing agent) */
+    agentUrl?: string;
+    /** API Key for the AI model (passed to agent as ANTHROPIC_API_KEY) */
+    apiKey?: string;
+    /** API Base URL (passed to agent as ANTHROPIC_BASE_URL, e.g. LiteLLM proxy) */
+    baseUrl?: string;
+    /** AI model name (passed to agent as ANTHROPIC_MODEL, e.g. "claude-sonnet-4-20250514") */
+    model?: string;
+    /** Widget position (default: "bottom-right") */
+    position?: "bottom-right" | "bottom-left";
+    /** Widget locale override */
+    locale?: "zh" | "en";
+}
+declare function prismDesign(options?: PrismDesignOptions): Plugin;
+
+export { type PrismDesignOptions, prismDesign as default };

package/dist/index.js

@@ -0,0 +1,159 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/index.ts
+import { spawn } from "child_process";
+import path from "path";
+import fs from "fs";
+function findWidgetScript() {
+  try {
+    const widgetPkg = __require.resolve("prism-design-widget/package.json");
+    const widgetDir = path.dirname(widgetPkg);
+    const iifeFile = path.join(widgetDir, "dist", "prism-design-widget.iife.js");
+    if (fs.existsSync(iifeFile)) return iifeFile;
+  } catch {
+  }
+  try {
+    const thisDir = path.dirname(new URL(import.meta.url).pathname);
+    const candidate = path.resolve(thisDir, "../../widget/dist/prism-design-widget.iife.js");
+    if (fs.existsSync(candidate)) return candidate;
+  } catch {
+  }
+  return null;
+}
+function findAgentCli() {
+  const candidates = [
+    // Monorepo sibling
+    path.resolve(new URL(import.meta.url).pathname, "../../../agent/dist/cli.js"),
+    // npm global / local
+    "prism-design-agent"
+  ];
+  for (const c of candidates) {
+    try {
+      if (path.isAbsolute(c) && fs.existsSync(c)) return c;
+    } catch {
+    }
+  }
+  return null;
+}
+function prismDesign(options = {}) {
+  const {
+    agentPort: preferredPort = 9527,
+    agentType = "claude",
+    agentAutoStart = true,
+    agentUrl: agentUrlOverride,
+    apiKey,
+    baseUrl,
+    model,
+    position = "bottom-right",
+    locale
+  } = options;
+  let agentProcess = null;
+  let agentUrl = agentUrlOverride || "";
+  let widgetJs = "";
+  let config;
+  return {
+    name: "prism-design",
+    apply: "serve",
+    // Dev only
+    configResolved(resolvedConfig) {
+      config = resolvedConfig;
+    },
+    async configureServer(server) {
+      const widgetPath = findWidgetScript();
+      if (widgetPath) {
+        widgetJs = fs.readFileSync(widgetPath, "utf-8");
+      } else {
+        config.logger.warn("[PrismDesign] Widget script not found. Run: pnpm build:widget");
+        return;
+      }
+      server.middlewares.use("/__prism__/widget.js", (_req, res) => {
+        res.setHeader("Content-Type", "application/javascript");
+        res.setHeader("Cache-Control", "no-store");
+        res.end(widgetJs);
+      });
+      if (!agentUrlOverride && agentAutoStart) {
+        const agentCli = findAgentCli();
+        if (agentCli) {
+          const projectRoot = config.root || process.cwd();
+          const agentEnv = { ...process.env };
+          if (apiKey) agentEnv.ANTHROPIC_API_KEY = apiKey;
+          if (baseUrl) agentEnv.ANTHROPIC_BASE_URL = baseUrl;
+          if (model) agentEnv.ANTHROPIC_MODEL = model;
+          agentProcess = spawn("node", [agentCli, "start", "--port", String(preferredPort), "--project", projectRoot, "--agent-type", agentType], {
+            stdio: ["ignore", "pipe", "pipe"],
+            env: agentEnv
+          });
+          const portPromise = new Promise((resolve) => {
+            const timeout = setTimeout(() => resolve(preferredPort), 15e3);
+            agentProcess.stdout?.on("data", (data) => {
+              const text = data.toString();
+              const match = text.match(/__PRISM_AGENT_PORT__=(\d+)/);
+              if (match) {
+                clearTimeout(timeout);
+                resolve(parseInt(match[1], 10));
+              }
+              for (const line of text.split("\n")) {
+                const trimmed = line.trim();
+                if (trimmed && !trimmed.startsWith("__PRISM_AGENT_PORT__")) {
+                  config.logger.info(`[PrismDesign Agent] ${trimmed}`);
+                }
+              }
+            });
+          });
+          agentProcess.stderr?.on("data", (data) => {
+            const msg = data.toString().trim();
+            if (msg) config.logger.warn(`[PrismDesign Agent] ${msg}`);
+          });
+          agentProcess.on("exit", (code) => {
+            if (code !== null && code !== 0) {
+              config.logger.error(`[PrismDesign] Agent exited with code ${code}`);
+            }
+            agentProcess = null;
+          });
+          const actualPort = await portPromise;
+          agentUrl = `http://localhost:${actualPort}`;
+          config.logger.info(`[PrismDesign] Agent ready at ${agentUrl}`);
+        } else {
+          config.logger.warn("[PrismDesign] Agent CLI not found. Install prism-design-agent or run agent manually.");
+          config.logger.info("[PrismDesign] Widget will show connection form for manual URL input.");
+        }
+      } else if (agentUrlOverride) {
+        agentUrl = agentUrlOverride;
+        config.logger.info(`[PrismDesign] Using agent at ${agentUrl}`);
+      }
+      server.httpServer?.on("close", () => {
+        if (agentProcess) {
+          agentProcess.kill("SIGTERM");
+          agentProcess = null;
+        }
+      });
+    },
+    transformIndexHtml() {
+      const initOptions = {};
+      if (agentUrl) initOptions.agentUrl = agentUrl;
+      if (position !== "bottom-right") initOptions.position = position;
+      if (locale) initOptions.locale = locale;
+      const optionsJson = JSON.stringify(initOptions);
+      return [
+        {
+          tag: "script",
+          attrs: { src: "/__prism__/widget.js" },
+          injectTo: "body"
+        },
+        {
+          tag: "script",
+          children: `PrismDesignWidget.init(${optionsJson});`,
+          injectTo: "body"
+        }
+      ];
+    }
+  };
+}
+export {
+  prismDesign as default
+};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "vite-plugin-prism-design",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "dependencies": {
+    "prism-design-widget": "workspace:*"
+  },
+  "peerDependencies": {
+    "vite": ">=5.0.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vite": "^6.0.0"
+  }
+}