feat(agy): add GEMINI.md persistent context memory and sync-agy-session.sh

2026-11-07 00:23:07 +08:00
1 parent 6b589fa62a
commit ba3cf726b4
@@ -0,0 +1,67 @@
+# HomeLab & Cloud-Edge Architecture Memory (`GEMINI.md`)
+
+本文件为 `agy` (Antigravity CLI) 的**全局持久上下文记忆文件**。无论在 M5 MacBook Air 还是 M6 Mac mini 网页端 (`https://agy.961504.xyz`) 启动新会话，均自动加载本架构规范。
+
+---
+
+## 1. 交互与工作准则
+1. **汇报 + 确认机制**：每次架构变更或较大改动前，先说明方案，再执行；代码与基础设施配置统一维护在 Git 仓库 [`/Users/ixvii0iv/homelab`](file:///Users/ixvii0iv/homelab) 并同步至 `mini:~/homelab`。
+2. **代码链接规范**：回答中涉及所有文件路径或代码符号时，必须使用可点击的 Markdown 链接（如 `[TopRibbon.tsx](file:///Users/ixvii0iv/homelab/stacks/portal/web/src/components/TopRibbon.tsx)`）。
+
+---
+
+## 2. 核心硬件与网络拓扑（4 大节点）
+
+| 节点角色 | 设备型号 / 系统 | 局域网 / 公网 IP | Tailscale 专线 IP | SSH 快捷别名 | 核心职责 |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **随身开发机** | Apple M5 MacBook Air (macOS) | `192.168.31.83` | `100.89.152.95` | 本机 | 日常主力操作终端、本地 Git 仓库源头 |
+| **家庭计算核心** | Apple M6 Mac mini (24GB RAM, 460GB SSD) | `192.168.31.164` | `100.108.205.40` | `ssh mini` / `ssh mini-ts` | 7×24h All-in-One 服务器、OrbStack 容器宿主机、AGY 网页端宿主、Tailscale 子网路由 (`192.168.31.0/24`) |
+| **家庭存储中心** | 极空间 Z4 (20TB RAID) | `192.168.31.185` | 经 Mac mini 子网路由可达 | Web `5055` / SMB `445` | 20TB 大容量冷热存储、通过 LaunchAgent 自动 SMB 挂载至 Mac mini `~/nas/{共享文件,个人空间}` |
+| **家庭主路由** | 小米路由器 (开启 SSH + ShellCrash/Mihomo) | `192.168.31.1` (联通公网 `124.90.142.21`) | 经 Mac mini 子网路由可达 | `ssh root@192.168.31.1` | PPPoE 拨号、端口转发 (`10443`/`41641` -> `192.168.31.164`)、内网 Split-DNS、锁定 AI 流量走狮城节点 |
+| **海外云端前哨** | 新加坡 Azure VM (Ubuntu 24.04) | `104.43.105.243` | `100.115.204.51` | `ssh azure` | 443 免端口公网 HTTPS 反向代理入口、AI 算力固定出口、Uptime Kuma 外部独立监控哨兵 |
+
+---
+
+## 3. 域名与双通道访问矩阵 (`961504.xyz`)
+
+### 通道 A：443 免端口标准 HTTPS（经新加坡 Azure Caddy -> Tailscale P2P 回源）
+- **导航中控台 (HomeLab Console V3)**: `https://nav.961504.xyz` -> `100.108.205.40:3002`
+- **Storybook 设计系统工作台**: `https://nav.961504.xyz/storybook` -> `100.108.205.40:3002/storybook`
+- **AGY 云端编程工作台 (`ttyd` + `tmux`)**: `https://agy.961504.xyz` -> `100.108.205.40:7681` (受 Basic Auth 保护)
+- **Vaultwarden 密码保险箱**: `https://vw.961504.xyz` -> `100.108.205.40:8222`
+- **Uptime Kuma 外部监控哨兵**: `https://status.961504.xyz` -> `127.0.0.1:3001` (Azure 本地容器)
+
+### 通道 B：10443 家庭宽带公网直连 & 局域网 Split-DNS 秒开（Mac mini Caddy Wildcard TLS）
+- 在家连 Wi-Fi 时，小米路由器 Mihomo 将 `home.961504.xyz` 与 `*.home.961504.xyz` 直接解析为 `192.168.31.164`（并在 `fake_ip_filter` 中豁免 Fake-IP），实现 <1ms 局域网直连。
+- 在外网时，Cloudflare DNS 将 `*.home.961504.xyz` 动态解析至家庭联通公网 IP (`124.90.142.21`)，通过路由器 `10443` 端口转发直达 Mac mini Caddy：
+  - `https://home.961504.xyz:10443` (HomeLab Console V3)
+  - `https://agy.home.961504.xyz:10443` (AGY 云端工作台)
+  - `https://vw.home.961504.xyz:10443` (Vaultwarden)
+  - `https://nas.home.961504.xyz:10443` (极空间 Z4 Web `192.168.31.185:5055`)
+  - `https://clash.home.961504.xyz:10443` (路由器 Mihomo 面板 `192.168.31.1:9999`)
+  - `https://router.home.961504.xyz:10443` (小米路由器后台 `192.168.31.1:80`)
+  - `https://status.home.961504.xyz:10443` (Uptime Kuma `100.115.204.51:3001`)
+
+---
+
+## 4. 前端中控台工程架构 (`stacks/portal/web`)
+- **技术栈**: React 19 + Vite 6 + TypeScript + Zustand + Tailwind CSS v4 + Lucide Icons
+- **设计语言**:
+  - **顶部导航 (`src/components/TopRibbon.tsx`)**: 标准 `shadcn/ui` 双层 AppShell Header。第一层 (`h-14`) 左侧为品牌与 `[中控台 | 📖 Storybook 设计规范]` 视图切换，右侧通过 `ml-auto shrink-0` 严格固定 `[🔍 搜索 ⌘K | >_ AGY 终端 | ☀️/🌙 主题切换]`；第二层 (`h-11`) 左侧为 4 枚硬件/网络微缩仪表胶囊，右侧为四模路由切换器。
+  - **双主流主题自动切换 (`src/design-system/tokens.ts`)**: 仅保留 `light` (Shadcn Clean Light) 与 `dark` (Catppuccin/Linear Dark) 两个主流主题，默认监听 `window.matchMedia('(prefers-color-scheme: dark)')` 跟随设备深浅色自动切换，也可在右上角手动切换。
+  - **内置 Storybook (`src/components/StorybookWorkbench.tsx`)**: 支持实时切换 3 种主流布局 (`homepage-3col` / `bento-split` / `compact-2col`)、查看双主题设计 Token、交互式调试 `ServiceCard` 组件变体。
+- **构建与发布命令**:
+  ```bash
+  cd /Users/ixvii0iv/homelab/stacks/portal/web && npm run build
+  rsync -az --delete /Users/ixvii0iv/homelab/stacks/portal/ ixvii0iv@192.168.31.164:~/homelab/stacks/portal/
+  ```
+
+---
+
+## 5. Mac mini 后台常驻服务清单 (`LaunchAgents` & `LaunchDaemons`)
+- `/Library/LaunchDaemons/com.homelab.caddy.plist`: 系统级 Caddy 网关（监听 `10443`，提供 `*.home.961504.xyz` Let's Encrypt DNS-01 通配符证书反代）
+- `~/Library/LaunchAgents/com.homelab.portal.plist`: HomeLab Console V3 后端与静态资源服务 (`stacks/portal/server.py`，监听 `3002`/`3004`，提供 `/api/telemetry` 与 `/api/action/*`)
+- `~/Library/LaunchAgents/com.homelab.agy-web.plist`: AGY 网页终端 (`scripts/start-agy-web.sh`，通过 `ttyd` 暴露 `7681` 端口并附着到 `tmux` 会话 `agy`)
+- `~/Library/LaunchAgents/com.homelab.cf-ddns.plist`: 每 5 分钟检测家庭公网 IP 并更新 Cloudflare `home.961504.xyz` / `*.home.961504.xyz`
+- `~/Library/LaunchAgents/com.homelab.mount-zspace.plist`: 自动挂载极空间 SMB 至 `~/nas/共享文件` 与 `~/nas/个人空间`
+- `~/Library/LaunchAgents/com.homelab.nas-backup.plist`: 每天凌晨 03:30 自动打包备份 Vaultwarden、Caddy 与基础设施配置至极空间 `~/nas/个人空间/MacMini_Backups/`
@@ -9,12 +9,12 @@ export LANG="en_US.UTF-8"
 export LC_ALL="en_US.UTF-8"
 export TERM="xterm-256color"

-mkdir -p "$HOME/workspace"
+mkdir -p "$HOME/homelab" "$HOME/workspace"

-# 确保 tmux 会话 agy 存在并在其中默认打开 zsh (可直接运行 agy)
+# 确保 tmux 会话 agy 存在并在其中默认恢复最近一次会话 (agy -c)
 if ! /opt/homebrew/bin/tmux has-session -t agy 2>/dev/null; then
-  /opt/homebrew/bin/tmux new-session -d -s agy -c "$HOME/workspace"
-  /opt/homebrew/bin/tmux send-keys -t agy "agy" C-m
+  /opt/homebrew/bin/tmux new-session -d -s agy -c "$HOME/homelab"
+  /opt/homebrew/bin/tmux send-keys -t agy "agy -c" C-m
 fi

 exec /opt/homebrew/bin/ttyd \
@@ -22,4 +22,4 @@ exec /opt/homebrew/bin/ttyd \
  -p 7681 \
  -t fontSize=15 \
  -t 'titleFixed=Mac mini (M6) - AGY 云端工作台' \
-  /opt/homebrew/bin/tmux new-session -A -s agy -c "$HOME/workspace"
+  /opt/homebrew/bin/tmux new-session -A -s agy -c "$HOME/homelab"
@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# ==============================================================================
+# sync-agy-session.sh
+# 用途：将本机 (MacBook Air) 当前的 AGY 会话上下文与 GEMINI.md 永久记忆同步至
+#       Mac mini 云端工作台 (https://agy.961504.xyz)，实现网页端无缝接力
+# ==============================================================================
+set -euo pipefail
+
+SESSION_ID="${1:-6293ebb4-df60-4db6-bf5d-df33433ba106}"
+MINI_HOST="${MINI_HOST:-mini}"
+AGY_DIR="$HOME/.gemini/antigravity-cli"
+
+echo "==> [1/4] 同步全局永久记忆文件 GEMINI.md 至本机与 Mac mini..."
+cp /Users/ixvii0iv/homelab/GEMINI.md "$HOME/GEMINI.md"
+ssh "$MINI_HOST" "mkdir -p ~/homelab ~/workspace ~/.gemini/antigravity-cli/conversations ~/.gemini/antigravity-cli/brain"
+rsync -az /Users/ixvii0iv/homelab/GEMINI.md "$MINI_HOST:~/GEMINI.md"
+rsync -az /Users/ixvii0iv/homelab/GEMINI.md "$MINI_HOST:~/homelab/GEMINI.md"
+rsync -az /Users/ixvii0iv/homelab/GEMINI.md "$MINI_HOST:~/workspace/GEMINI.md"
+
+echo "==> [2/4] 同步会话索引库与历史记录 (conversation_summaries.db / history.jsonl)..."
+for f in conversation_summaries.db conversation_summaries.db-wal conversation_summaries.db-shm jetbox_summaries_proto.pb history.jsonl; do
+  if [ -f "$AGY_DIR/$f" ]; then
+    rsync -az "$AGY_DIR/$f" "$MINI_HOST:~/.gemini/antigravity-cli/$f"
+  fi
+done
+
+echo "==> [3/4] 同步当前会话数据库与 Brain 上下文 ($SESSION_ID)..."
+rsync -az "$AGY_DIR/conversations/${SESSION_ID}".db* "$MINI_HOST:~/.gemini/antigravity-cli/conversations/"
+if [ -d "$AGY_DIR/brain/${SESSION_ID}" ]; then
+  rsync -az "$AGY_DIR/brain/${SESSION_ID}/" "$MINI_HOST:~/.gemini/antigravity-cli/brain/${SESSION_ID}/"
+fi
+
+echo "==> [4/4] 在 Mac mini 的 tmux (agy) 会话中配置一键恢复别名..."
+ssh "$MINI_HOST" "grep -q 'alias agy-resume=' ~/.zshrc 2>/dev/null || echo \"alias agy-resume='agy --conversation ${SESSION_ID}'\" >> ~/.zshrc"
+
+echo "✅ 同步完成！"
+echo "   • 网页端工作台地址: https://agy.961504.xyz (或在中控台右上角点击 [>_ AGY 终端])"
+echo "   • 恢复当前完整会话: agy --conversation ${SESSION_ID}  (或直接输入: agy-resume / agy -c)"
+echo "   • 开启新会话(自带完整架构记忆): agy"