GitHub 同步

每次保存 Velxio 项目时，GitHub 同步 都会将草图、画布状态和自动生成的 README 提交并推送到您拥有的 GitHub 仓库。您的代码始终保留在您自己的版本控制中——Velxio 只是其上的编辑器。

GitHub 同步是 Pro 版的一部分——请参阅套餐。

同步内容

每次成功保存时，Velxio 都会写入您仓库的根目录：

• sketch.ino — 以及活动板卡文件组中的任何额外 .ino / .h / .c / .py 文件。
• velxio.json — 完整的画布状态：板卡类型、放置的组件、导线和每个板卡的布局。克隆您仓库的任何人都可以在 Velxio 中打开该项目，并看到完全相同的电路。
• README.md — 自动生成，包含项目名称、描述和“在 Velxio 中打开”的深层链接。当您想要更丰富的 README 时，可以自由覆盖。

Velxio 绝不会触碰这些路径之外的文件——仓库中的 CI 配置、文档、照片和其他任何内容都不会被改动。

如何启用

1. 打开任意已保存的项目。点击编辑器工具栏中的 … 溢出菜单，然后选择 同步到 GitHub。
2. 仅首次使用：点击 连接 GitHub。GitHub 会询问您希望 Velxio 写入哪些仓库——Velxio 仅获得这些仓库的安装级访问权限，不会获得“所有仓库”的全面授权。
3. 从下拉菜单中选择目标仓库，然后点击 链接并立即同步。Velxio 会推送初始提交并显示 SHA 和链接。
4. 完成。之后每次保存都会推送新的提交；同步弹窗会显示上次同步时间和提交的直接链接。

安全模型

Velxio 使用 GitHub 应用，而非个人 OAuth 令牌：

• 按仓库选择加入 — 您在安装时选择 Velxio 可以写入的仓库，并可以随时从 github.com/settings/installations 撤销或添加仓库。
• 无长期令牌 — 每次同步都会生成一个约 1 小时有效期的全新安装令牌；用户 OAuth 令牌仅使用一次（用于在连接时获取您的 GitHub 个人资料）后即被丢弃。
• 独立的速率限制 — 该应用拥有自己的配额，与您个人工具的配额分开。
• 干净断开 — 从您的 GitHub 设置中删除 Velxio 应用会立即撤销访问权限；Velxio 会接收 webhook 并断开连接，不会留下过期状态。

冲突与手动编辑

同步目前是单向推送：Velxio → GitHub。在 Velxio 保存之间于 GitHub 上进行的手动编辑将在下次保存时被覆盖——Velxio 是同步文件的权威来源。

想在 VS Code 中本地开发一段时间？取消链接项目（同步弹窗 → 取消链接），在本地克隆中工作，然后准备好再次从 Velxio 驱动时重新链接。双向同步已在路线图中。

常见问题

如果同步失败怎么办？ 失败会在同步弹窗中显示，并提供恢复操作（重新连接 GitHub、选择其他仓库、稍后重试）。保存本身永远不会被阻止——您的项目始终会保存在 Velxio 内部。

我可以同步到我不拥有的仓库吗？ 可以，只要 GitHub 应用已安装在该组织中，并且您拥有写入权限。

私有仓库呢？ 完全支持——您在安装期间授权的任何内容都可写入，无论是公开还是私有。

我可以自定义 README 吗？ 目前 Velxio 每次同步都会覆盖 README.md。路线图中计划：一旦您接管了该文件，就跳过覆盖。

—– 页面结束 —–