← Back to Blog

Stagewise 集成指南

Xiao Wu
Xiao WuAuthor
June 25, 2025工具
Tags:
工具Nextjs

Stagewise 集成指南

概述

Stagewise 是一个强大的开发工具，允许 Cursor、GitHub Copilot 和 Windsurf 等 AI 编程助手直接与浏览器交互。它可以让你在任何 DOM 元素上添加注释，并将真实的上下文发送给 AI 助手。

当前状态

⚠️ 注意: 由于 Next.js 15+ 的函数序列化限制，我们暂时移除了自定义 Stagewise 配置。目前使用基础配置。

安装步骤

1. 安装 VS Code 扩展

首先需要在 VS Code/Cursor 中安装 Stagewise 扩展：

  • 访问 VS Code Marketplace
  • 或在 Cursor 中按 CMD + Shift + P，输入 setupToolbar 来自动安装

2. 安装 Next.js 包

项目中已安装 @stagewise/toolbar-next 包：

pnpm i -D @stagewise/toolbar-next

3. 当前配置

在 app/layout.tsx 中的基础配置：

import { StagewiseToolbar } from '@stagewise/toolbar-next'
 
// 只在开发环境中显示（当前已移除以解决序列化问题）
// {process.env.NODE_ENV === 'development' && (
//   <StagewiseToolbar />
// )}

已知问题和解决方案

函数序列化问题

问题: Next.js 15+ 不允许将函数直接传递给客户端组件，导致以下错误：

Functions cannot be passed directly to Client Components unless you explicitly expose it by marking it with "use server"

临时解决方案:

  1. 使用基础 Stagewise 配置（无自定义插件）
  2. 或者完全移除 Stagewise 直到找到更好的解决方案

未来解决方案:

  1. 创建服务器操作来处理 Stagewise 配置
  2. 使用客户端组件来初始化 Stagewise
  3. 等待 Stagewise 更新以支持 Next.js 15+

使用方法

1. 启动开发环境

npm run dev

2. 访问应用

打开浏览器访问 http://localhost:3000/dashboard/chat

3. 基础 Stagewise 功能

在浏览器中：

  1. 元素选择: 在页面上的任何元素上右键
  2. 发送到 AI: 将选中的元素发送给 Cursor/Windsurf
  3. 基础上下文: 获得 DOM 结构和基本信息

在 Cursor 中：

  1. 接收上下文: AI 助手会收到来自浏览器的基础 DOM 上下文
  2. 智能建议: 基于实际的 UI 状态提供代码建议

聊天页面优化

最新 UI/UX 改进

我们对聊天页面进行了专业的 UI/UX 优化：

1. 布局优化

  • 输入框位置: 增加底部间距（pb-6），避免过于贴近底部
  • 消息区域: 优化间距和布局，提供更好的阅读体验
  • 响应式设计: 消息最大宽度限制为 85%，确保良好的阅读体验

2. 配色方案改进

  • 用户消息: 使用主色调背景，确保文字对比度
  • AI 消息: 使用柔和的 muted 背景，带有边框增强可读性
  • 工具调用: 优化配色，使用蓝色系统表示工具状态
  • 深色模式: 完全支持深色模式，自动适配颜色

3. 视觉层次

  • 头像系统: 简洁的圆形头像，用户和 AI 有不同的样式
  • 消息气泡: 圆角设计，增加阴影效果
  • 状态指示: 清晰的加载状态和工具执行状态

4. 交互体验

  • 自动滚动: 新消息自动滚动到底部
  • 悬停效果: 按钮和交互元素有平滑的悬停过渡
  • 焦点管理: 输入框有清晰的焦点环

调试工作流程

1. 基础调试

由于当前使用基础配置，调试功能有限：

  • 选择页面元素
  • 发送基础 DOM 信息给 AI
  • 获得结构化的代码建议

2. 手动上下文提供

在没有自定义插件的情况下，可以：

  • 手动描述聊天功能给 AI
  • 截图并分享给 AI 助手
  • 复制相关代码片段

故障排除

常见问题

  1. 工具栏不显示: 检查是否在开发环境中运行
  2. 扩展未连接: 确认 VS Code/Cursor 扩展已安装并激活
  3. 配置错误: 当前使用基础配置，应该没有配置相关问题

调试步骤

  1. 检查控制台是否有错误
  2. 确认 Stagewise 扩展已激活
  3. 重启开发服务器
  4. 如果问题持续，可以完全移除 Stagewise 配置

未来计划

短期目标

  1. 解决 Next.js 15+ 兼容性问题
  2. 恢复自定义插件配置
  3. 添加聊天特定的上下文信息

长期目标

  1. 深度集成聊天功能调试
  2. 自定义 Stagewise 插件开发
  3. 团队协作工作流程优化

相关链接

Comments