一、先说结论
在当前项目里，Stagewise 最适合扮演"页面定位器"，Cursor 最适合扮演"代码实现工具"。
推荐链路是：
- 本地前端运行在
127.0.0.1:8080 Stagewise bridge运行在127.0.0.1:3100- 浏览器继续访问真实域名
whistle把页面流量从真实域名转到3100/admin/api继续走真实域名，保留登录态
一句话总结：
- 用
Stagewise选页面元素 - 用
Cursor定位文件和改代码 - 如果自动投递到
Cursor不稳定，就手动把上下文发给Cursor
二、Stagewise 是什么
Stagewise 是一个面向前端开发的可视化 AI 上下文工具。它的核心价值不是多一个聊天窗口，而是把浏览器里的真实页面元素直接变成 AI 可以理解的输入。
相比"截图 + 复制 DOM + 手工描述问题"，Stagewise 更适合做两件事：
- 从页面反向定位代码
- 给 AI 提供更准确的 UI 上下文
官方资料：
三、它能解决什么问题
Stagewise 特别适合下面这些场景：
- 页面元素好找，但代码位置难找
- UI 修改需求很明确，但上下文描述成本高
- 微前端、条件渲染、动态拼装导致代码路径不直观
- 想快速回答"这个按钮对应哪个文件、哪个组件"
四、为什么本项目要这样接
本项目不推荐直接打开 http://127.0.0.1:3100，因为这样容易丢失真实域名下的登录态。
在当前项目里，如果接口失去登录态，通常会走到：
- 接口
401 - 前端跳到
sso.dev.shoplazza.com - 最后看到
refused to connect
所以 sso.dev.shoplazza.com refused to connect 往往不是根因，而是 401 -> SSO 之后的结果。
五、开始前需要准备什么
1. 本地工具
- 已安装
Cursor - 已安装
Node.js - 已安装
whistle
2. Cursor 扩展
需要在 Cursor 中安装：
stagewise.stagewise-vscode-extension
3. 项目基础能力
确认项目可以正常启动：
arduino
npm run dev4. 版本说明
当前 bridge 模式依赖旧版 CLI：
css
npx stagewise@0.11.1 ...不建议直接使用 stagewise@latest 来走本文这套旧 bridge 链路。
六、项目里有哪些配置和改动
1. stagewise.json
项目根目录已有：
yaml
{
"appPort": 8080
}作用：
- 告诉
Stagewise被包裹的本地前端端口是8080
2. vite.config.js
已支持从环境变量读取：
DEV_PROXY_TARGETDEV_PROXY_COOKIE
作用：
- 只在必要时用本地私有配置兜底
- 避免把真实 cookie 写死在代码里
3. .env.local.example
提供本地私有代理配置模板。
4. .gitignore
已忽略：
.env.local.env.*.local
作用：
- 避免本地登录态被提交进仓库
5. 项目 Skill
已新增：
.cursor/skills/stagewise-whistle-bridge/SKILL.md.cursor/skills/stagewise-whistle-bridge/reference.md
作用：
- 复用本次关于
Stagewise、whistle、401 -> SSO的排查经验
七、需要执行的命令
1. 启动本地前端
arduino
npm run dev默认运行在：
127.0.0.1:8080
2. 启动 Stagewise bridge
css
npx stagewise@0.11.1 -b -a 8080 -w "/Users/zhenghaiyang/Desktop/shoplazza/git/loyalty" -v -s参数含义：
-b：bridge mode-a 8080：包裹本地前端端口-w：项目绝对路径-v：输出调试日志-s：静默模式
正常情况下，Stagewise 会监听：
127.0.0.1:3100
八、whistle 规则怎么切
1. 普通开发模式
perl
wss://feature-v3-1---robbin-shop.dev.myshoplaza.com/ wss://localhost:8080/ resCors://enable
^https://feature-v3-1---robbin-shop.dev.myshoplaza.com/*** //127.0.0.1:8080/$1 resCors://enable excludeFilter://*/admin/api2. Stagewise 模式
perl
wss://feature-v3-1---robbin-shop.dev.myshoplaza.com/ wss://127.0.0.1:3100/ resCors://enable
^https://feature-v3-1---robbin-shop.dev.myshoplaza.com/*** http://127.0.0.1:3100/$1 resCors://enable excludeFilter://*/admin/api核心区别：
- 普通开发：真实域名转到
8080 - Stagewise 模式：真实域名转到
3100
九、完整使用步骤
1. 启动前端
arduino
npm run dev2. 启动 Stagewise bridge
css
npx stagewise@0.11.1 -b -a 8080 -w "/Users/zhenghaiyang/Desktop/shoplazza/git/loyalty" -v -s3. 切换 whistle 到 Stagewise 模式
把真实域名从 8080 改为转发到 3100。
4. 通过真实域名访问页面
访问：
https://feature-v3-1---robbin-shop.dev.myshoplaza.com/...
不要直接打开：
http://127.0.0.1:3100
5. 在页面中使用 Stagewise toolbar
在页面里选中按钮、标题、卡片或表单元素，再输入你的修改目标。
6. 用 Cursor 做最终实现
如果 Stagewise -> Cursor 自动投递没生效，就直接手动把信息发给 Cursor。
十、当前最推荐的工作流
当前环境下，最稳的方式是：
- 用
Stagewise选元素 - 用
Cursor读代码 - 让
Cursor先定位文件，再实施修改
推荐提问模板：
markdown
我在页面上用 Stagewise 选中了一个元素。
页面：
`https://你的真实域名/...`
元素：
- 类型：按钮 / 标题 / 卡片 / 表单项
- 文案：`xxx`
- 大致位置：例如"会员召回计划页顶部右侧按钮"
目标：
- 想把它改成：`xxx`
- 预期行为：`xxx`
补充上下文：
- 这是从 Stagewise 选中的页面元素
- 如果需要，请先帮我定位它对应的文件和组件，再实施修改十一、已知限制
当前链路前半段已经打通：
Stagewise bridge已成功启动- 页面通过真实域名和
whistle能正常展示 Cursor扩展已安装并激活
但最后一步，也就是：
Stagewise自动把 prompt 投递到Cursor
这一步并不稳定。当前现象通常是：
- Stagewise 中发送了请求
Cursor会被拉起- 但
Cursorchat 中没有真正收到 prompt 或上下文
这个现象更像是当前 Cursor 版本与 Stagewise bridge 的兼容限制，而不是本地配置错误。
参考资料：
- Cursor 社区讨论：Cursor 1.0 ignores input from stagewise
- Stagewise issue: messages to Cursor don't auto-execute
十二、FAQ
1. 为什么页面能开，但会跳到 sso.dev.shoplazza.com？
因为接口先 401 了，SSO 跳转只是后续表现。
2. .env.local 是必须的吗？
不是。它只是兜底方案，主推荐链路仍然是：
- 真实域名
whistle80803100
3. 为什么不能直接访问 3100？
因为当前项目依赖真实域名登录态，直接访问 3100 容易丢 cookie。
4. 自动投递到 Cursor 没生效，是我配置错了吗？
不一定。结合当前排查结果，这更像是兼容性限制。
5. 当前最推荐的使用方式是什么？
最推荐的是：
- 用
Stagewise选页面元素 - 用
Cursor负责代码定位和实现 - 自动投递失效时，改为手动喂给
Cursor
十三、总结
对当前项目来说，Stagewise 的价值不在于完全替代 Cursor，而在于：
- 帮助从页面快速定位元素
- 降低 UI 修改的上下文描述成本
- 缩短"页面问题 -> 代码定位 -> 实施修改"的路径
当前最佳实践可以概括为：
- 页面访问继续走真实域名
whistle在普通开发和 Stagewise 模式之间切换8080/3100- 不优先依赖在
vite.config.js中硬编码登录 cookie - 当自动投递不稳定时，优先使用"Stagewise 选元素 + 手动喂给 Cursor"的工作流