opencode-web-preview

英文版：README.md

opencode-web-preview 为 OpenCode 增加托管式本地前端预览能力，但它必须与 OpenCode Studio 配合使用，因为预览会话存储、代理路由和托管运行时都由 Studio 负责。

为什么选择 Web Preview

• 直接在 OpenCode 对话中启动、停止、重启并查看本地前端预览。
• 将预览会话记录、日志和运行状态统一保存在 OpenCode Studio 中，让 UI 与 agent 共享同一份事实来源。
• 生成稳定的 proxyBasePath，方便 Studio 承载 iframe、静态资源和 HMR 流量。
• 按常见前端端口与环境变量约定发现可访问的 loopback 开发地址。

安装

把插件加入你的 OpenCode 配置文件 opencode.json：

• Unix/macOS：~/.config/opencode/opencode.json
• Windows：%USERPROFILE%\\.config\\opencode\\opencode.json（例如：C:\\Users\\<your-user>\\.config\\opencode\\opencode.json）

{
  "plugin": ["opencode-web-preview"]
}

OpenCode 会在会话启动时自动安装 npm 插件。

必须与 OpenCode Studio 搭配使用

opencode-web-preview 是一个 Studio 配套插件，不能脱离 Studio 单独使用。

• 了解 Studio： opencode-studio
• 预览会话的持久化存储和 HTTP API 都由 Studio 提供。
• 当 OpenCode 由 Studio 启动时，Studio 会自动注入：
  • OPENCODE_STUDIO_BASE_URL
  • OPENCODE_STUDIO_UI_AUTH_TOKEN（仅在 Studio UI 开启鉴权时提供）
• 如果缺少这些环境变量，除 help 之外的所有动作都会失败。

自然语言快速开始

示例提示词：

1. 使用 web_preview_helper 为当前前端工作区启动一个托管预览。
2. 使用 web_preview_helper 列出 Studio 中的预览会话，并告诉我哪个正在运行。
3. 使用 web_preview_helper 在 5173 端口重启预览会话 pv_example。

OpenCode Studio 集成体验

web_preview_helper 在 OpenCode Studio 中最有价值：

• 通过 Studio API 管理会话生命周期（create、update、start、stop、status、list）。
• 让 Studio UI 与 agent 共享 id、port、targetUrl、日志等预览元数据。
• 使用稳定的 /api/workspace/preview/s/{id}/ 路径安全承载代理预览。
• 仅允许 loopback 发现，降低本地前端预览交接时的风险。

如果你希望 agent 稳定管理本地前端预览，那么 OpenCode Studio 既是必需运行时，也是最推荐的控制界面。

详细说明

更详细的动作契约、发现规则、Studio API 载荷和验证命令见 DETAIL.md。

License

MIT