# 商业化扩展设计：安装时自动配置 + 激活码/Key 售卖

目标：将「编辑器内反馈 + MCP」做成**付费扩展**，用户购买后获得激活码/Key，在扩展中配置后解锁功能；安装时自动添加 MCP 配置和全局规则，对话在 Windsurf 内部展示与配置。

---

## 一、整体流程

```
用户购买 → 获得激活码 (如 XXXXX-XXXXX-XXXXX)
    ↓
安装扩展 → 扩展激活时：
    ├── 可选：若未激活，提示输入激活码
    ├── 自动追加 MCP 配置到 ~/.codeium/windsurf/mcp_config.json
    └── 自动创建/追加全局规则 (如 global_rules.md 或 Windsurf 规则目录)
    ↓
用户输入激活码 → 扩展请求你的「许可证校验服务」→ 校验通过后写入本地
    ↓
后续启动 → 扩展读取本地许可证状态 → 已激活则正常提供 MCP + 侧边栏对话 UI
```

---

## 二、安装时自动添加的配置

### 1. MCP 配置

- **路径**：`~/.codeium/windsurf/mcp_config.json`（macOS/Linux）或 `%USERPROFILE%\.codeium\windsurf\mcp_config.json`（Windows）。
- **做法**：扩展在 `activate()` 中：
  - 读取该 JSON（若不存在则 `{}`）；
  - 在 `mcpServers` 下添加或更新一个条目（如 `dev-workflow-utils` 或你对外品牌名），`command` 用 `uvx`，`args` 用 `["你的包名@latest"]`，并带上 `timeout`、`env`、`autoApprove` 等；
  - 写回文件。
- **注意**：避免覆盖用户已有的其他 MCP；只做「无则添加、有则按你的 key 更新」。

### 2. 全局规则（提示使用该 MCP）

- **目的**：让 Cascade 在对话中知道要使用你提供的 MCP 工具。
- **可能位置**（需在 Windsurf 实际环境中确认）：
  - 用户级：`~/.codeium/windsurf/global_rules.md` 或类似路径；
  - 或通过 Windsurf 设置里的「Rules」界面维护，扩展无法直接写文件时，可改为在扩展内提供「一键复制规则内容」按钮，让用户粘贴到规则里。
- **若可写文件**：在安装/首次激活时追加一段规则内容，例如：

```markdown
## Dev Workflow Utils
- 在需要用户确认或收集反馈时，请使用 MCP 工具 dev_checkpoint。
- 使用前请确保已启用 Dev Workflow Utils 对应的 MCP 服务器。
```

- **若不可写**：在扩展的 Webview 或说明里提供上述内容 + 「复制到全局规则」按钮。

---

## 三、激活码 / Key 的承接与配置

### 1. 用户如何配置 Key

- **方式 A（推荐）**：在 VS Code/Windsurf 的**设置**里增加一项，例如：
  - 设置 ID：`devWorkflowUtils.licenseKey`
  - 用户粘贴购买得到的激活码（如 `XXXXX-XXXXX-XXXXX`），保存。
- **方式 B**：扩展提供**命令**（Command Palette）：`Dev Workflow Utils: Enter License Key`，弹出输入框，用户输入后由扩展校验并保存。
- **方式 C**：在扩展侧边栏 Webview 里做「许可证」Tab，输入 Key 并显示激活状态、到期时间。

可以 A+B 或 A+C 同时存在：设置里可填，界面里也可填并展示状态。

### 2. Key 的存储（安全与持久化）

- **不要**把 Key 明文写在 `mcp_config.json` 或规则文件里（容易被复制、泄露）。
- **推荐**：
  - 使用 VS Code 的 **SecretStorage API**（`vscode.SecretStorage`）存「激活码」或「服务端返回的 token」；或
  - 使用 **GlobalState**（`context.globalState`）存「已激活」状态 + 到期时间，Key 本身用 SecretStorage。
- 流程建议：
  - 用户输入 Key → 调用你的校验 API（见下）→ 服务端返回 `{ "valid": true, "expires_at": "2026-12-31", "token": "..." }`；
  - 扩展将 `token` 或 Key 存入 **SecretStorage**，将 `expires_at` 和 `activated: true` 存入 **GlobalState**；
  - 下次启动只读 GlobalState/SecretStorage，不再每次请求服务器（可选的「心跳」见下）。

### 3. 校验服务（你的后端）

- **接口**：你维护一个 HTTPS 接口，例如：
  - `POST https://your-product.com/api/license/activate`
  - Body：`{ "license_key": "XXXXX-XXXXX-XXXXX", "machine_id": "optional-unique-device-id" }`
  - Response 200：`{ "valid": true, "expires_at": "2026-12-31", "plan": "pro" }`
  - Response 4xx：`{ "valid": false, "reason": "expired" }`
- **扩展侧**：在用户点击「激活」或保存设置时，用 Node 的 `https.request` 或 `fetch` 调用该接口；根据返回决定是否写入 SecretStorage/GlobalState，并更新 UI（已激活 / 已过期 / Key 无效）。
- **可选**：定期（如每 7 天）在扩展内再请求一次 `POST /api/license/validate`，带上存好的 token 或 Key，用于封禁外泄 Key 或提前提示续费。

### 4. 未激活时的行为

- **方案 A（软限制）**：未激活也可添加 MCP 和规则，但侧边栏里提示「请输入激活码以解锁完整功能」或限制使用次数（如每天 3 次）。
- **方案 B（硬限制）**：未激活则不自动添加 MCP（或添加但 MCP 侧由你服务器校验 Key 后再响应）；扩展内所有能力都要求先激活。
- 推荐先做 **方案 B**，逻辑简单、变现清晰；若需要拉新可再改为方案 A。

---

## 四、对话在 Windsurf 内部显示与配置

- **显示**：用扩展的 **Webview View**（侧边栏）或 **Webview Panel** 展示「当前反馈会话」：显示 AI 的 summary、用户输入框、图片上传、提交/取消。数据来源可以是：
  - MCP 通过本地端口把「本次请求」推给扩展（你之前设计的 TCP/HTTP 桥），扩展把内容渲染在 Webview 里，用户提交后再通过该连接回传给 MCP。
- **配置**：在扩展的 **设置**（`package.json` 的 `contributes.configuration`）里提供：
  - 端口号（与 MCP 约定一致）；
  - 主题、语言等；
  - **许可证 Key**（`devWorkflowUtils.licenseKey`），见上。

这样「对话在 Windsurf 内部显示」由扩展 Webview 承接，「配置」由 VS Code 设置 + 可选 Webview 里的「设置」Tab 完成。

---

## 五、实现清单（扩展侧）

| 项目 | 说明 |
|------|------|
| 安装时写 MCP 配置 | 读 `~/.codeium/windsurf/mcp_config.json`，合并你的 MCP 条目后写回 |
| 安装时写/提示全局规则 | 若存在 `global_rules.md` 等则追加规则；否则提供「复制规则」按钮 |
| 设置项 `licenseKey` | `contributes.configuration`，用户可粘贴激活码 |
| 命令 `Enter License Key` | 输入框 → 调校验 API → 存 SecretStorage + GlobalState |
| 激活校验 API | 你的后端 `POST /api/license/activate`，返回 valid + expires_at |
| 启动时检查许可证 | 读 GlobalState/SecretStorage，过期或缺失则提示输入 Key |
| Webview 对话 UI | 接收 MCP 请求、展示 summary、提交后回传，端口与 MCP 一致 |
| （可选）心跳校验 | 定期调用 `/api/license/validate` 拉黑或提示续费 |

---

## 六、售卖与 Key 发放

- **售卖**：用你现有渠道（官网、Gumroad、Paddle、柠檬等）售卖「许可证」，用户支付后收到：
  - 一封邮件，内含 **激活码**（如 `XXXXX-XXXXX-XXXXX`），或
  - 一个「下载/查看 Key」的链接。
- **Key 生成**：后端在「订单完成」时生成唯一 Key，写入你的数据库，并和 `expires_at`、`plan` 绑定；`/api/license/activate` 时查库校验并返回结果。
- **扩展只负责**：把用户输入的 Key 发到你的接口，根据返回结果写入本地并决定是否解锁功能；不负责支付，支付和 Key 发放都在你的后台完成。

---

## 七、小结

- **安装时**：扩展自动添加 MCP 配置（和可选全局规则），用户无需手改 `mcp_config.json`。
- **激活**：用户购买获得 Key，在设置或扩展内输入；扩展请求你的校验 API，通过后把状态存 SecretStorage/GlobalState，实现「承接售卖后的激活码」。
- **对话与配置**：在 Windsurf 内部用 Webview 显示对话与配置，MCP 通过本地端口与扩展通信；Key 不写进 MCP 配置，只存在扩展的保密存储中，保证可售卖、可校验、可过期控制。

若你确定技术栈（例如 Node 后端用哪家、Key 格式），可以在扩展仓库里按上述清单拆成 issue/任务逐步实现；需要的话我可以再按「扩展第一版最小闭环」列一份更细的接口与文件结构。
