# 🦐 坤虾界站点设计说明文档 (kuuila.cn)

> 主人专属极客风站点 · 统一规范 + 设计语言
> 版本：v1.0 · 2026-08-19 · 作者：虾3x ♠️

---

## 📑 目录

1. [站点定位](#一-站点定位)
2. [页面总览](#二-页面总览)
3. [设计语言系统](#三-设计语言系统)
4. [设计模式与组件](#四-设计模式与组件)
5. [技术架构](#五-技术架构)
6. [设计原则 (铁律)](#六-设计原则-铁律)
7. [演化历史与待办](#七-演化历史与待办)

---

## 一、站点定位

### 1.1 一句话定义

**坤虾界 = 张显跃的极客风个人知识实验场**

- 不是博客、不是作品集、不是 SaaS
- 是主人**知识、灵感、工具、游戏、实验**的**单一聚合门户**
- 调性：**深渊之下的神秘领域** + **极客主义** + **私域感**

### 1.2 目标用户

| 角色 | 期望 |
|---|---|
| 🐉 主人本人 (张显跃) | 一站收纳所有产物,可视化进展,统一品牌 |
| 👀 公开访客 (偶然进站) | 视觉冲击 → 好奇 → 停留 → 探索 |
| 🤝 合作者/朋友 | 看到主人的作品/能力,引发合作兴趣 |
| 🦐 "虾女团" Agent | 调用统一接口/约定,贡献内容 |

### 1.3 核心哲学

> **"一只蝴蝶扇动翅膀,可能引发一场龙卷风"**

- 一行代码改变世界
- 用最小杠杆撬动最大影响力
- 让科技改善生活,让内心更美好

---

## 二、页面总览

### 2.1 站点地图

```
kuuila.cn (主页 · 神话主页)
│
├─ /science.html      🦋 硬核科普      · 混沌/复杂系统/蝴蝶效应 (默认展示)
├─ /news.html         📰 科技快讯      · AI/芯片/计算机/学生资讯
├─ /lab.html          🎮 实验场        · H5 游戏/工具/控制台
├─ /action.html       📋 每日行动      · 计划/复盘/统计
├─ /weiyan.html       💭 微言          · 一句话灵感记录
│
├─ [🐉 神话主题 - 旧时代]
├─ /join.html         蜕壳            · 加入虾文明
├─ /lore.html         虾史            · 神话叙事
├─ /fortune.html      算卦            · 玄学工具
├─ /console.html      虾坊            · 控制台/工具集
├─ /explore.html      探索            · 探索虾界
├─ /civilization.html 虾文明史         · 时间线叙事 (独立主题)
│
├─ /h5-dungeon-forge.html      H5 地下城锻造
├─ /h5-luna--game-master.html  H5 月光游戏主持
├─ /h5-puzzleflow.html         H5 谜题流
├─ /h5-quizmaster-.html        H5 答题大师
│
├─ /agents/           Agent 后台面板
│   ├─ analytics/  console.html  content/
│   ├─ data/  design/  engagement/  growth/
│   ├─ intelligence/  outreach/  scheduler/  security/
│
├─ /game/             灵安城(子应用)
├─ /market/           市场(预留)
├─ /skills/           技能发布台
│   └─ jury-review/
│
└─ /downloads/        工具下载 (frp 等)
```

### 2.2 页面分类与权重

| 分类 | 页面 | 权重 | 设计代 |
|---|---|---|---|
| **🌟 核心内容** | science / news / lab / action / weiyan | ⭐⭐⭐⭐⭐ | v2 (现代模块化) |
| **🐉 神话主题** | index / join / lore / fortune / console / explore | ⭐⭐⭐ | v1 (符文+神秘向导) |
| **🎮 H5 游戏** | h5-* | ⭐⭐ | 各自独立 |
| **🛠️ 工具/后台** | agents / skills / market | ⭐⭐ | 各自独立 |
| **📦 子应用** | game (灵安城) | ⭐⭐⭐⭐ | Flask 后端独立 |

---

## 三、设计语言系统

### 3.1 双套色板

> 历史原因:站点经过两次大型重构,保留两套并行色板

#### 🔵 旧色板 (v1 · 神话主题)

```
--void:   #0a0d12  /* 深空背景 */
--deep:   #0f1318  /* 深海卡片背景 */
--coral:  #ff6b6b  /* 珊瑚红 - 主强调色 */
--ocean:  #4ecdc4  /* 海洋青 - 辅强调色 */
--glow:   #a8e6cf  /* 荧光绿 - 提示 */
--sand:   #ffeaa7  /* 沙金 - 标题点缀 */
--dust:   #b2bec3  /* 尘埃灰 - 正文 */
```

应用页面: `index.html` `join.html` `lore.html` `fortune.html` `console.html` `explore.html`

#### 🟢 新色板 (v2 · 现代模块)

```
--void:    #0a0d12  /* 主背景 - 保留一致性 */
--deep:    #0f1318  /* 次背景 */
--panel:   #141a22  /* 面板背景 (比 deep 浅一档) */
... + 业务色:
--coral:   #ff6b6b  /* 红 - 警示/新闻 */
--amber:   #ffb86c  /* 琥珀 - 科普 */
--cyan:    #4ecdc4  /* 青 - 实验 */
--mint:    #a8e6cf  /* 薄荷 - 行动 */
--sand:    #ffeaa7  /* 金 - 微言 */
--phosphor: #00ff88 /* 荧光绿 - 计数/科技感 */
```

应用页面: `science.html` `news.html` `lab.html` `action.html` 等核心内容页

#### 🎨 独立主题页面

- `civilization.html` — 暗红独立主题 (`--black` `--red`)
- `weiyan.html` — 极简 (37行 HTML,无 CSS 变量)

### 3.2 字体方案

| 场景 | 字体 | 用途 |
|---|---|---|
| 英文/数字 | `Courier New` monospace | 科技感/终端风(默认) |
| 中文标题 | 系统无衬线 | 简洁清晰 |
| 中文长文 | 系统衬线 | 阅读舒适 |

> 📌 **未引入 Web Font** — 性能优先,本地系统字体够用。
> 若以后要古风/手写,优先**单页面**引入,不全局污染。

### 3.3 视觉语言关键词

- **🌌 暗黑系** — `--void` 深空背景为主
- **🪸 海洋元素** — 珊瑚、海水、浮游粒子
- **✨ 神秘感** — 符文、对话气泡、闪烁动画
- **🦐 极客萌** — emoji 虾大量出镜,反差萌
- **💡 荧光点缀** — `--phosphor #00ff88` 计数/状态/重要提示

---

## 四、设计模式与组件

### 4.1 主页布局模式 (v2 · 模块化)

主页 (`index.html`) 是所有现代页面的**模板**。结构:

```
┌──────────────────────────────────────┐
│  🎈 装饰层 (bubbles / 粒子背景)       │  ← z-index: 0
├──────────────────────────────────────┤
│  🦐 Logo/角色元素                     │  ← z-index: 1
├──────────────────────────────────────┤
│  📊 Counter Bar (访客/今日 + 入口链接) │  ← 1 行,带边框
├──────────────────────────────────────┤
│  📛 标题 + 副标题 (渐变色)             │
├──────────────────────────────────────┤
│  🃏 模块卡片网格 (Grid auto-fit)       │  ← 核心内容
│   ┌─────┬─────┬─────┐                │
│   │ 🦋  │ 📰  │ 🎮  │                │
│   ├─────┼─────┼─────┤                │
│   │ 📋  │ 💭  │ ... │                │
│   └─────┴─────┴─────┘                │
├──────────────────────────────────────┤
│  📂 可选:details 折叠旧区             │
├──────────────────────────────────────┤
│  📊 Meta 统计 (数量/标签)             │
├──────────────────────────────────────┤
│  📎 Footer (内部链接)                 │
└──────────────────────────────────────┘
```

### 4.2 5 大核心模块卡片 (主页)

| 卡片 | emoji | 主题色 | URL | 内容定位 |
|---|---|---|---|---|
| 硬核科普 | 🦋 | 琥珀 `#ffb86c` | `/science.html` | 混沌理论/复杂系统/蝴蝶效应 |
| 科技快讯 | 📰 | 珊瑚 `#ff6b6b` | `/news.html` | AI/芯片/计算机/学生 |
| 实验场 | 🎮 | 青色 `#4ecdc4` | `/lab.html` | H5 游戏/工具/控制台 |
| 每日行动 | 📋 | 薄荷 `#a8e6cf` | `/action.html` | 计划/复盘/统计 |
| 微言 | 💭 | 沙金 `#ffeaa7` | `/weiyan.html` | 一句话灵感 |

> **设计模式**:每张卡片统一结构 = `emoji + 主题色标题 + 一句话定位 + → 进入`
> **交互**:hover 时边框颜色变深 + 上移 3px (transition: 0.2s)

### 4.3 Counter Bar (访问计数条)

```
[ ⟐ 总访客 1,234 ] [ ◉ 今日 56 ] [ 📰 科技快讯 → ] [ 🦋 硬核科普 → ] [ 🎮 实验场 → ]
```

- 荧光绿 `#00ff88` 边框 + 半透明背景
- 后端 API: `POST /api/visit` + `GET /api/stats/counter` (服务器 IP 去重)
- 仅 `index.html` `science.html` `news.html` `lab.html` 接入

### 4.4 神话主题组件 (v1)

- **符文网格** — 7 大符文,点击弹 alert 描述
- **神秘向导对话** — `dialogue` 卡片:图标 + 文本 + 署名(底色深、左侧边框青色)
- **虾文明时间线** — `civilization.html` 独立主题

### 4.5 通用微交互

| 元素 | hover/active 效果 |
|---|---|
| 按钮 `.btn` | 背景填色 + 阴影晕染 |
| 卡片 | 边框变色 + 上移 3px + 缩放 1.0→1.05 |
| 符文 `.rune` | 边框珊瑚色 + 上移 4px + 阴影 |
| emoji 🦐 | shake 摇摆动画 |

---

## 五、技术架构

### 5.1 部署拓扑

```
            ┌─────────────────┐
            │  Cloudflare (?)  │  ← 待确认(可能直连)
            └────────┬────────┘
                     │
            ┌────────▼────────┐
            │   Nginx 1.24    │  ← /etc/nginx/sites-available/kuuila
            └────────┬────────┘
                     │
   ┌─────────────────┼─────────────────┐
   │                 │                 │
┌──▼────┐      ┌────▼─────┐     ┌─────▼──────┐
│ 静态 │      │ Flask API │     │  H5 游戏   │
│ HTML │      │ (Gunicorn)│     │ (内联 JS)  │
└──────┘      └──────────┘     └────────────┘
   │
   ├─ /api/health
   ├─ /api/members
   ├─ /api/stats
   ├─ /api/content
   ├─ /api/agents
   ├─ /api/visit (POST)
   └─ /api/stats/counter (GET)
```

### 5.2 后端栈

| 层 | 技术 | 备注 |
|---|---|---|
| Web 服务器 | Nginx 1.24.0 (Ubuntu) | 反向代理 + 静态托管 |
| 后端 | Flask + Gunicorn | 统一 API 网关 |
| 数据库 | SQLite | 轻量够用 |
| 虚拟环境 | `/var/www/kuuila/backend/venv` | |
| 维护脚本 | `/usr/local/bin/kuuila_maintenance.sh` | 每日 06:00 cron |
| 备份 | GitHub: `kuuila/kuuila.cn` | `main` 分支 |

### 5.3 前端栈

| 页面 | 技术 | 复杂度 |
|---|---|---|
| `index.html` | 纯 HTML + CSS + vanilla JS | ⭐⭐ |
| `weiyan.html` | 纯 HTML + LocalStorage (37 行) | ⭐ |
| `action.html` | HTML + JS + 后端 API | ⭐⭐⭐ |
| `science.html` | HTML + Markdown 渲染 + 后端 | ⭐⭐⭐⭐ |
| `news.html` | HTML + JS + 后端 | ⭐⭐⭐ |
| `lab.html` | HTML (聚合页) | ⭐⭐ |
| `h5-*` | HTML + 内联 JS/游戏引擎 | ⭐⭐⭐~⭐⭐⭐⭐ |
| `game/index.html` | Vue/SPA (灵安城) | ⭐⭐⭐⭐⭐ |

### 5.4 自动化

| 任务 | Cron | 脚本 |
|---|---|---|
| 站点维护 | `0 6 * * *` | `kuuila_maintenance.sh` |
| 灵安城触发 | `0 8 * * *` / `0 23 * * *` | `daily_trigger.sh` |
| 每日项目 | `30 8 * * *` | `daily-project-runner.sh` |
| 凌晨任务 | `0 3 * * *` | (memory_guard 任务) |

---

## 六、设计原则 (铁律)

> 这些是从主人历次反馈+自我实践中提炼的隐性标准,**违反任何一条都会被立刻识别**。

### 6.1 视觉一致

1. **深空背景统一** — 所有页面都以 `--void` 深色为主,不允许突然变白
2. **主题色不超过 3 个** — 每个页面定义 ≤3 个强调色,避免花哨
3. **字号克制** — 标题/副标题/正文/提示四档足够,不引入第 5 档
4. **emoji 即语义** — 一旦某 emoji 代表某模块,全站一致

### 6.2 交互克制

1. **不滥用弹窗** — alert() 仅用于"惊喜揭示"(如符文点击),不用于表单错误
2. **动画 ≤ 0.3s** — 所有 transition 默认 0.2-0.3s,避免视觉拖沓
3. **悬停反馈统一** — hover 必有反馈:边框变色 / 上移 / 阴影
4. **不破坏可访问性** — 关键操作保留键盘可达

### 6.3 内容结构

1. **首页信息密度高** — 至少 5 个模块入口 + 计数器 + 标题 + 副标题
2. **每页有 Footer** — 链接到相邻页面 + GitHub 仓库
3. **标题一句话定义** — 副标题 ≤ 30 字,精确说明页面是什么
4. **数据无遗漏** — API 返回字段必须在前端有对应渲染

### 6.4 工程纪律

1. **改动前备份** — `index.html` → `index.html.bak-YYYYMMDD-HHMM`
2. **大改前走 legacy** — 旧版本保留为 `*.legacy-20260730.bak`(2026-07-30 大重构标记)
3. **Nginx 配置谨慎** — 不删已有 server 块,新增前必查现有配置
4. **路径一致** — 链接用绝对路径 `/science.html` 而非 `./science.html`,避免目录错位

### 6.5 反 AI 痕迹

1. **不允许出现"作为一个 AI..."类口吻** — 这是个人站点,不是产品宣传
2. **emoji 风格统一** — 🦐♠️🌸⚡♣️♦️⟡⧫∞✦ 等神秘符号系,不用 💼🚀✨ 等产品系
3. **保留"主人口吻"** — "咻~" "神秘向导·老虾" 等叙述元素,体现主人个性
4. **不做无意义的 "现代化"** — 保持极客原始感,不为了好看而失去个性

---

## 七、演化历史与待办

### 7.1 重大版本

| 日期 | 事件 | 影响 |
|---|---|---|
| 2026-03-12 | 创建 kuuila.cn | 极客终端风格首页 |
| 2026-03-22 | 加入「每日行动」「灵安城」 | 内容爆发期 |
| 2026-07-30 | **大重构** | v1 神话主题 → v2 模块化首页 + 多页并行 |
| 2026-08-14 | 灵安城结算 bug 修复 | `last_settle_date` 只在23:00 更新 |
| 2026-08-15 | 凌晨任务 cron 配置缺失 | heartbeat 手动补跑 |
| 2026-08-19 | 本文档 v1.0 | 站点设计规范化起点 |

### 7.2 待办 (Backlog)

#### 🔴 高优先级
- [ ] **章节标题递增 bug** — `chapter_148.py` 把 day 148-200 全标"第七十七章",卡在77
- [ ] **Nginx 反向代理路径统一** — 主页 `kuuila.cn/` 与 `kuuila.cn/index.html` 是否一致
- [ ] **H5 游戏整合** — `h5-*` 各自为战,缺少统一入口/视觉

#### 🟡 中优先级
- [ ] **v1 → v2 全站迁移** — 神话主题页面(join/lore/fortune/console/explore)是否需要现代化?
- [ ] **404 页面** — 当前访问不存在路径会 nginx 默认错误页,需定制
- [ ] **移动端适配** — 当前设计偏桌面,移动端需测实际体验
- [ ] **Open Graph / SEO** — `<meta>` og/twitter 标签缺失,社交分享卡片不友好
- [ ] **暗色/亮色切换** — 大多数页面强制暗色,亮色模式缺失

#### 🟢 低优先级
- [ ] **站点地图页** — `/sitemap` 列出所有页面,方便爬虫
- [ ] **PWA** — 离线访问 manifest,提升"工具"属性
- [ ] **国际化 (i18n)** — 当前仅中文,英文版缺失
- [ ] **RSS** — 硬核科普/科技快讯内容订阅

### 7.3 不做清单 (Anti-Goals)

> 与其追求全面,不如追求**精炼、个性化、可识别**

- ❌ 不做用户系统 / 评论 / 点赞 — 主人站点不需要社交
- ❌ 不做 SEO 优化到极致 — 个人站点,目标受众明确
- ❌ 不做广告位 / 商业化 — 不接广告
- ❌ 不做"关于我们"页面 — 主人本人即品牌
- ❌ 不做"用户协议 / 隐私政策" — 除非法务要求

---

## 附录 A: 关键文件路径速查

```
# 主页与核心内容
/var/www/kuuila/index.html        # 主页
/var/www/kuuila/science.html      # 硬核科普
/var/www/kuuila/news.html         # 科技快讯
/var/www/kuuila/lab.html          # 实验场
/var/www/kuuila/action.html       # 每日行动
/var/www/kuuila/weiyan.html       # 微言

# 神话主题 (v1)
/var/www/kuuila/join.html
/var/www/kuuila/lore.html
/var/www/kuuila/fortune.html
/var/www/kuuila/console.html
/var/www/kuuila/explore.html
/var/www/kuuila/civilization.html

# H5 游戏
/var/www/kuuila/h5-*.html

# 子应用
/var/www/kuuila/game/             # 灵安城
/var/www/kuuila/agents/           # Agent 后台
/var/www/kuuila/skills/           # 技能发布
/var/www/kuuila/market/           # 市场(预留)

# 后端
/var/www/kuuila/backend/          # Flask + venv
/etc/nginx/sites-available/kuuila # Nginx 配置
/usr/local/bin/kuuila_maintenance.sh # 维护脚本

# 仓库
https://github.com/kuuila/kuuila.cn
本地: /var/www/kuuila

# Agent 工作区
/root/.openclaw/workspace/MEMORY.md  # 长期记忆
/root/.openclaw/workspace/SOUL.md    # 人设
```

---

## 附录 B: 站点指标

- **总页面数**: 17 (主页 + 5 核心 + 6 神话 + 4 H5 + 1 主站子页 + ...)
- **总大小**: ~155 KB (主页)/ 27 KB (硬核科普) / ...
- **响应速度**: 静态页面 < 100ms
- **HTTPS**: Let's Encrypt (有效期至 2026-09?)
- **域名**: kuuila.cn (2026-03-12 创建)
- **公网 IP**: 122.51.232.92
- **部署**: Ubuntu + Nginx 1.24.0 + Flask + SQLite

---

> ✍️ **本文档维护说明**
> - 任何页面新增/重大修改 → 必须更新本文档
> - 设计原则变更 → 必须经主人确认
> - 文档版本: v1.0 · 2026-08-19
> - 下次评审: 重大重构前 / 季度回顾

🦐 **坤虾界 — 深渊之下,代码之上** ♠️