diff --git a/README.md b/README.md
index d2ff2a4..6677f16 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,54 @@
-模块 README（133 个测试说明）
\ No newline at end of file
+# fault-log-analyzer
+
+HMS（主机监控系统）故障日志捕获与分析模块。
+
+依据 `docs/01-design/architecture.md`（5.3）、`database-design.md`（3/5）、
+`api-design.md`（6）实现四条主线：
+
+1. **故障日志捕获管道**：`logs.raw` → 级别/关键字/正则过滤 → 结构化解析
+   → MinHash 指纹去重 → 启发式归类 → 落库 → 可选生产 `logs.fault` / ES。
+2. **故障归类**：`fault_type.pattern` 正则优先 → 簇标注 → 关键字启发式兜底。
+3. **根因分析**：日志关键字 + 指标-故障规则库 + 时间窗口/主机关联 + 置信度评分。
+4. **REST API**：故障日志查询/详情/根因结论、故障类型、过滤规则管理。
+
+## 技术栈
+
+- Python 3.10+（核心逻辑零强制第三方依赖，纯标准库实现）
+- 可选后端：kafka-python / elasticsearch / pymysql / redis / numpy / scikit-learn
+
+## 目录结构
+
+```
+pyproject.toml / requirements.txt / README.md
+src/fault_log_analyzer/
+    __init__.py      # 包元信息
+    __main__.py      # CLI 入口
+    api.py           # REST API（http.server）
+    classifier.py    # fault_type 归类
+    cluster.py       # TF-IDF + DBSCAN 聚类
+    config.py        # 环境变量配置
+    filters.py       # fault_filter_rule 过滤
+    fingerprint.py   # MinHash 指纹 + 去重
+    integrations.py  # Kafka/ES/MySQL/Redis 可选适配
+    models.py        # 数据模型
+    parser.py        # 结构化解析 + 模板化
+    pipeline.py      # 捕获管道编排
+    root_cause.py    # 根因分析器
+    storage.py       # 存储抽象 + 内存实现
+    workers.py       # 聚类/根因分析 worker
+tests/               # 14 个测试模块
+```
+
+## 运行
+
+```bash
+# REST API（内存存储）
+python3 -m fault_log_analyzer --storage memory --api-host 127.0.0.1 --api-port 8080
+
+# 单元测试
+python3 -m unittest discover -s tests -v
+```
+
+## 测试
+
+`python3 -m unittest discover -s tests -v` → **Ran 132 tests，OK（0 失败）**。