长文写随笔，短话发唠叨；记折腾、看影视、动起来——唠叨日常，也记录每一次改变。
惊蛰是一套用来记录工作、生活与各种折腾的开源个人博客系统。你可以随手发几句日常唠叨，认真写一篇随笔，留下技术折腾与备忘；也可以整理看过的电影和剧集，记录减肥路上的每一次运动与变化，再让 AI 帮你完成月度复盘。
它基于 Hugo、GitHub Actions 与可选 Serverless 服务构建，文章和生活数据统一保存在自己的 Git 仓库中。你可以从一个干净的静态博客开始，也可以按需增加网页写作、评论点赞、影视同步、运动可视化和 AI 总结。
本仓库同时是 Koobai 的真实生产站点、惊蛰的完整演示和可复用开源实现。Core 初始化工具可生成不包含 Koobai 真实内容与生产服务的最小站点；Publisher、Social、Life Data 和 AI Coach 可以按需启用。
- 生活时间线：随笔、唠叨和折腾备忘统一展示，并通过标签与分类组织内容。
- 自研 Hugo 主题：响应式设计，支持浅色、深色、跟随系统和图片灯箱。
- 轻量写作后台：解决静态博客不能在线发文的痛点，打开浏览器即可写随笔、发唠叨、预览 Markdown、保存草稿、上传图片并发布到 GitHub。
- 内容自己掌控：文章与公开生活数据保存在自己的 Git 仓库，并生成全文 RSS、JSON、Sitemap、Web App Manifest 和完整分享元数据。
- 评论与互动：支持评论、多层回复、点赞、表情和管理，并通过 Cloudflare Turnstile 降低滥用。
- 观影记录：增量同步豆瓣数据，以电影票形式展示评分、短评和观看时间。
- 运动与隐私：提供运动统计、月历、心率、Mapbox 轨迹、成就和海报，并用公共地标路线保护隐私运动。
- AI 运动复盘：生成月中与月末总结，只向模型发送经过过滤的聚合数据。
- 按需组合功能：Core 静态博客无需 Worker，写作、互动、生活数据和 AI 能力均可独立启用。
- AI 与自动化友好：支持直接交给 AI 初始化和部署，并通过 GitHub Actions 完成测试、同步、处理、构建与发布。
完整功能边界见功能与安装层级。
想快速部署？直接交给 AI： 把本仓库地址和可复制的部署指令发给支持读取 GitHub 仓库的 AI。它会先确认站点信息、功能层级和部署平台，从安全的 Core 开始，本地验证通过后再询问是否操作 GitHub 或 Cloudflare。
如果还需要自动同步运动数据，可以直接补充一句：帮我部署惊蛰博客和运动同步网关（Activity Sync Worker），并把我的 Keep/Health Connect 数据转换成 exercise-sync-v1 协议进行同步。
惊蛰提供五种逐步增强的使用层级。未配置的可选模块不会阻止核心博客运行。
| 层级 | 能力 | 额外依赖 |
|---|---|---|
| Core | 文章、唠叨、主题、标签、RSS、JSON | Hugo Extended |
| Publisher | 网页写作、图片上传、GitHub 写回、草稿 | 管理端 Worker、GitHub 凭据、图片存储 |
| Social | 评论、回复、点赞、Turnstile | Comments/Likes Worker 与 D1 |
| Life Data | 豆瓣同步、运动统计、地图与隐私路线 | Python、Mapbox、数据来源；自动运动同步可选运动同步网关（Activity Sync Worker） |
| AI Coach | 月中/月末 AI 运动复盘 | 模型 API 与隐私配置 |
当前生产站点使用 Full Profile，并由 koobai.com 作为唯一在线演示。Core Profile 不依赖 Worker，由初始化工具在新目录按需生成，不维护第二套演示站。
flowchart LR
A["Markdown / JSON"] --> R["GitHub 仓库"]
B["网页写作"] --> W["发布 Worker"]
W --> R
C["豆瓣同步"] --> R
D["原生 App / 数据源连接器"] --> ASW["运动同步网关"]
ASW --> R
R --> P["运动处理与 AI 月报"]
P --> R
R --> H["Hugo + 惊蛰 v3"]
H --> CF["Cloudflare Pages"]
H --> O["HTML / RSS / JSON / Sitemap"]
E["评论 / 点赞 Worker"] <--> V["访问者"]
CF --> V
详细说明见架构与模块契约。
- Git
- Hugo Extended 0.158.0 或更高版本
- Python 3.9 或更高版本仅用于运动处理和相关测试
git clone https://github.com/koobai/blog.git
cd blog
hugo server访问 Hugo 输出的本地地址即可查看站点。
当前仓库仍是 Koobai 的生产参考实现，因此部分图片、地图、评论、点赞和网页写作能力依赖 Koobai 的公开资源或私有服务。请勿把生产管理页面或生产接口当成通用安装方式。功能开关已经可用，通用 Worker 部署包位于 workers/，默认不会自动部署或切换 Koobai 的生产服务。
默认命令仍使用 Koobai Production 配置；原有本地预览和 Cloudflare 构建方式没有改变。
AI 或用户可在仓库外的新目录生成不读取 Koobai 内容、真实数据和 Worker 的最小站点：
python3 tools/jingzhe.py init --output ../my-jingzhe --title "我的站点"该目录仅在调用命令时生成，不是需要同步部署的第二个演示站。配置环境、功能开关和公开参数见配置说明。
构建输出目录、上线前检查和可选服务接入见部署说明。
生产构建：
hugo --minify --panicOnWarningPython 测试：
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -p 'test_*.py'JavaScript 语法检查：
node --check themes/jingzhe_v3/assets/js/pages/comments.js
node --check themes/jingzhe_v3/assets/js/exercise/*.js
node --check themes/jingzhe_v3/assets/js/pages/laodao.js
node --check themes/jingzhe_v3/assets/js/pages/movies.js
node tests/test_exercise_modules.jsWorker 行为测试：
node tests/test_workers.mjs统一检查：
python3 tools/jingzhe.py doctor
python3 tools/jingzhe.py validate
python3 tools/jingzhe.py check命令、JSON 输出、Core 初始化和 Starter 打包说明见 AI 工具链。
content/
├── posts/ # 长篇随笔
├── laodao/YYYY/MM/ # 短动态
└── pages/ # 关于、观影、运动和管理页面
assets/
├── movie.json # 观影数据
├── activities.json # 处理后的运动展示数据
├── landmark_route_library.json
└── monthly_insights.json # 月度统计与 AI 报告
data/exercise/
└── activities.json # 来源无关的原始运动事实
themes/jingzhe_v3/ # 当前生产主题及可指纹化的项目自有脚本
static/js/ # 按许可证原样保留的第三方浏览器脚本
workers/ # 五个独立 Worker、Wrangler 示例、D1 迁移与 OpenAPI
config/ # 通用、生产与开发配置
schemas/ # Front Matter、参数和 JSON Schema
data/jingzhe/features.json # 机器可读功能注册表
jingzhe/ # 运动处理、月报与共享契约模块
.github/workflows/ # 测试、同步、处理、构建和部署工作流
开源整理不会要求 Koobai 改变现有发布习惯。下列行为属于兼容基线：
/newlaodao和/newsuibi的使用方式保持不变。content/posts/、content/laodao/YYYY/MM/等内容路径保持不变。- 已有 Front Matter、永久链接、评论 URL 与点赞 URL 保持兼容。
- 浏览器草稿、登录、主题和点赞所使用的 LocalStorage Key 保持兼容。
- Worker 路由、Header 和请求字段在完成兼容测试前不改变。
- GitHub Actions 依赖的提交信息和 Secrets 名称不擅自改变。
- 豆瓣、原生 App、运动处理、AI 月报和 Cloudflare Pages 流程继续运行。
完整约束见生产兼容基线。
AI 编程助手在修改仓库前必须先阅读 AGENTS.md。该文件定义了：
- 源文件与生成文件边界。
- 不可破坏的生产兼容契约。
- Secrets 和隐私规则。
- 不同类型改动必须运行的检查。
- Worker 的最小权限、Secret、隐私和生产迁移边界。
第一次使用建议从 AI 快速开始 进入；维护和二次开发规则见 AI 安装与维护协议。
- 文档入口
- AI 快速开始
- 架构与模块契约
- 生产兼容基线
- 功能与安装层级
- 隐私与外部数据边界
- AI 安装与维护协议
- AI 工具链
- 配置、Profile 与 Core 初始化
- 部署说明
- Worker 部署与安全边界
程序代码、惊蛰主题、工具、Worker、技术文档和 Core 合成示例采用 MIT License。Koobai 的真实文章、个人数据和图片保留所有权利，详见内容授权边界；Koobai 名称、头像与 Logo 不包含在 MIT 授权中，详见品牌说明。第三方浏览器脚本的版本、哈希与许可证副本见 Third-party Notices。