diff --git a/README.md b/README.md
new file mode 100644
index 00000000..6bbd11dc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,80 @@
+# 大染志博客源码（toozhao.com）
+
+Hexo 6.3.0 + NexT 8.25 博客工程，部署在 GitHub Pages。
+
+- **`master` 分支** = 构建产物（纯静态 HTML），由 CI 自动更新，**不要手动改**
+- **`hexo-source` 分支** = 源码（本仓库默认分支），文章都写在这里
+- 发布规则：**push 到 hexo-source 即自动构建并上线**（GitHub Actions，1-2 分钟）
+
+## ✍️ 用 VSCode 写新博客
+
+```bash
+# 1. 第一次：拉取源码（含全部历史文章 + 主题配置）
+git clone -b hexo-source https://github.com/wahyd4/wahyd4.github.com.git toozhao-blog
+cd toozhao-blog
+code .
+```
+
+```markdown
+# 2. 在 source/_posts/ 目录新建文件，如 hello-world.md：
+---
+title: "文章标题"
+date: 2026-08-04 12:00:00
+tags: [科技, 生活]
+---
+正文直接写 Markdown……支持代码块、表格、图片、引用。
+```
+
+```bash
+# 3. 写完推送（不需要装 Node/Hexo，纯写 md 即可）
+git add .
+git commit -m "新文章：标题"
+git push origin hexo-source
+```
+
+推送后等 1-2 分钟，访问 https://toozhao.com 即可看到新文章。
+
+### 注意事项
+
+- **图片**：放到 `source/images/` 下，md 里写 `/images/文件名.jpg`
+- **日期格式**：`YYYY-MM-DD HH:MM:SS`，决定文章归档位置和 URL
+- **标签**：`tags: [a, b]`，不写也可以
+- **URL 规则**：`/年份/月/日/文件名/`（文件名即 URL 的一部分，尽量用英文/拼音）
+- 每次 push 前先 `git pull` 一次，避免冲突
+
+## 🗣️ 用 Discord 写新博客
+
+在频道 @小黑：「写博客：标题 + 内容」→ 小黑生成 markdown 并提交，同样走 push 即上线流程。
+
+## 🧰 常用命令（可选，本地调试用）
+
+```bash
+npm install          # 首次
+npx hexo server -p 4000   # 本地预览 http://127.0.0.1:4000
+npx hexo generate    # 手动构建到 public/
+npx hexo new "标题"   # 生成新文章模板
+```
+
+## 📁 目录结构
+
+```
+source/
+├── _posts/          # 全部文章（Markdown）
+├── _data/
+│   ├── head.njk     # 自定义 CSS（阅读排版/暗色模式）
+│   └── body-end.njk # 自定义 JS（字号调节）
+├── images/          # 图片资源
+├── about/ gallery/ recommend/ my-career/   # 静态页面
+└── tags/ categories/  # 标签/分类页
+_config.yml          # 站点配置
+_config.next.yml     # NexT 主题配置
+tools/publish-post.sh # 小黑发布脚本
+.github/workflows/deploy.yml  # CI：push 即构建部署
+```
+
+## 🔧 更新维护（小黑专用）
+
+- 逆向提取工具：`tools/extract_posts.py`（HTML 产物 → markdown）
+- 子路径预览构建：`npx hexo generate --config _config.yml,_config.preview.yml`
+- 线上验证：`gh api repos/wahyd4/wahyd4.github.com/pages/builds/latest`（status=built）
+- 详细坑位记录见 Hermes 技能 `hexo-blog-pipeline`