claude-dev-server 1.1.3 → 1.2.0

package/README.md

@@ -7,13 +7,14 @@
 ## 功能特性
 
 - **通用支持** - 适用于 Vite、Next.js、Webpack 或任何 dev server
+- **分屏布局** - 左侧 Claude Code 终端，右侧开发服务器，可拖动分隔线调整宽度
 - **ttyd 终端** - 使用 ttyd 提供真正的 PTY 终端体验，完整支持 ANSI 转义序列、颜色、光标控制
 - **Claude Code 集成** - 通过 WebSocket 与后台 Claude Code 进程通信，实时 AI 辅助开发
 - **元素检查器** - 点击页面元素，自动定位到对应源代码位置，并发送到 Claude Code 终端
 - **智能提示格式** - 自动格式化选中元素为 `@filename:line <selector> "text content"` 格式
+- **Next.js 路由支持** - 使用真实 iframe src 解决 Next.js 路由问题
 - **无需安装** - 直接使用 `npx` 运行，自动检测项目类型
-- **快捷键支持** - `Cmd/Ctrl + \\`` 打开/关闭面板，`Escape` 退出检查模式
-- **悬浮按钮** - Claude Code 图标按钮打开面板，Inspect 按钮进入检查模式
+- **快捷键支持** - `Cmd/Ctrl + Shift + I` 切换检查模式，`Escape` 退出
 
 ## 快速开始
 
@@ -63,48 +64,87 @@ npx claude-dev-server@latest --port 4000
 
 ## 使用方法
 
-### 悬浮按钮
+### 界面布局
 
-页面右上角会显示两个悬浮按钮：
+浏览器打开后会显示分屏布局：
 
-| 按钮 | 功能 |
-|------|------|
-| **Claude Code 图标** | 打开/关闭 Claude Code 面板 |
-| **Inspect 图标** | 进入/退出元素检查模式 |
+```
+┌─────────────────────────────────────────────────────────────┐
+│  ┌────────────────────┐ │ ┌──────────────────────────────┐  │
+│  │  Claude Code 终端   │ │ │     开发服务器 (Next.js)      │  │
+│  │                    │ │ │                              │  │
+│  │  [Inspect 按钮]    │ ╳ │                              │  │
+│  │                    │ │ │                              │  │
+│  └────────────────────┘ │ └──────────────────────────────┘  │
+│           左侧 (40%)      │           右侧 (60%)              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+- **左侧面板** - Claude Code 终端（可拖动分隔线调整宽度）
+- **右侧面板** - 开发服务器（Next.js/Vite/Webpack 应用）
+- **分隔线** - 鼠标悬停变橙色，拖动可调整左右宽度
 
 ### 键盘快捷键
 
 | 快捷键 | 说明 |
 |--------|--------|
-| `Cmd/Ctrl + \\`` | 打开/关闭 Claude Code 面板 |
-| `Escape` | 退出检查模式或关闭面板 |
+| `Cmd/Ctrl + Shift + I` | 切换元素检查模式 |
+| `Escape` | 退出检查模式 |
 
 ### 工作流程
 
-1. 按 `Cmd/Ctrl + \\`` 或点击 Claude Code 图标打开面板
-2. 在终端中直接与 Claude Code 交互
-3. 点击 **Inspect** 按钮进入检查模式
-4. 鼠标移动到页面元素上会高亮显示
-5. 点击元素后自动发送格式化提示到终端：
+1. 在左侧 Claude Code 终端中与 AI 交互
+2. 点击左上角的 **Inspect** 按钮进入检查模式
+3. 鼠标移动到右侧页面元素上会高亮显示
+4. 点击元素后自动发送格式化提示到终端：
    ```
-   @src/App.tsx:12 <button className="btn"> "Submit"
+   @src/App.tsx:12 <button.inline-flex.items-center> "Submit"
    ```
-6. Claude Code 会根据代码位置上下文回答你的问题
+5. Claude Code 会根据代码位置上下文回答你的问题
 
 ## 提示格式说明
 
 选中元素后，会自动生成以下格式的提示：
 
 ```
-@<filename>:<line> <selector> "text content"
+@<filename> <selector> "text content"
 ```
 
-- `@filename:line` - 源文件路径和行号（支持 React DevTools、Vue 组件）
-- `<selector>` - CSS 选择器（标签名 + ID + 类名）
-- `"text content"` - 元素文本内容（如果存在）
+- `@filename` - 源文件路径
+- `<selector>` - CSS 选择器（标签名 + ID + 类名，最多 3 个）
+- `"text content"` - 元素文本内容（前 50 个字符）
+
+**示例：**
+```
+@apps/web/src/app/[lng]/login/page.tsx <button.inline-flex.items-center> "Log In"
+```
 
 ## 架构
 
+### Next.js 路由解决方案
+
+使用 `dev.html` + referer 检测解决 Next.js 在 iframe 中的路由问题：
+
+```
+浏览器直接访问: http://localhost:3000/dashboard
+         ↓
+服务器检测: 无 dev.html referer
+         ↓
+302 重定向到: /dev.html?path=/dashboard
+         ↓
+dev.html 加载，创建 iframe src="/dashboard"
+         ↓
+iframe 加载，referer=".../dev.html"
+         ↓
+服务器检测到 dev.html referer
+         ↓
+代理原始 HTML（无注入）
+         ↓
+Next.js 有真实 window.location → 路由正常工作 ✅
+```
+
+### 系统架构
+
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │                  Claude Dev Server (主进程)                  │
@@ -113,9 +153,9 @@ npx claude-dev-server@latest --port 4000
 │  │  HTTP Proxy      │         │  Control Server  │         │
 │  │  (Port :3000)    │         │  (WebSocket)     │         │
 │  │                  │         │                  │         │
-│  │  - 代理转发       │         │  - ttyd 管理      │         │
-│  │  - HTML 注入     │◄───────►│  - Claude 进程   │         │
-│  │  - 中间件        │         │                  │         │
+│  │  - Referer 检测   │         │  - ttyd 管理      │         │
+│  │  - dev.html 重定向│◄───────►│  - Claude 进程   │         │
+│  │  - 代理转发       │         │                  │         │
 │  └────────┬─────────┘         └──────────────────┘         │
 │           │                                                    │
 │           ▼                                                    │
@@ -132,9 +172,13 @@ npx claude-dev-server@latest --port 4000
                     ┌─────────────────┐
                     │   Browser       │
                     │                 │
-                    │  - App 页面     │
-                    │  - Claude 终端  │
-                    │  - Inspector    │
+                    │  ┌───────────┐  │
+                    │  │ dev.html  │  │
+                    │  │ (分屏布局) │  │
+                    │  │           │  │
+                    │  │ 左: 终端  │  │
+                    │  │ 右: iframe│  │
+                    │  └───────────┘  │
                     └─────────────────┘
 ```
 
@@ -151,27 +195,28 @@ npx claude-dev-server@latest --port 4000
 
 ### Q: 如何使用自己的 claude 命令？
 
-A: 使用 `--claude-path` 选项：
-
-```bash
-npx claude-dev-server --claude-path /path/to/your/claude
-```
+A: 暂不支持，默认使用 `claude` 命令。
 
 ### Q: Inspect 模式下为什么有些元素无法选中？
 
-A: Dev Tools 自身的元素（悬浮按钮、面板等）已被排除，无法选中。
+A: 某些特殊元素（如 iframe 内部）可能无法正常选中。
 
 ### Q: 支持哪些框架的源码定位？
 
-A: 目前支持 React、Vue。使用项目根路径自动计算相对路径。
+A: 目前支持 Next.js (通过 Turbopack chunk 解析)。其他框架使用默认的元素选择器。
 
 ### Q: 可以在其他端口使用吗？
 
 A: 可以，使用 `--port` 选项指定任意端口。
 
+### Q: 为什么 URL 中有 `/dev.html?path=...`？
+
+A: 这是正常的。dev.html 是分屏布局容器，`path` 参数指定右侧 iframe 要加载的实际路径。
+
 ## 技术栈
 
-- **HTTP Proxy** - 请求转发和 HTML 注入
+- **HTTP Proxy** - 请求转发和 referer 检测
+- **dev.html** - 分屏布局容器，解决 Next.js 路由问题
 - **ttyd** - 终端 over HTTP/WebSocket
 - **xterm.js** - Web 终端组件（VS Code 同款）
 - **WebSocket (ws)** - 客户端-服务器通信