diff --git a/README.md b/README.md
index 9962f56..a0c1a87 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,129 @@
-个人娱乐bot，自己随便写点小功能
\ No newline at end of file
+# 禾汐 (HeXi)
+
+基于 **NoneBot2** 的个人娱乐 QQ 机器人,使用 **OneBot V11** 协议接入。集成了游戏战绩查询、群聊学习、每日打卡、人设卡、表情包等大量功能,以插件化方式组织,方便增删。
+
+## ✨ 功能特性
+
+### 🎮 游戏相关
+
+| 插件 | 功能 | 主要命令 |
+| --- | --- | --- |
+| `nonebot_plugin_bf_bot` | 战地系列 (BF3/BF4/BF1/BFV/BF2042/BF6) 战绩查询,PIL 生成统计卡片 | `/bft` `/bfbind` `/unbind` `/update_bind` |
+| `nonebot_plugin_deadlock` | Deadlock 战绩、段位、近期比赛查询 | `/nekoscore` `/nekobind` `/nekounbind` `/nekorank` `/nekomatch` |
+| `nonebot_plugin_steam_info` | Steam 玩家信息、库存、游戏时长查询 | `/steamhelp` `/steambind` `/steaminfo` `/steamplaytime` 等 |
+| `nonebot_plugin_helldivers_tools` | 绝地潜兵 2 前线战况简报、星球详报、随机战备推荐 | `/简报` `/详报` `/随机战备` |
+| `nonebot_plugin_brash_general_supercredits_tools` | 绝地潜兵 超级积分查询 | — |
+| `nonebot_plugin_mc_server_status` | Minecraft 服务器状态查询 | `/信息` `/信息数据` |
+| `nonebot_plugin_ncm_saying` | 网易云音乐热评(网抑云) | `/网抑云` |
+| `nonebot-bison` | Bilibili / 微博等订阅推送 | — |
+
+### 💬 聊天娱乐
+
+| 插件 | 功能 | 主要命令 |
+| --- | --- | --- |
+| `nonebot_plugin_learning_chat` | 马尔可夫链群聊学习:被动学习群消息并模仿回复,定时主动发言;附 Vue 3 Web 管理后台 | — |
+| `nonebot_plugin_galgame_card` | 群友"人设卡"生成与展示,带 Web 管理后台 | — |
+| `nonebot_plugin_group_tools` | 群工具集(头像、表情、签到素材、游戏素材图等) | — |
+| `nonebot_plugin_dailywife` | 每日随机抽取群友当"老婆" | `/今日老婆` |
+| `nonebot_plugin_deer_pipe` | 每日打卡(鹿)与打卡记录,日历可视化 | `/打卡记鹿` `/查询记录` |
+| `nonebot_plugin_makeaquote` | 生成"名言"引用图片 | — |
+| `memes_ops` | 表情包运营/管理 | — |
+| `nonebot_plugin_random_jm_code` | 随机 JM 本子代码 | `/jm` |
+| `nonebot_plugin_dice` | 骰子掷点 | — |
+
+### 🛠️ 实用工具
+
+| 插件 | 功能 | 主要命令 |
+| --- | --- | --- |
+| `nonebot_plugin_hexi_core` | 核心库:消息解析、权限分级、限流器 (token bucket)、命令冷却、热插件管理 | — |
+| `nonebot_plugin_voice_trans` | 语音消息转文字 | `/voice` |
+| `nonebot_plugin_video_analysis` | 视频链接解析 | — |
+| `nonebot_plugin_regif` | GIF 注册与处理 | — |
+| `nonebot_plugin_picfinder_take` | 识图(Playwright 驱动) | — |
+| `nonebot_plugin_picstatus` | 头像状态图生成 | — |
+| `nonebot_plugin_group_daily_analysis` | 群聊行为分析报告 | `/群分析` |
+| `nonebot_plugin_web_hub` | 统一 Web 管理入口 | — |
+
+## 🚀 快速开始
+
+### 环境要求
+
+- Python **3.10+**,使用 [Poetry](https://python-poetry.org/) 管理依赖
+- 一个 OneBot V11 实现(如 [NapCat](https://github.com/NapNeko/NapCatQQ)、Lagrange)作为 QQ 接入端
+
+### 安装与启动
+
+```bash
+# 安装依赖
+poetry install
+
+# 配置环境变量(见下节),然后启动
+poetry run python bot.py
+```
+
+- **开发**:使用 `.env.dev`(监听 `127.0.0.1:11011`,昵称 Elika)
+- **生产**:复制为根目录 `.env` 后启动(监听 `0.0.0.0:39697`,超级用户 `2931589710`,昵称 爱丽丝)
+
+`.env` / `.env.dev` 均已被 `.gitignore` 排除,包含凭据的文件不会进入仓库。
+
+## ⚙️ 配置
+
+启动时 NoneBot 自动加载根目录 `.env` 文件,主要变量:
+
+| 变量 | 说明 |
+| --- | --- |
+| `HOST` / `PORT` | 监听地址与端口 |
+| `SUPERUSERS` | 超级用户 QQ 号 |
+| `NICKNAME` | 机器人昵称 |
+| `COMMAND_START` / `COMMAND_SEP` | 命令前缀与分隔符 |
+| `DRIVER` | NoneBot 驱动器(httpx + fastapi + websockets) |
+| `ONEBOT_ACCESS_TOKEN` | OneBot 接入鉴权 token |
+| `DATASTORE_*` | 数据目录(localstore 统一指向 `hexi/data/` 等) |
+| `SENTRY_DSN` / `SENTRY_ENVIRONMENT` | Sentry 错误上报(可选) |
+| `BISON_*` | Bison 订阅推送配置 |
+
+各插件专属配置(Steam API key、网易云 cookie、识图等)按需在 `.env` 中补充,详见各插件文档。
+
+## 📁 目录结构
+
+```
+HeXi/
+├── bot.py  pyproject.toml  README.md
+├── hexi/
+│   ├── plugins/      # 全部插件(nonebot.load_plugins("hexi") 加载)
+│   ├── data/         # 运行数据(不入库)
+│   ├── config/       # 业务配置(不入库)
+│   ├── resource/     # 全局静态资源(fonts/ 字体、menu_config 等)
+│   ├── web/          # 统一 Web 前端(Vue 3)
+│   ├── logs/         # 日志(不入库)
+│   └── web_*.py      # Web 管理相关(鉴权、插件注册)
+├── docs/             # 插件开发标准文档
+├── tests/            # pytest 测试
+└── plugin_template/  # 新插件脚手架模板
+```
+
+- **数据库**:`hexi/data/data.db`(datastore)、`hexi/data/nonebot_plugin_orm/db.sqlite3`(orm,各插件表)
+- **群聊学习数据**:`hexi/data/record.json` + `inverted_index.json`(马尔可夫链)
+- **本地插件数据**通过 localstore 统一收进 `hexi/data/`,避免散落根目录
+
+## 🧪 测试与开发
+
+```bash
+poetry run pytest          # 运行测试(tests/,asyncio auto 模式)
+poetry run black .         # 格式化
+poetry run isort .         # import 排序
+poetry run ruff check .    # lint
+poetry run pyright         # 类型检查
+```
+
+> ⚠️ 测试文件必须放在 `tests/`,**不要**放进 `test/` —— `pyproject.toml` 中 `test` 是插件目录,NoneBot 启动时会把其中所有文件当插件加载。
+
+新增插件请参考:
+
+- [插件结构标准](docs/plugin-structure-standard.md)
+- [插件配置标准](docs/plugin-config-standard.md)
+- `plugin_template/` 脚手架模板
+
+## 📄 许可
+
+MIT(`pyproject.toml` 声明,仓库未附带 LICENSE 文件)