Appwrite Backend 是一个面向 Appwrite 后端开发的技能，聚焦 SDK 开发、自托管以及仅通过 MCP 进行的智能体操作。以下按用途、主要能力、使用方式、适用场景和限制分段说明。
一、用途 该技能用于指导与 Appwrite 相关的开发与运维工作，包括：针对 Appwrite 的任意智能体操作、MCP 服务器搭建、Appwrite 文档查询，以及更具体的生产迁移、破坏性数据擦除、批量写入、事务一致性、Schema 设计、查询优化、认证、权限、团队、存储、函数、实时、消息、Webhook、自托管等任务。技能采用“路由”机制，按触发场景加载对应的主题文档（owner），未列出的细节要求先阅读对应 owner，不得自行推断。
二、主要能力与覆盖主题
- 智能体操作与 MCP：智能体读取、变更、部署、诊断统一使用 mcp-servers 主题；缺少 MCP 能力时要求报告缺口，不提供直接的 SDK、HTTP 或命令行回退方案。
- 生产迁移：涉及生产 Schema/数据/ACL/函数的切换，使用 production-migrations，并在写入共享事务时结合 transactions。
- 破坏性擦除：跨 TablesDB、Auth、Storage、提供商数据或保留的审计证据进行永久账号/主体数据擦除，使用 destructive-erasure 与 transactions。
- 批量操作：针对大规模行创建/更新/upsert/删除、事务限额压力、逐行写入循环，使用 bulk-operations，并在原子范围跨请求/表时结合 transactions。
- 查询与性能：超出 Query.equal() 值上限时使用 chunked-queries；查询形态、select、空间、时间辅助、缺失索引排查使用 query-optimization；列表、信息流、无限滚动、大偏移分页使用 pagination-performance；慢路径、缓存、增量同步、启动顺序使用 performance。
- 数据模型：表/列/索引设计、静态加密、自增、时间戳覆盖、CSV 导入导出使用 schema-management；关系建模或遍历使用 relationships；并发修改的计数器、数组、字符串、日期字段使用 atomic-operators。
- 认证与权限：会话、MFA、SSR 认证、JWT、用户标签、安全设置使用 authentication；OAuth、魔法链接、邮箱 OTP、电话、匿名、自定义令牌、邮箱验证、密码恢复、会话列表/删除、用户偏好使用 auth-methods；ACL 设计、锁定、公开泄露排查使用 permissions；团队、成员、多租户使用 teams。
- 存储与函数：上传、下载、预览、变换、存储桶配置使用 storage-files；函数编写、处理器、运行时、冷启动、环境变量使用 functions；函数事件、调度、幂等、二进制负载、CI/CD 使用 functions-advanced。
- 其它服务：实时订阅、频道、在线状态、事件过滤使用 realtime；推送、邮件、短信使用 messaging；事件外发使用 webhooks；头像、首字母、二维码、旗帜、图标使用 avatars；错误处理使用 error-handling；平台上限或限制错误使用 limits；国家、货币、语言、地理查询使用 locale；GraphQL 端点使用 graphql；自托管安装、配置、安全、扩展、SDK 版本锁定使用 self-hosting；自托管备份、恢复、升级、数据丢失事件使用 self-hosting-ops；健康检查、队列深度、运行时间监控使用 health。
三、使用方式与约定
- 版本与调用风格：Web TypeScript/JavaScript/React 使用 appwrite；Node.js/Deno/TypeScript SSR/函数使用 node-appwrite；Flutter 客户端使用 appwrite；Dart 服务端/函数使用 dart_appwrite；Python 服务端/函数使用 appwrite。TypeScript 使用对象参数，Python 使用关键字参数，Dart 使用命名参数；仅在匹配既有代码或明确要求时使用位置参数。
- 客户端与服务端：客户端 SDK 使用账号会话与用户范围 API；服务端 SDK 使用 API 密钥；SSR 使用两个客户端——可复用的 admin 客户端用于创建会话，以及每请求通过 setSession(...) 创建的会话客户端，二者不能共享。
- 端点与初始化：Cloud 项目端点为 https://<REGION>.cloud.appwrite.io/v1。在运行时允许的情况下，在热函数处理器之外初始化客户端。
四、关键不变量（Invariants）
- 智能体操作用 MCP，应用代码用官方 SDK。缺失 MCP 能力时报告缺口，智能体操作不使用直接 SDK、HTTP 或命令行回退；应用代码使用官方 SDK，原始 Appwrite HTTP 仅在缺失 SDK 端点或隔离且经过测试的 Client.call 模型解析变通方案时使用。
- 按目标与调用形态锁定 SDK：Cloud 用最新稳定官方 SDK；自托管用与所部署服务端版本精确匹配的版本钉（如 2.x 或 1.9.x）。“兼容 1.9.x”不等于版本精确匹配。更改版本钉前需审计每个中间破坏性变更，并用仓库真实的 SDK 调用验证候选版本。已验证的仓库 SDK 版本钉优先于技能版本钉。
- 使用 TablesDB，而非旧版 Databases 服务（其 Collections/Documents API 自 1.8.0 起已弃用）。DocumentsDB 与 VectorsDB 是独立服务，并非该旧 API。
- 资源 ID 只用 ID.unique() 分配一次，并在重试/对账中复用同一 ID；业务/自然身份保留在索引列中，绝不用名称、时间戳、slug、哈希或自定义生成器派生资源 ID。
- 显式 ACL：服务端 SDK/控制台创建的资源 ACL 为空；客户端 SDK 创建者获得 read/update/delete。ACL 正确性重要时始终传入显式的 Permission/Role。
- 限额以部署目标为准：分页大小、每请求批量行数、事务操作数、Query.equal() 值上限均来自已部署服务端源码/配置，不得凭记忆。
- 按所需结果选择执行模式：需要响应数据用同步 createExecution（30 秒限制内）；异步后台工作用有界状态监控与真相对账；轮询/实时无法返回响应体或响应头；长时间运行结果需要经授权的持久结果读取。仅在同步响应不明确或状态/404 时先对账再重试。
- 破坏性范围需证明：Schema/访问收缩需要完整实时清单、精确的已批准资源 ID、备份/恢复证明；字段缺失、分页不完整或访问影响未知时按失败关闭处理。
- 生产迁移分阶段：追加式扩展 → 类型感知可恢复回填 → 兼容部署 → 契约/回读 → 消费者激活；部分数据/Schema 绝不激活下游代码。
- 优化前保留写入意图：仅更新的工作绝不走 upsertRow/upsertRows；同一补丁应用于多行用 updateRows，异构逐行更新用 createOperations 且 action: update，并处于已验证的事务预算内。事务压力绝不允许改用 upsert。
- 编码前先批量收集写入：目标数量可能超过一或依赖数据时，先盘点完整变更集与已部署限额；存在兼容的服务端批量方法时禁止逐行写入循环；不支持批量时需完整的操作预算与原子晚期失败证明。
- 保留失败因果：清理、补偿或回滚失败绝不取代主异常；同时保留两个错误、堆栈跟踪、执行/事务 ID，报告操作失败，然后对账确切后置条件。
- 协调客户端需求与不确定结果：一个端点/项目范围的协调器负责前台、同步、认证与重试流量；限制并发；共享 429/传输冷却；分类 code-zero 网络失败；在一个截止时间内重试读取；重复前先对账写入/事务；每个失败操作只报告一次事件；部分失败后绝不推进同步检查点。
五、适用场景 适合需要按场景准确加载 Appwrite 主题文档的后端开发、生产迁移、数据擦除、批量与事务处理、认证权限设计、自托管与运维、性能与成本优化、实时与消息集成等工作。技能提供了从触发场景到 owner 主题的映射，便于在复杂任务中定位应遵循的规范。
六、限制 该技能仅覆盖上述主题与不变量，未提供的收费、价格、平台、效果或具体步骤等信息暂未提供，需以官方文档为准。技能明确禁止智能体操作使用 MCP 之外的回退方式，并要求在缺失 MCP 能力时报告缺口。关于本技能自身的安装命令或包管理方式，资料中暂未提供。