mcpField
D
developer-sandbox

developer-sandbox

github.com/jonathimer营销与增长8788 次安装34 周前更新
代码仓库

关于 developer-sandbox

面向开发者产品团队的交互式演示环境设计指南，帮助开发者在投入设置前评估产品、学习概念并复现问题。内容涵盖示例、分享与嵌入、注册门槛、架构和安全考量。

主要功能

  1. 01规划从简单到进阶的演示体验
  2. 02使用真实 API 和沙盒凭据
  3. 03设计预置示例与实际场景
  4. 04支持演示状态分享和嵌入
  5. 05设置渐进式注册门槛
  6. 06考虑代码隔离与 API 防护

适用场景

  1. 01让访客在注册前试用产品能力
  2. 02用示例解释 API 概念与用法
  3. 03分享可复现的代码问题
  4. 04在文档或内容中嵌入可运行演示

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jonathimer/devmarketing-skills --skill developer-sandbox

安装后在 Claude Code 中输入/developer-sandbox确认已加载。

附带文件README.md

详细介绍

交互式 Playground 和演示环境

让开发者在决定使用产品之前先体验它。优秀的 Playground 能消除采用产品的最大障碍：不确定你的产品能否解决他们的问题。

概述

开发者 Playground 有多种用途：

  • 评估：让开发者在投入时间进行设置之前先行测试
  • 学习：通过交互式环境理解概念
  • 营销：无需销售人员沟通即可展示产品能力
  • 支持：提供可复现的环境来调试问题

本指南介绍如何设计 Playground，将好奇的访客转化为活跃用户。

开始之前

查看 developer-audience-context 技能，了解：

  • 开发者注册前想要验证什么？
  • 你所在领域的典型评估工作流是什么？
  • 竞品提供了哪些 Playground？
  • 展示价值所需的最小可行体验是什么？

你的 Playground 应回答开发者在评估时提出的问题。

Playground 设计原则

原则 1：即时获得反馈

开发者打开页面后，应在 10 秒内看到有意义的内容。

好：页面加载时，已有可运行的示例 不好：空编辑器中只有“在此输入代码”占位文本


<div class="playground">
  <div class="editor">
    <pre><code>// Analyze sentiment of this text
const result = await api.analyze("I love this product!");
console.log(result.sentiment); // "positive"</code></pre>
  </div>
  <div class="output">
    <pre>{ "sentiment": "positive", "confidence": 0.94 }</pre>
  </div>
  <button class="run-btn">Run ▶️</button>
</div>
原则 2：逐步提升复杂度

从简单内容开始，随着开发者兴趣增加，让他们逐步深入。

级别 1：一键演示

[Analyze Text] → See result immediately

级别 2：可编辑输入

[Edit the text] → [Run] → See result

级别 3：完整 API 访问权限

Edit code → Modify parameters → See raw request/response

级别 4：完整 Playground

Multiple files → Import SDK → Build mini-app
原则 3：真实 API，真实结果

绝不伪造结果。使用带有沙盒凭据的实际 API。

真实结果的重要性：

  • 建立信任（不是演示，而是真正的产品）
  • 展示真实的性能表现
  • 演示实际的错误处理
  • 用户注册后不会遇到意外
原则 4：零阻碍

基础 Playground 无需注册、安装或配置。

❌ Bad: "Sign up to try the playground"
❌ Bad: "Install our CLI to continue"
❌ Bad: "Configure your environment..."

✅ Good: Works immediately in browser

预置示例

示例选择策略

选择满足以下条件的示例：

  1. 在 30 秒内展示核心价值
  2. 解决开发者遇到的真实问题
  3. 展现与竞品的差异
  4. 从简单到高级，逐步增加复杂度
示例类别

“Hello World”示例

  • 以最简单的方式使用你的 API
  • 无需任何修改即可运行
  • 证明系统正常工作
// Example: Text Analysis API
const result = await api.analyze("Hello, world!");
// Output: { words: 2, characters: 13 }

“顿悟时刻”示例

  • 展示产品的独特能力
  • 带来“哇，居然这么简单”的惊喜
  • 这是最重要的示例
// Example: Shows AI doing something impressive
const result = await api.summarize(longArticle);
// Output: A perfect 3-sentence summary

“真实用例”示例

  • 展示开发者实际会遇到的场景
  • 演示如何解决特定问题
  • 针对不同用例提供多个示例
// Example 1: E-commerce - Analyze product reviews
// Example 2: Support - Classify incoming tickets
// Example 3: Social - Detect spam comments

“集成”示例

  • 展示产品如何与热门工具协同工作
  • 解答“这能与我的技术栈配合使用吗？”这一疑问
// Example: Integration with Express.js
app.post('/analyze', async (req, res) => {
  const result = await api.analyze(req.body.text);
  res.json(result);
});
示例质量检查清单
  • 示例无需修改即可运行
  • 输出内容有趣或令人印象深刻
  • 代码遵循语言的最佳实践
  • 注释解释代码正在执行的操作
  • 真实用例一目了然
  • 自然激发“它还能做什么？”的好奇心

分享和嵌入

可分享的 Playground URL

让开发者能够分享 Playground 状态：

https://playground.example.com/?code=BASE64_ENCODED_CODE
https://playground.example.com/share/abc123 (stored state)

使用场景：

  • 与团队成员分享代码
  • 在 Stack Overflow 答案中添加链接
  • 在错误报告中附上复现步骤
  • 在博客文章中添加代码片段
可嵌入的 Playground

让开发者将 Playground 嵌入自己的内容：


<iframe
  src="https://playground.example.com/embed/quickstart"
  width="100%"
  height="400px"
></iframe>


<div class="example-playground" data-example="quickstart"></div>
<script src="https://playground.example.com/embed.js"></script>
嵌入注意事项

大小和性能：

  • 轻量级嵌入脚本（< 50KB）
  • 仅在 Playground 可见时延迟加载
  • 宽度自适应，高度可配置

自定义：

  • 主题选项（浅色/深色，与宿主网站匹配）
  • 显示/隐藏特定 UI 元素
  • 只读或可编辑模式

署名：

  • 使用低调的品牌标识链接回产品
  • 添加“由 [Product] 提供支持”页脚
  • 添加“在完整 Playground 中编辑”链接

是否设置访问门槛

何时保持免注册

免注册（无需注册）适用于：

  • 开发者正在评估是否采用
  • 示例展示了产品的核心价值
  • 可以通过速率限制防止滥用
  • 目标是提升漏斗顶端的认知度
何时要求注册

需要注册的情况：

  • 使用生产环境 API 资源
  • 访问个人或已保存的 Playground
  • 使用需要账户的高级功能
  • 生成供外部使用的 API 密钥
渐进式注册策略
┌─────────────────────────────────────────────────────────┐
│ UNGATED                                                  │
│ • Run pre-built examples                                │
│ • Edit and re-run examples                              │
│ • Share playground URLs                                 │
├─────────────────────────────────────────────────────────┤
│ FREE SIGNUP                                             │
│ • Save playgrounds                                      │
│ • Get API key for external use                         │
│ • Access more examples                                  │
│ • Higher rate limits                                    │
├─────────────────────────────────────────────────────────┤
│ PAID                                                    │
│ • Production API access                                 │
│ • Team features                                         │
│ • Premium models/features                               │
└─────────────────────────────────────────────────────────┘
注册体验

需要用户注册时，尽量减少阻力：


<div class="save-prompt">
  <p>Want to save this playground?</p>
  <button onclick="signup()">Create free account</button>
  <button onclick="dismiss()">Continue without saving</button>
</div>


<div class="modal">
  <p>Sign up to continue using the playground</p>
  <form></form>
</div>

Playground 到注册的转化

转化漏斗
Playground Visit
      ↓
Runs First Example (Time to first interaction)
      ↓
Modifies Example (Engagement)
      ↓
Explores More Examples (Interest)
      ↓
Hits Limitation (Trigger)
      ↓
Signs Up (Conversion)
设计转化触发点

鼓励用户注册的自然限制：

// Rate limit message
"You've used 10/10 free playground requests today.
 Sign up for 1,000 free requests/month."

// Feature tease
"This example uses our Pro model.
 Sign up to try it free."

// Save prompt
"Your playground session will expire in 30 minutes.
 Create an account to save your work."

避免人为设置阻碍：

// Bad: Arbitrary block
"Sign up to run more than 3 examples"

// Bad: Feature that should be free
"Sign up to see request/response details"
转化最佳实践

清晰的价值主张：

┌─────────────────────────────────────────┐
│ Create a free account                   │
│                                         │
│ ✓ Get your own API key                 │
│ ✓ Save and share playgrounds           │
│ ✓ 1,000 free API calls/month           │
│                                         │
│ [Sign up with GitHub]                   │
│ [Sign up with Google]                   │
│ [Sign up with email]                    │
└─────────────────────────────────────────┘

保留上下文：

  • 注册后，返回相同的 Playground 状态
  • 在他们的代码中预先填入 API 密钥
  • 根据他们正在进行的操作，展示相关的“后续步骤”

衡量漏斗：

analytics.track('playground_visit');
analytics.track('playground_first_run');
analytics.track('playground_code_edit');
analytics.track('playground_signup_prompt_shown');
analytics.track('playground_signup_started');
analytics.track('playground_signup_completed');

Playground 架构

客户端 Playground

适用于：

  • JavaScript/TypeScript SDK
  • 基于浏览器的 API
  • 对延迟敏感的场景

架构：

┌──────────────────────────────────────────┐
│ Browser                                  │
│  ┌─────────────┐    ┌────────────────┐ │
│  │ Monaco      │    │ Preview/Output │ │
│  │ Editor      │ →  │ Iframe        │ │
│  └─────────────┘    └────────────────┘ │
│         ↓                    ↓          │
│  Bundler (esbuild-wasm) → Execute       │
│                              ↓          │
│                        Your API         │
└──────────────────────────────────────────┘
服务端 Playground

适用于：

  • Python、Go、Ruby 等
  • 隔离至关重要的场景
  • 依赖关系复杂的场景

架构：

┌────────────────────────────────────────────────┐
│ Browser                                        │
│  ┌─────────────┐    ┌────────────────────┐   │
│  │ Editor      │    │ Output             │   │
│  └─────────────┘    └────────────────────┘   │
│         ↓                    ↑                │
└─────────│────────────────────│────────────────┘
          │                    │
          ↓                    │
   ┌──────────────────────────────────────┐
   │ Backend                              │
   │  ┌────────────┐    ┌─────────────┐ │
   │  │ Code       │ →  │ Sandbox     │ │
   │  │ Receiver   │    │ Container   │ │
   │  └────────────┘    └─────────────┘ │
   └──────────────────────────────────────┘
安全注意事项

沙箱隔离：

  • 在容器中执行用户代码
  • 限制 CPU、内存和网络
  • 禁止访问主机文件系统
  • 终止失控的进程

API 防护：

  • 按 IP/会话实施速率限制
  • 使用仅供沙箱使用的 API 凭证
  • 监控滥用模式

内容安全：

  • 扫描生成的内容
  • 拦截恶意输出
  • 记录日志以供审计

Playground 的 UX 组件

必备 UI 元素
┌─────────────────────────────────────────────────────────────┐
│ [Examples ▼] [Docs] [Share] [Sign Up]                       │
├───────────────────────────────┬─────────────────────────────┤
│                               │                             │
│  // Your code here            │  Output                     │
│  const result = await         │  {                         │
│    api.analyze("Hello");      │    "sentiment": "neutral"  │
│                               │  }                         │
│                               │                             │
│                               │                             │
├───────────────────────────────┴─────────────────────────────┤
│ [▶ Run]  [Reset]  [Copy Code]  [Copy as cURL]              │
└─────────────────────────────────────────────────────────────┘
编辑器功能
  • 语法高亮
  • SDK 方法自动补全
  • 错误高亮
  • 行号
  • 支持多个文件（高级）
输出功能
  • 格式化 JSON
  • 可折叠的嵌套对象
  • 复制输出按钮
  • 请求/响应切换
  • 计时信息

工具

代码编辑器
  • Monaco Editor：VS Code 的编辑器（功能丰富）
  • CodeMirror：轻量、可扩展
  • Ace Editor：历史悠久、经过充分验证
沙箱
  • Firecracker：轻量级虚拟机
  • gVisor：容器沙箱
  • WebContainers：基于浏览器的 Node.js
Playground 平台
  • CodeSandbox：完整的开发环境
  • StackBlitz：基于 WebContainer
  • Replit：支持多种语言
  • Custom：自行构建，实现自主控制
嵌入方式
  • iframes：简单但功能有限
  • Web Components：隔离性更好
  • Script embeds：灵活性最高

相关技能

  • api-onboarding：将 Playground 用作入门工具
  • docs-as-marketing：文档中的交互式示例
  • sdk-dx：适用于 Playground 场景的 SDK 设计
  • developer-metrics：衡量 Playground 的效果
  • developer-audience-context：了解要演示的内容

评论

支持 Markdown