本文件用于约束和指导参与本项目的 AI 代理与协作者。
- 技术栈与背景：优先参考
README.md。 - 移动端平台边界：Android 客户端位于
apps/mobile，使用 Expo / React Native 实现；iOS 客户端位于apps/ios，使用 Swift / SwiftUI 原生实现。 - 双语同步：修改中文文档时必须同步更新对应的英文文档。修改根目录 README 时必须同步
README.md、README.zh-CN.md、README.zh-TW.md、README.ja.md、README.pl-PL.md。
- 先评估后实现：动手前说明功能价值、影响范围、最坏后果、回滚方案和未验证项；低价值但可能扰动成熟链路的需求，默认拒绝或提供低风险替代方案。
- 核心链路从严：安装器、自动升级、数据存储、认证及迁移的机制或配置变化一律按高风险变更处理，必须验证真实的旧版本到新版本链路，不能只验证新版本自身。
- 禁止无依据保证：未完成对应平台及跨版本验证时，必须明确标注风险，严禁声称“不影响现有用户”或“不影响自动升级”。
- USB 真机优先：Android 功能调测必须使用通过 USB 连接的真实设备和
adb，不得启动或使用 QEMU、AVD 等 Android 模拟器；未连接可用真机时，明确标注真机验证未完成，不得以模拟器结果替代。
- 回复 Issue、PR 或提交 PR Review（含行内审查意见）时，使用对方正文或当前讨论的主要语言：英文用英文回复，中文用中文回复。
- 对方明确指定沟通语言时，遵循其要求；中英混合或无法判断时，默认使用英文。
- 不得因与仓库维护者的本地对话使用中文，就在英文 Issue 或 PR 中使用中文回复。
- Fork 工作流边界：配置 GitHub Actions 时必须考虑大量用户会 Fork 仓库进行自部署；仅官方仓库需要的 Job 必须使用
github.repository == 'tianma-if/edgeever'门禁，严禁在下游 Fork 中分配 Runner 或执行。 - 版本号与基线：
vX.Y.Z（非 Draft/Prerelease）。发布须显式--bump patch|minor|major（脚本不自动选级）；按 SemVer 选择，禁止因发版节奏把用户可感知的新能力或新平台压成 patch。递增根目录package.json；含移动端修改时同步apps/mobile/app.json的expo.version并递增android.versionCode。上一个正式 Release 为审计基线。 - 跨平台 Release 资产：每个正式 Release 页面必须同时包含 macOS arm64 DMG、macOS x64 DMG、Windows x64 Preview 安装包、Linux x64 AppImage Preview 和 Android arm64 APK。Windows Preview 未使用 Authenticode 签名时必须同时提供经仓库外 Ed25519 私钥签名的更新清单；Linux Preview 必须包含
latest-linux.yml更新元数据和独立 SHA-256 清单；两者均须在发布前通过独立下载与摘要审计。若本次未修改对应原生运行时代码、依赖、配置或构建工具，直接复用上一个正式 Release 中已验证的原始资产，保留原文件名与校验和，禁止仅为匹配新版本号而重命名。官方仓库正式 Release 中的 Android APK 必须使用固定的 Google Play 应用签名证书；本地上传证书签名的 APK 只能作为 Draft 临时资产，未经 Play 签名替换和发布前门禁核验不得公开。 - 验证命令：必须通过
bun run typecheck、bun run typecheck:mobile和bun run build:web。 - 测试职责边界：正式 Release 必须先在官方仓库及与下游一致的 Ubuntu 环境通过完整非 E2E 测试，严禁将上游自身的测试失败转嫁给下游 Fork 发现。只读部署 Fork 仅同步产品快照且不运行测试；只有显式保留定制改动的 Fork 才验证合并结果，失败时必须保持
main与生产环境不变。 - 原生资产构建与复用：由
scripts/plan-native-release.mjs决定重建或复用；桌面资产包含apps/web。修改判定规则时同步更新测试。移动端重建使用bun run build:android:apk:local，签名配置保存在仓库外。 - Draft 内准备资产：通过带
release_tag的workflow_dispatch在 Draft 中准备并验证资产；Android 重建时须在 Draft 阶段完成 Google Play 交付、用 Play 签名 APK 替换临时资产并通过独立签名门禁；published事件只审计，禁止重新构建或上传，签名不符时恢复 Draft。 - 桌面验证职责：桌面 Release 工作流负责测试、包结构检查、签名与公证；代理不再重复下载 Draft 或执行本地首次启动验收，除非用户明确要求。
- 发布后更新：正式发布后，发布流程默认不得下载、覆盖安装或启动
/Applications/EdgeEver.app；已安装的 macOS、Windows 与 Linux 桌面端通过应用内自动更新机制获取新版，其中 Linux Preview 必须在 Draft 阶段通过真实 AppImage 跨版本更新门禁。仅在用户明确要求时使用--install-desktop执行原有安装验收，功能体验由用户在实际使用中验证。 - 失败处理：Release 阻塞工作流或资产审计失败时保持或恢复 Draft，修复后重跑；不得公开已知损坏的 Release。GHCR 镜像属于阻塞门禁；腾讯云 TCR 公共镜像由独立工作流在正式发布后异步同步和审计，其耗时或失败不得阻塞 GitHub Release 或将已发布版本恢复为 Draft。
- Release 说明结构：使用中英文双语格式（正文禁止包含字面量
\n），只写用户可感知的变化、影响以及必要的升级或迁移提醒。类型检查、构建命令、签名、公证、资产复用等技术验证细节保留在 Actions 和关联 Issue 中，不写入公开 Release 正文。功能/修复关联对应 Issue 并标记 Label，发布后回链并关闭 Issue。正文结构：
## 主要更新
- 面向用户说明本次变化及影响。
关联 Issue：#<issue-number>
## Key Changes
- User-facing summary of changes in English.
Related Issue: #<issue-number>- 外部贡献者署名：维护者本人无需署名；外部贡献逐条注明账号与 PR，或集中致谢。正文名单不重复列名，保留 GitHub 原生 Contributors 头像区。参数用法见
docs/release.zh-CN.md/docs/release.md。
- AI 模型 API 优先客户端直连：所有平台、所有功能的 AI 模型 API 请求优先由客户端直接调用模型服务；Web 端遇到浏览器网络或 CORS 限制时，允许通过 EdgeEver 后端兜底。桌面端及原生移动端保持直连；已有 HTTP 响应或开始接收流式结果后，不得因错误自动切换到后端重复调用。
- Cloudflare 部署：严格按
docs/agent-deploy-cloudflare.md执行。 - 跨运行时架构：项目未来将正式支持 Docker 自托管；实现新功能时必须保持业务逻辑与 Cloudflare 解耦，并为其他运行时预留扩展边界。Cloudflare 与 Docker 必须共用同一套业务代码，仅允许保留薄且稳定、不包含业务判断的运行入口和基础设施驱动适配器。
- 数据库 Migration：数据库或种子变化时，在
migrations/下新增递增编号 SQL，禁止修改已执行的旧 Migration。 - 本地启动：默认
bun run dev（纯本地环境）。用户要求“启动/重启 Web 端”时，默认含 Web 与 API，必须使用bun run dev；只有用户明确要求“纯前端”或明确指定dev:web时，才使用bun run dev:web。指定远程实例用EDGE_EVER_INSTANCE=<实例名> bun run dev:remote。 - Demo 示例同步：修改示例笔记后，在
main分支干净状态下执行bun run demo:sync重置公开 Demo。 - 禁止重复造轮子：严禁重复实现已有成熟方案；优先采用维护活跃、广泛验证的开源组件与依赖，并优先复用
shadcn/ui；复杂或重复模块封装为独立组件。 - UI和交互的原则是，产品始终表现得可靠、可预测、确定、被接住。
- 悬停提示：所有悬停或聚焦提示严禁使用 HTML 原生
title；Web 端必须统一使用 shadcn/ui 的 Tooltip 组件，并确保键盘聚焦时同样可见。
- 品牌色：复用现有的 UI 黑灰配色，Logo 图形色
#07130B。 - 修改 Logo 后执行
bun run prepare:brand:icons同步各平台资源。