# Spare 开发者共创指南 · v1

Spare 把 AI 生成间隙变成可选择的轻量体验。广告保留既有有效曝光与收益机制；小游戏、宠物和社区插件不自动产生现金收益。首批体验包括小恐龙、2048、宠物陪伴和账户共同养宠，欢迎小说、短剧、种树、呼吸伸展、小工具与更多创意。

入口：https://spare.cool/developers
在线体验：https://spare.cool/play
开发模板：https://spare.cool/downloads/spare-plugin-starter.zip
联系：support@spare.cool

## 1. 无需私有仓库，立即开始

1. 下载并解压模板 ZIP。包内包含 `index.html`、`manifest.json`、`preview.html`、`README.md` 和 `LICENSE`。
2. 双击 `preview.html`，体验「片刻花园」，点击开始、模拟回答完成和恢复，观察 JSON 快照。
3. 修改 `index.html` 的 HTML、CSS、JavaScript。不需要框架、构建工具、Spare 账户或 API 密钥。
4. 如浏览器限制本地文件或持久存储，在目录中运行 `python3 -m http.server 8000`，访问 `http://localhost:8000/preview.html`。停止调试时在终端按 Ctrl+C。
5. 模板代码采用 MIT 许可证；保留许可证即可修改并开发你自己的作品。表情由用户设备的系统字体呈现，无额外图片包。

## 2. 设计适合等待的体验

- 一次几秒到几分钟，随时可停止；不因离开而惩罚用户。
- 默认静音，不弹出其他窗口，不阻碍 AI 回答或关闭操作。
- 320px 手机宽度到桌面窗口都可用，触控、键盘和减弱动态效果偏好可用。
- 不接触 AI 提示词、回答、代码、账户令牌、广告计费或提现接口。
- 首版建议离线静态内容；需要网络、账号或其他权限时请先说明，审核团队会评估可行性。
- 代码、图片、音乐、小说、短剧内容需要你拥有使用和发布权，并在 README 中列出许可证或授权来源。

## 3. Manifest

`manifest.json` 放在包根目录。名称、版本、方向必须与提交表单一致。

```json
{
  "schemaVersion": 1,
  "id": "com.example.tiny-garden",
  "name": "片刻花园",
  "version": "1.0.0",
  "category": "plant",
  "entry": "index.html",
  "permissions": [],
  "storage": "local",
  "lifecycle": {
    "start": "spareStart",
    "pause": "sparePause",
    "snapshot": "spareSnapshot"
  }
}
```

`id` 使用英文小写反向域名或带连字符的唯一标识；版本使用 `1.0.0`。`category` 可选 `game`、`pet`、`story`、`novel`、`plant`、`utility`、`other`。`entry` 是包内 HTML 相对路径，不接受绝对路径、`..` 或远程网址。首版 `permissions` 建议为空；`storage` 为 `local` 或 `none`，描述进度需求，不意味着社区沙箱可访问 Spare 的网站存储。

## 4. 暂停、恢复与快照

原生宿主适配约定为三个函数：

```js
window.spareStart = (saved, language) => {
  state = normalize(saved);  // saved 可能是 null；校验与限制输入
  render(language);
};
window.spareSnapshot = () => ({ ...state });
window.sparePause = () => {
  stopTimersAndAudio();
  return window.spareSnapshot();
};
```

- `spareStart`：宿主恢复进度后开始体验。语言可为 `zh-Hans`、`en`、`fr`，不支持的语言应有回退。
- `spareSnapshot`：返回 JSON 可序列化的小对象，建议小于 16 KiB；不包含 DOM、函数、图片或敏感信息。
- `sparePause`：立即停止动画计时器、循环、声音和用户交互，再返回快照；可重复调用。
- 处理 `visibilitychange`：页面隐藏时暂停。每次关键操作后主动提交快照，避免突然关闭造成丢失。
- 当前原生端只加载随版本内建的官方体验。提交 ZIP 不会自动安装；社区插件原生接入需由团队适配并随客户端版本发布。

模板还演示浏览器预览消息：宿主发送 `{type:'spare:start',state,language}` 或 `{type:'spare:pause'}`；插件发送 `{type:'spare:ready'}` 和 `{type:'spare:snapshot',state}`。接收方必须验证 `event.source` 是对应父窗口或 iframe。模板只传递本地进度，不传递身份或凭证。

## 5. 本地验证与打包

1. 在 `preview.html` 中开始体验，操作后查看快照。
2. 点击「模拟回答完成」，确认立刻暂停；点击开始，确认恢复。
3. 刷新预览或关闭再打开，检查宿主是否恢复进度。本地文件存储被禁用时用本地 HTTP 预览。
4. 选择手机 320px，检查横向溢出、按钮与文字；测试键盘操作和页面隐藏。
5. 离线测试，浏览器控制台无报错，不发送不必要请求。
6. 将 manifest、入口、全部本地资源、README、许可证打为 ZIP；文件放包根目录。不要包含 `node_modules`、开发缓存、`.git`、密钥或系统文件。

可直接上传的 ZIP 最大 5 MiB。大型素材可提供 HTTPS 包下载链接供团队评估，最终托管范围仍需审核。不要在链接中包含账号密码、访问令牌或私人凭据。

## 6. 提交与审核

1. 在 https://spare.cool/developers 登录 Spare 账户；普通账户即可提交。
2. 填写名称、方向、简介、版本、联系方式、HTTPS 源码地址。
3. 选择 ZIP 上传或 HTTPS 下载地址，粘贴真实 manifest，说明数据处理和素材授权。
4. 提交后，在「我的作品」查看状态和审核反馈。
5. 状态依次为待审核、审核中、审核通过待上架、已上架。退回时请根据反馈修改，提升版本后重新提交；旧记录保留。
6. 团队人工检查代码、许可、隐私、体验和兼容性，通过后部署到官方静态目录，再在后台发布。上传包本身不会执行或自动公开。
7. 已发布作品出现在共创页目录，以隔离 iframe 体验。社区预览只允许脚本，不赋予同源、弹窗、表单或导航权限；无法读取 Spare 登录状态和网站存储，当前社区预览不自动保存进度。

## 7. 当前边界与共创方式

官方小游戏与单人宠物的浏览器进度只存当前设备；账户情侣或兄弟共养使用服务器保存共同亲密值、双方贡献与每日任务。邀请加入不产生现金奖励。真实救助联动规则默认筹备中，合作方、预算及转换规则确认并启用后再执行；已核验凭证见 https://spare.cool/rescue。第三方社区作品目前提供审核后的浏览器展示，客户端插件目录、社区作品云存档和作者分成仍需后续产品方案与版本支持。不要把游戏积分或宠物等级描述为可提现金额。

在你的源码仓库开启 Issues，接受体验反馈；把新方向、技术需求和合作建议发送到 support@spare.cool。Spare 团队可以协助审核、托管和上架，不需要开发者访问私有仓库。