developer-sandbox

用途

开发者演练场（Playground）用于让开发者在正式投入时间配置环境之前，先直接体验产品。它主要服务于四类目的：评估（让开发者在投入安装时间前先测试）、学习（提供理解概念的交互环境）、营销（无需销售通话即可展示能力）、支持（提供可复现的调试环境）。本技能聚焦于设计能把好奇访客转化为活跃用户的演练场。

开始之前

建议先参考 developer-audience-context 技能，弄清以下问题：开发者在注册前想验证什么？所在领域的典型评估流程是什么？竞品是否提供演练场？能展示价值的最小可用体验是什么？演练场应当回答开发者评估时真正关心的问题。

设计原则

原则一：即时满足。开发者应在落地后 10 秒内看到有意义的结果。好的做法是页面加载时已有可运行的示例；不好的做法是空白编辑器加“在此输入代码”的占位提示。

原则二：渐进复杂度。从简单开始，随好奇心增长逐步深入。可分为四级：一键演示（点击即见结果）、可编辑输入（改文本再运行）、完整 API 访问（改代码、调参数、查看原始请求/响应）、完整演练场（多文件、导入 SDK、构建迷你应用）。

原则三：真实 API、真实结果。不要伪造结果，应使用沙箱凭证调用真实 API。真实能建立信任、展示真实性能特征、演示真实错误处理，避免注册后的落差。

原则四：零摩擦。基础演练场无需注册、无需安装、无需配置。应避免“注册后才能试用”“安装 CLI 才能继续”“先配置环境”等做法，理想状态是在浏览器中立即可用。

预置示例

示例选取应满足：30 秒内展示核心价值、解决开发者真实问题、体现与竞品的差异、复杂度从简到繁。示例类别包括：“Hello World”示例（最简单用法，零修改即可运行，证明系统可用）、“顿悟时刻”示例（展示独特能力，制造“原来这么简单”的反应，是最重要的示例）、“真实用例”示例（电商评论分析、工单分类、垃圾评论检测等实际场景）、“集成”示例（展示与 Express.js 等流行工具的配合，回应“能否适配我的技术栈”）。

示例质量检查清单：无需修改即可运行；输出有趣或令人印象深刻；代码符合语言最佳实践；注释解释发生了什么；真实用例显而易见；能自然引出“还能做什么”的好奇。

分享与嵌入

可分享的演练场 URL 支持通过 Base64 编码代码或存储状态来分享，用于与同事共享代码、在 Stack Overflow 回答中链接、附带复现步骤的缺陷报告、博客文章中的代码片段。

可嵌入演练场支持通过 iframe 或 script 标签嵌入到文档等自有内容中。嵌入时需考虑：体积与性能（轻量脚本小于 50KB、可见时才懒加载、宽度自适应且高度可配置）；定制（明暗主题、显示/隐藏特定 UI、只读与可编辑模式）；归属（带链接的轻量品牌标识、“Powered by”页脚、“在完整演练场中编辑”链接）。

门槛策略

不设门槛的适用情形：开发者正在评估是否采用、示例展示核心产品价值、可通过速率限制防滥用、目标是漏斗顶部的认知。

设置门槛的适用情形：使用生产 API 资源、访问个人/已保存的演练场、需要账户的高级功能、为外部使用生成 API 密钥。

渐进式门槛策略分三层：不设门槛（运行预置示例、编辑并重跑示例、分享演练场 URL）；免费注册（保存演练场、获取外部使用的 API 密钥、访问更多示例、更高速率限制）；付费（生产 API 访问、团队功能、高级模型/功能）。

设置门槛时也应尽量减少摩擦，例如采用非阻塞式提示（“想保存这个演练场吗？”并提供“创建免费账户”和“不保存继续”两个选项），而非阻塞式弹窗。

从演练场到注册的转化

转化漏斗为：访问演练场 → 运行首个示例（首次交互时间）→ 修改示例（参与）→ 探索更多示例（兴趣）→ 触达限制（触发）→ 注册（转化）。

可设计自然的转化触发点，例如速率限制提示（“今日免费额度已用完，注册可获每月 1000 次免费请求”）、功能预告（“此示例使用 Pro 模型，注册可免费试用”）、保存提示（“会话将在 30 分钟后过期，创建账户以保存工作”）。应避免人为摩擦，如“运行超过 3 个示例需注册”“查看请求/响应详情需注册”这类本应免费的限制。

转化最佳实践：清晰的价值主张（列出注册可获得的具体权益，并提供 GitHub、Google、邮箱等多种注册方式）；保留上下文（注册后回到同一演练场状态、在代码中预填 API 密钥、展示与当前操作相关的“下一步”）；衡量漏斗（对访问、首次运行、代码编辑、注册提示展示、注册开始、注册完成等事件埋点）。

架构

客户端演练场适用于 JavaScript/TypeScript SDK、基于浏览器的 API、对延迟敏感的场景。架构为浏览器内的 Monaco 编辑器加预览/输出 iframe，经打包器（如 esbuild-wasm）执行后调用你的 API。

服务端演练场适用于 Python、Go、Ruby 等语言、隔离要求高、依赖复杂的场景。架构为浏览器编辑器将代码发送到后端，由沙箱容器执行并返回输出。

安全注意事项

沙箱隔离：在容器中执行用户代码、限制 CPU/内存/网络、禁止访问宿主文件系统、终止失控进程。API 保护：按 IP/会话限流、使用仅限沙箱的 API 凭证、监控滥用模式。内容安全：扫描生成内容、拦截恶意输出、记录审计日志。

UX 组件

核心 UI 元素包括：顶部工具栏（示例下拉、文档、分享、注册）、左侧代码编辑区、右侧输出区、底部操作栏（运行、重置、复制代码、复制为 cURL）。

编辑器功能：语法高亮、SDK 方法自动补全、错误高亮、行号、多文件支持（高级）。输出功能：格式化 JSON、可折叠嵌套对象、复制输出按钮、请求/响应切换、耗时信息。

工具选型

代码编辑器：Monaco Editor（VS Code 的编辑器，功能丰富）、CodeMirror（轻量、可扩展）、Ace Editor（历史悠久、久经考验）。沙箱：Firecracker（轻量虚拟机）、gVisor（容器沙箱）、WebContainers（浏览器内 Node.js）。演练场平台：CodeSandbox（完整开发环境）、StackBlitz（基于 WebContainer）、Replit（多语言支持）、自建（可控性更强）。嵌入方式：iframe（简单但受限）、Web Components（隔离更好）、脚本嵌入（最灵活）。

技能介绍

用途