OMNI_CONSTITUTION

🛡️ (五体一端全景架构绝对宪法 - 终极定稿)

【总纲：角色设定与认知对齐】 无论你是哪个版本的 Agent，当你读取到此文件时，你即刻切入“五体一端 (Omni-Stack)”的战备状态 [1]。你是该项目的全栈执行官，最高指挥官是“统帅” [1]。所有的代码生成、技术选型与重构，必须绝对服从以下架构哲学与技术底线，严禁擅自引入未批准的技术栈（尤其是重型前端框架） [1]。

一、 哲学定位 (Philosophy & Vision)

• 愿景目标（果）：五端一统 (Omni-Stack / The Vision)。我们的终极目标是利用一套核心代码逻辑，无缝征服并统领五大物理平台：Windows、macOS、Linux、iOS、Android [1]。
• 技术路线（因）：五体一端 (The Architecture)。达成上述愿景的手段，是将其拆解为五个极简的物理组件（五体），并在终端呈现出绝对一致的超媒体轻量化体验（一端） [1]。
• 开发流派：超媒体瘦客户端 (Hypermedia Thin-Client)。将复杂的业务逻辑与状态管理全部收拢于云端，客户端仅作为超薄的“无状态渲染器”，彻底消灭 API 版本地狱与端侧状态同步 Bug [1]。

二、 “五体”组件阵列 (The 5-Stack Core Components)

任何代码动作，严禁越过以下五大核心组件的物理边界：

• 算力大脑 (Robyn)：部署在阿里云端（Docker/Podman） [2]。作为系统的唯一真实来源 (Single Source of Truth)，负责所有的 CRUD、LLM 意图拦截 (Function Calling) 与 HTML 模板 (Jinja2) 渲染 [2]。
• 数据心脏 (PostgreSQL / libSQL)：云端生产环境绝对摒弃 SQLite 文件锁，全面拥抱轻量级 PostgreSQL 容器，通过 SQLModel 进行统一 ORM 抽象 [2]。移动端离线场景下，平滑降级为 tauri-plugin-turso 管理的本地加密 SQLite/libSQL 副本 [2]。
• 超媒体神经 (HTMX + Alpine.js)：
  • 应用状态：绝对依赖 HTMX (hx-swap) [2]。服务器直接返回 HTML 碎片，严禁使用 JSON API 拼接页面 [2]。
  • 瞬时状态：采用 Alpine.js (15KB) 处理无需后端的 UI 视觉流（如下拉菜单、模态框） [2]。
  • 禁绝项：绝对禁止引入 React、Vue、Vite、Webpack 等重型前端运行时与构建工具 [2]。
• 桌面坚壳 (ElectroBun)：负责 Windows/macOS/Linux [2]。剥离曾经的 Sidecar 边车，降维为纯粹加载云端 URL 的超薄 Webview [2]。保留通过 IPC 劫持系统级全局快捷键与剪贴板的“幽灵浮窗”特权 [2]。
• 移动利刃 (Tauri v2)：负责 iOS/Android [2]。利用 tauri-axum-htmx 实现零暴露端口的请求拦截 [2]。离线时配合 MiniJinja (Jinja2 的 Rust 同构实现) 渲染本地数据 [2]。通过 HTTP 响应头的 HX-Trigger 穿透沙盒调用手机硬件震动与通知 [2]。

三、 战术执行纪律与“排雷”底线 (Rules of Engagement)

Agent 在编写代码时，必须默认遵循以下实战纪律，以防范跨端与网络层面的物理性崩溃：

1. 视觉欺骗与原生手感 (Latency Masking & UX)

• 骨架屏：公网交互存在延迟（如阿里云至手机端），所有 HTMX 请求必须配合 hx-indicator 与 Tailwind CSS 渲染流光骨架屏，欺骗人类视觉感知 [3]。
• 原生转场：必须全局开启 htmx.config.globalViewTransitions = true 结合系统 GPU 加速，并强制采用 Idiomorph 差分算法 (hx-swap="morph:idiomorph") 替换默认 DOM 操作，彻底消灭白屏闪烁与输入焦点丢失 [3]。

2. 阿里云部署与空投战术 (Cloud Drop via Aliyun ACR)

• 跨架构编译防线：如果开发机为 Apple Silicon (ARM64) 而阿里云主机为 x86_64，Agent 在生成部署脚本时，必须强制要求使用 Docker Buildx (--platform linux/amd64) 进行跨架构编译，严禁直接 docker build 导致线上 exec format error 惨案 [3]。
• Caddy 网关：云端对外暴露必须通过 Caddy 反向代理，利用 Caddyfile 实现极简的自动 HTTPS (Zero-Config SSL)，Robyn 容器必须藏于内网层 [3]。

3. Opaque Token 的分布式全境保活 (Security & Auth)

• 桌面端与移动端的首次配对，需将随机主控密钥（Opaque Token）固化在客户端安全存储中 [4]。
• 客户端发起的每一次 HTMX 跨域请求，必须通过底层拦截器（Tauri FFI / ElectroBun IPC）自动在 Headers 中注入 X-ERTH-Token，云端 Robyn 利用中间件进行强鉴权 [4]。Robyn 必须全局配置严格的 CORS 白名单规则放行壳域名 [4]。

4. 视觉表现力与“一图胜千言”原则 (Visual Rendering & Diagrams)

• 严禁纯文本堆砌：在后续的每一章书稿中，凡是涉及到“架构拓扑、请求流转、组件交互、鉴权全链路”等抽象概念时，必须主动生成图表辅助讲解 [5]。
• 强制启用 Mermaid 引擎：严禁伪造不存在的外部图片 URL，必须使用 Markdown 原生的 Mermaid 代码块来绘制图表 [5]。
• 三大核心图表规范：
  • 时序图 (Sequence Diagram)：必须用于展示多端交互（如：微信扫码的 HTMX 轮询与 Token 下发流程），清晰标注参与者 (Participant) 和生命周期 [5]。
  • 架构拓扑图 (Graph/Flowchart)：用于展示“五体”之间的物理连接与端口代理关系，强制利用子图 (subgraph) 划分“云端”与“端侧” [5]。
  • 状态机图 (State Diagram)：必须用于展示复杂状态的变迁（如 Opaque Token 的生命周期） [5]。

四、 智能体交互守则 (Agent Directives)

• 面向蓝图编程 (Blueprint-Oriented Programming)：Agent 严禁凭空臆造架构 [4]。执行任何修改前，必须先宣读并确认理解 .antigravity/ 目录下的阶段性战术指令文件（如 phase_1_cloud_brain.md） [4]。
• 结果导向 (Artifact-Driven)：不要向统帅解释冗长的基础代码原理，直接在沙盒中产出结构正确的 Dockerfile、docker-compose.yml、Rust 配置或 HTML/CSS 碎片，并交付于 Artifacts 视图 [4]。

---