powersync

PowerSync 技能

使用此技能可将项目接入 PowerSync，并在之后持续维护其健康运行，避免反复试错。请优先将其视为引导式工作流，其次才是参考资料库。

**Agent：请先阅读 AGENTS.md，再继续。其中包含强制合规规则和接入指南。以下快速规则仅供提醒，不能代替该文件。powersync login**仅适用于 PowerSync Cloud（PAT）；自托管部署无需使用此命令。

术语

• Operator — 指挥此 Agent 的人（你正在执行其请求）。
• User — Operator 的 PowerSync 应用的终端用户（JWT 主体、同步流筛选的行所对应的人、调用 disconnectAndClear() 的人）。

如果句子存在歧义，默认按 Operator 的含义理解。完整术语表见 AGENTS.md。

快速规则

• **优先使用 CLI。**所有操作均使用 PowerSync CLI。不要手写配置文件。请参阅 references/powersync-cli.md。
• **先询问，不要假定。**询问 Operator 使用的是 Cloud 还是自托管部署，以及使用哪种后端（Supabase、Postgres、MongoDB、Azure DocumentDB、MySQL、MSSQL）。不要默认使用 Supabase。
• **先后端，后前端。**部署同步配置并验证服务正常后，再编写应用代码。
• **新项目使用 Sync Streams。**Sync Rules 已过时。
• **将凭据保存在 .env 中，切勿硬编码。**获取 URL 和密钥后，将其记录在 .env 中；配置（!env）和应用代码从该文件读取。
• **现有项目的默认范围：仅修改同步配置。**除非 Operator 在本次对话中明确授权修改服务或基础设施，否则不要编辑 service.yaml 或 cli.yaml。
• **执行任何会改变状态的命令（deploy、destroy、stop、link --create、pull instance）前，先确认目标实例。**绝不要将内容部署到未经 Operator 授权的实例。未经明确批准，不得操作生产环境。
• **使用项目记忆。**如果你的运行环境支持，请保存 CLI 调用方式、同步配置路径、已授权的实例 ID 和环境（dev/staging/prod），以及允许的变更范围。采取行动前，请确认保存的值仍与实际情况一致。请参阅 AGENTS.md §“持续使用与防护措施”。

在仓库中首次使用：提供精简选项（agents）

此副本包含适用于所有 PowerSync 平台的参考文件。在仓库中首次使用此技能时，请检查此文件旁是否存在 .trim-state.json。如果存在，说明 Operator 已作出决定；跳过本节。

否则，请从此技能所在目录运行 node scripts/trim.mjs。默认运行只生成报告：它会检测此仓库使用了哪些 PowerSync 平台，并列出此副本中不需要的参考文件。该脚本仅作用于当前安装的副本，不会发起网络请求；重新安装此技能即可恢复。若脚本拒绝运行（共享安装或源代码安装）或尚未检测到任何 PowerSync 用途，则静默跳过本节。否则，将报告展示给 Operator，并询问是否精简此安装副本。未经 Operator 明确批准，绝不要精简。

• Operator 批准：运行 node scripts/trim.mjs --apply（如需保留 Operator 仍想使用的平台，请添加 --keep <platforms>）。
• Operator 拒绝：运行 node scripts/trim.mjs --decline，以免再次询问。

重新安装或运行 npx skills update 会恢复完整副本并清除已记录的决定；更新后再次提供精简选项是预期行为。

根据任务加载内容

任务	从此处开始	按需加载
Supabase + PowerSync	references/onboarding-supabase.md	references/supabase-auth.md、references/sync-config.md、SDK 文件
自定义后端（非 Supabase）	references/onboarding-custom.md	references/custom-backend.md、references/sync-config.md、SDK 文件
新项目设置	references/powersync-cli.md + references/powersync-service.md	references/sync-config.md、SDK 文件
从 Electric Cloud 迁移	references/migration-from-electric.md	references/sync-config.md、SDK 文件
自托管 / 服务配置	references/powersync-service.md + references/powersync-cli.md	references/sync-config.md
Terraform / IaC 配置	references/terraform.md	references/sync-config.md、references/supabase-auth.md（如果数据源是 Supabase）
编写同步配置	references/sync-config.md	—
调试同步问题	references/powersync-debug.md	—
Raw Tables（高级）	references/raw-tables.md	—
附件	references/attachments.md	—
架构概览	references/powersync-overview.md	—
SQLite 扩展（向量搜索、FTS5、自定义分词器）	references/sqlite-extensions.md	—

SDK 参考文件

JavaScript / TypeScript

对于任何 JS/TS 项目，始终加载 references/sdks/powersync-js.md，然后加载适用的框架文件。

框架	文件	在以下情况下尽早加载……
React / Next.js	references/sdks/powersync-js-react.md	Vite + React 项目 — 包含安装包之前所需的 vite.config.ts 配置（optimizeDeps.exclude、worker.format: 'es'）
React Native / Expo	references/sdks/powersync-js-react-native.md
Vue / Nuxt	references/sdks/powersync-js-vue.md
Node.js / Electron	references/sdks/powersync-js-node.md
TanStack	references/sdks/powersync-js-tanstack.md
Drizzle / Kysely ORM	references/sdks/powersync-js-orm.md	项目使用 Drizzle 或 Kysely

其他 SDK

| 平台 | 文件 | |----------| | Dart / Flutter | references/sdks/powersync-dart.md | | .NET | references/sdks/powersync-dotnet.md | | Kotlin | references/sdks/powersync-kotlin.md | | Swift | references/sdks/powersync-swift.md | | Rust | references/sdks/powersync-rust.md |

无需询问即可遵循的关键规则

• 切勿在 PowerSync 表架构中定义 id 列；系统会自动创建该列。
• 布尔值使用 column.integer，ISO 日期字符串使用 column.text。
• connect() 会立即返回，后台继续执行。需要确认就绪时，请使用 waitForFirstSync()。
• 每个会话只调用一次 .connect()。不要在窗口获得焦点、令牌刷新或网络变化时再次调用；重复调用会建立额外的同步连接。
• 必须调用 transaction.complete()，否则上传队列会永久停滞。
• 用户退出登录时，根据设备上可能保留的数据选择处理方式：如果同一用户之后会再次登录且可以保留数据，请使用 disconnect()，这样下次会话可以恢复，而无需重新下载。如果必须隐藏可见行，但 PowerSync 的内部副本可以保留，请使用 disconnectAndClear(soft: true)；此操作会删除已同步的行，但保留内部副本，因此以同一用户重新连接时，大多数情况下无需完整重新下载。如果不能保留任何已同步数据，请使用默认的 disconnectAndClear()。切勿为其他用户保留某一用户的数据。
• uploadData 的 4xx 响应会永久阻塞上传队列；验证错误时应返回 2xx。