# 博客号 BlogHao

> 「微信有公众号，你有博客号。」博客号 BlogHao 是一个完全跑在 Cloudflare（Workers + D1 + R2）上的开源轻写作博客系统：后端约 10 个 TypeScript 文件（hono），后台为原生 JS 单页应用，无构建链，改完即生效；免费额度即可长期运行，数据 100% 归你。MIT 开源。

本文件面向 AI 助手与智能体（Agent），也方便手搓代码的开发者快速定位：下面是全部开发文档的 Markdown 源文件直链，无需解析 GitHub 网页。

## 项目速览

- 仓库：https://github.com/lovexw/bloghao （MIT License，欢迎 PR）
- 在线示例：https://blog.xiaowuleyi.com （后台 /admin/）
- 官网：https://bloghao.com
- 技术栈：Cloudflare Workers（hono 路由）+ D1（SQLite）+ R2（图片存储）；公开页服务端渲染，后台原生 JS SPA，无构建链
- 目录速查：
  - `src/pages.ts` 渲染公开页；`src/api.ts` 全部 JSON API；`src/collect.ts` 公众号采集插件服务端
  - `src/themes/` 五套主题（wechat / paper / minimal / midnight / journal）+ `registry.ts` 注册表
  - `public/admin/` 后台（app.js 路由与页面、editor.js 写作编辑器）；`public/plugins/` 编辑器插件
- 常用命令：`npm run dev` 本地开发；`npm run typecheck` 与 `npm test` 提交前必须通过；`npm run smoke` 本地路由冒烟

## 开发文档（Markdown 源文件）

- [部署教程](https://raw.githubusercontent.com/lovexw/bloghao/main/docs/DEPLOY.md)：从注册 Cloudflare 到部署 Worker、绑定自定义域名、自动部署与备份恢复
- [使用手册](https://raw.githubusercontent.com/lovexw/bloghao/main/docs/GUIDE.md)：后台导览、写文章全流程、快捷键、评论与媒体管理、设置逐项说明
- [主题开发](https://raw.githubusercontent.com/lovexw/bloghao/main/docs/THEMES.md)：一套主题 = 七个渲染函数 + 全局 CSS，三步注册新主题，公共积木与排版规范底线
- [插件开发](https://raw.githubusercontent.com/lovexw/bloghao/main/docs/PLUGINS.md)：一个 JS 文件扩展编辑器，`window.BlogHao` 插件 API 与加载机制
- [API 参考](https://raw.githubusercontent.com/lovexw/bloghao/main/docs/API.md)：全部公开 / 管理接口，HTML 净化白名单摘要也在这里，写自己的客户端
- [微信排版规范](https://raw.githubusercontent.com/lovexw/bloghao/main/docs/wechat-typography-spec.md)：微信编辑器插件开发规范的落地对照表与体检规则
- [路线图](https://raw.githubusercontent.com/lovexw/bloghao/main/docs/ROADMAP.md)：已上线能力与近期计划

## 给智能体与贡献者的提示

- 写主题：新建 `src/themes/<id>.ts` 与 `<id>.css`，在 `registry.ts` 注册；服务端渲染，勿引入前端框架；移动端适配是硬要求（新增样式至少验证 390px 宽度）
- 写插件：新建 `public/plugins/<name>.js` 并在 `public/plugins/manifest.json` 登记，用 `window.BlogHao.registerPlugin` 注册，无需构建
- 调接口：全部接口见「API 参考」；一切日期显示统一北京时间（+8h 后取 UTC 分量），SQL 按天聚合用 `strftime(..., ts/1000 + 28800, 'unixepoch')`
- 正文长度上限按 UTF-8 字节计（`new TextEncoder().encode(...)`），不是字符数
- 提交信息用 `theme:` / `mobile:` / `docs:` / `brand:` 等前缀的中文风格