diff --git a/README.md b/README.md
index 7997201..356769d 100755
--- a/README.md
+++ b/README.md
@@ -298,6 +298,22 @@ gateway 改为内部 HTTP 模式（[example.ini](gateway/example.ini) 中 `tls =
 
 与云原生微服务的差异：未引入服务注册发现、容器编排、消息总线，服务地址在 `waf/config.yaml` 与 `gateway/example.ini` 中静态配置。对于个人/中小规模的 DIY 场景，这种取舍在简洁性与可控性上是合理的。
 
+## 文档管理约定
+
+所有项目文档统一通过根目录 [docs/](docs/) 聚合管理，入口索引见 [docs/INDEX.md](docs/INDEX.md)。文档分类与存放规则如下：
+
+| 文档类型 | 存放位置 | 说明 |
+|----------|----------|------|
+| **模块 README** | 各模块根目录（如 `waf/README.md`） | 遵循行业惯例，方便 GitHub/IDE 直接识别，不移动 |
+| **安全审计报告** | `docs/security/` | 各模块的安全审计、部署审计、依赖审计、加固计划统一存放，文件命名为 `<模块名>_<文档类型>_<日期>.md` |
+| **代码审查日志** | `docs/reviews/` | 代码审查、评审记录统一存放 |
+| **分析报告** | `docs/reports/` | 各类分析报告（HTML/MD 等）统一存放 |
+| **全局文档** | `docs/` 根目录 | 全局审计总览、跨模块文档直接放在 `docs/` 下 |
+| **aibox 技能提示词** | `aibox/skills/`、`aibox/tasks/` | 属于运行时数据，保留在原目录 |
+| **虚拟环境/第三方文档** | `.venv/` 等 | 不纳入文档管理，由 `.gitignore` 排除 |
+
+新增模块文档时遵循以上规则：模块说明写本目录 `README.md`，审计/审查/报告类文档放入 `docs/` 对应子目录。
+
 ## 许可证
 
 各模块均采用 MIT License，详见各目录下的 `LICENSE`。
diff --git a/docs/INDEX.md b/docs/INDEX.md
new file mode 100644
index 0000000..8de0a64
--- /dev/null
+++ b/docs/INDEX.md
@@ -0,0 +1,135 @@
+# micro_servers 文档索引
+
+所有项目文档的统一入口。
+
+## 目录结构
+
+```
+docs/
+├── INDEX.md                              # 本文件（文档总索引）
+├── SECURITY_AUDIT_20260801.md            # 全局安全审计总览
+├── security/                             # 安全审计与加固相关
+├── reviews/                              # 代码审查日志
+└── reports/                              # 其他分析报告
+```
+
+---
+
+## 一、项目总览
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| 项目 README | [../README.md](../README.md) | 架构总览、服务说明、安装运行指南 |
+
+---
+
+## 二、安全文档 (`security/`)
+
+### 全局审计与加固
+
+| 文档 | 说明 |
+|------|------|
+| [SECURITY_AUDIT_20260801.md](security/SECURITY_AUDIT_20260801.md) | **全局总览** — 全模块安全审计汇总（问题等级定义、各模块问题汇总、修复跟踪） |
+| [DEPLOY_SECURITY_AUDIT_20260801.md](security/DEPLOY_SECURITY_AUDIT_20260801.md) | 部署配置安全审计（docker-compose、systemd、防火墙、TLS 等） |
+| [DEPS_SECURITY_AUDIT_20260801.md](security/DEPS_SECURITY_AUDIT_20260801.md) | 依赖安全审计（第三方库版本、已知漏洞、许可证） |
+| [SECURITY_HARDENING_PLAN.md](security/SECURITY_HARDENING_PLAN.md) | 安全加固计划（后续加固任务清单） |
+
+### 各模块安全审计报告
+
+| 模块 | 文档 | 审计范围 |
+|------|------|----------|
+| waf | [waf_SECURITY_AUDIT_20260801.md](security/waf_SECURITY_AUDIT_20260801.md) | Go WAF 网关（TLS、coraza、反向代理） |
+| gateway | [gateway_SECURITY_AUDIT_20260801.md](security/gateway_SECURITY_AUDIT_20260801.md) | C++20 应用网关（鉴权、Token、反向代理） |
+| core | [core_SECURITY_AUDIT_20260801.md](security/core_SECURITY_AUDIT_20260801.md) | C++20 进程托管服务（PMC/Nidus） |
+| db | [db_SECURITY_AUDIT_20260801.md](security/db_SECURITY_AUDIT_20260801.md) | Python 数据库服务（pymsg、SQLAlchemy、日志收集） |
+| pymsg | [pymsg_SECURITY_AUDIT_20260801.md](security/pymsg_SECURITY_AUDIT_20260801.md) | Python RPC 基础库（长度前缀帧、MsgClient/Server） |
+| dnfs | [dnfs_SECURITY_AUDIT_20260801.md](security/dnfs_SECURITY_AUDIT_20260801.md) | Python 树状菜单服务 |
+| static | [static_SECURITY_AUDIT_20260801.md](security/static_SECURITY_AUDIT_20260801.md) | Python 前端托管/文件服务 |
+| ai_review | [ai_review_SECURITY_AUDIT_20260801.md](security/ai_review_SECURITY_AUDIT_20260801.md) | Python AI 内容审核（DeepSeek + RAG） |
+| smtp | [smtp_SECURITY_AUDIT_20260801.md](security/smtp_SECURITY_AUDIT_20260801.md) | Python 邮件服务（验证码发送/校验） |
+| captcha | [captcha_SECURITY_AUDIT_20260801.md](security/captcha_SECURITY_AUDIT_20260801.md) | Python 验证码服务 |
+| confs | [confs_SECURITY_AUDIT_20260801.md](security/confs_SECURITY_AUDIT_20260801.md) | Python 统一配置服务 |
+| aibox | [aibox_SECURITY_AUDIT_20260801.md](security/aibox_SECURITY_AUDIT_20260801.md) | Python AI 智能体系统（WebSocket） |
+| aibox (历史) | [aibox_SECURITY_AUDIT.md](security/aibox_SECURITY_AUDIT.md) | aibox 早期安全审计 |
+| BotOps | [BotOps_SECURITY_AUDIT_20260801.md](security/BotOps_SECURITY_AUDIT_20260801.md) | BotOps 运维控制面板 |
+
+---
+
+## 三、代码审查 (`reviews/`)
+
+| 文档 | 说明 |
+|------|------|
+| [core_CODE_REVIEW_LOG_20260730.md](reviews/core_CODE_REVIEW_LOG_20260730.md) | Core 模块代码审查日志（2026-07-30，自动化审查） |
+
+---
+
+## 四、分析报告 (`reports/`)
+
+| 文档 | 说明 |
+|------|------|
+| [bot4cj_analysis_20260525_00.md](reports/bot4cj_analysis_20260525_00.md) | bot4cj 机器人模块分析报告（Markdown） |
+| [bot4cj_analysis_20260525_00.html](reports/bot4cj_analysis_20260525_00.html) | bot4cj 机器人模块分析报告（HTML） |
+
+---
+
+## 五、各模块 README（保留在原目录）
+
+各模块根目录的 `README.md` 保留在原位，方便 GitHub 直接浏览：
+
+### 核心服务
+
+| 模块 | 路径 | 说明 |
+|------|------|------|
+| core | [../core/README.md](../core/README.md) | 进程托管服务（PMC/Nidus） |
+| waf | [../waf/README.md](../waf/README.md) | WAF 网关（Go, coraza） |
+| gateway | [../gateway/README.md](../gateway/README.md) | 应用层网关（C++20） |
+| db | [../db/README.md](../db/README.md) | 通用数据库服务（pymsg） |
+| confs | [../confs/README.md](../confs/README.md) | 统一配置服务 |
+| static | [../static/README.md](../static/README.md) | 前端托管服务 |
+| dnfs | [../dnfs/README.md](../dnfs/README.md) | 树状网络文件系统 |
+| ai_review | [../ai_review/README.md](../ai_review/README.md) | AI 内容审核 |
+| captcha | [../captcha/README.md](../captcha/README.md) | 验证码服务 |
+| smtp | [../smtp/README.md](../smtp/README.md) | 邮件服务 |
+| redirect80 | [../redirect80/README.md](../redirect80/README.md) | HTTP 重定向服务 |
+
+### 共享库
+
+| 库 | 路径 | 说明 |
+|----|------|------|
+| pymsg | [../pymsg/README.md](../pymsg/README.md) | Python RPC 基础库 |
+| libhttp | [../libhttp/README.md](../libhttp/README.md) | C++ HTTP/WebSocket 库 |
+| libcrypt | [../libcrypt/README.md](../libcrypt/README.md) | C++ 加密库 |
+| libth | [../libth/README.md](../libth/README.md) | C++ 线程库 |
+| libsqlite3 | [../libsqlite3/README.md](../libsqlite3/README.md) | C++ SQLite3 封装 |
+
+### 其他模块
+
+| 模块 | 路径 | 说明 |
+|------|------|------|
+| aibox | [../aibox/README.md](../aibox/README.md) | AI 智能体系统 |
+| bot4cj | [../bot4cj/README.md](../bot4cj/README.md) | 机器人硬件脚本解析器（仓颉） |
+| BotOps | [../BotOps/README.md](../BotOps/README.md) | 运维控制面板 |
+| lci | [../lci/README.md](../lci/README.md) | LCI 交互式终端框架 |
+| tests | [../tests/blackbox/README.md](../tests/blackbox/README.md) | 黑盒测试套件 |
+
+### Robot 文档 (README.robot.md)
+
+| 模块 | 路径 |
+|------|------|
+| pymsg | [../pymsg/README.robot.md](../pymsg/README.robot.md) |
+| libhttp | [../libhttp/README.robot.md](../libhttp/README.robot.md) |
+| libtry | [../libtry/README.robot.md](../libtry/README.robot.md) |
+| aibox | [../aibox/README.robot.md](../aibox/README.robot.md) |
+| bot4cj | [../bot4cj/README.robot.md](../bot4cj/README.robot.md) |
+
+---
+
+## 六、aibox 技能与任务文档
+
+aibox 模块的技能提示词和任务模板属于运行时数据，保留在原目录：
+
+| 类型 | 路径 |
+|------|------|
+| 技能格式说明 | [../aibox/SKILLS_FORMAT.md](../aibox/SKILLS_FORMAT.md) |
+| 技能目录 | [../aibox/skills/](../aibox/skills/) |
+| 任务目录 | [../aibox/tasks/](../aibox/tasks/) |
diff --git a/bot4cj/docs/Reports/analysis_20260525_00.html b/docs/reports/bot4cj_analysis_20260525_00.html
similarity index 100%
rename from bot4cj/docs/Reports/analysis_20260525_00.html
rename to docs/reports/bot4cj_analysis_20260525_00.html
diff --git a/bot4cj/docs/Reports/analysis_20260525_00.md b/docs/reports/bot4cj_analysis_20260525_00.md
similarity index 100%
rename from bot4cj/docs/Reports/analysis_20260525_00.md
rename to docs/reports/bot4cj_analysis_20260525_00.md
diff --git a/core/docs/CODE_REVIEW_LOG_20260730.md b/docs/reviews/core_CODE_REVIEW_LOG_20260730.md
similarity index 100%
rename from core/docs/CODE_REVIEW_LOG_20260730.md
rename to docs/reviews/core_CODE_REVIEW_LOG_20260730.md
diff --git a/BotOps/docs/SECURITY_AUDIT_20260801.md b/docs/security/BotOps_SECURITY_AUDIT_20260801.md
similarity index 100%
rename from BotOps/docs/SECURITY_AUDIT_20260801.md
rename to docs/security/BotOps_SECURITY_AUDIT_20260801.md
diff --git a/docs/DEPLOY_SECURITY_AUDIT_20260801.md b/docs/security/DEPLOY_SECURITY_AUDIT_20260801.md
similarity index 100%
rename from docs/DEPLOY_SECURITY_AUDIT_20260801.md
rename to docs/security/DEPLOY_SECURITY_AUDIT_20260801.md
diff --git a/docs/DEPS_SECURITY_AUDIT_20260801.md b/docs/security/DEPS_SECURITY_AUDIT_20260801.md
similarity index 100%
rename from docs/DEPS_SECURITY_AUDIT_20260801.md
rename to docs/security/DEPS_SECURITY_AUDIT_20260801.md
diff --git a/docs/SECURITY_HARDENING_PLAN.md b/docs/security/SECURITY_HARDENING_PLAN.md
similarity index 100%
rename from docs/SECURITY_HARDENING_PLAN.md
rename to docs/security/SECURITY_HARDENING_PLAN.md
diff --git a/ai_review/docs/SECURITY_AUDIT_20260801.md b/docs/security/ai_review_SECURITY_AUDIT_20260801.md
similarity index 100%
rename from ai_review/docs/SECURITY_AUDIT_20260801.md
rename to docs/security/ai_review_SECURITY_AUDIT_20260801.md
diff --git a/aibox/SECURITY_AUDIT.md b/docs/security/aibox_SECURITY_AUDIT.md
similarity index 100%
rename from aibox/SECURITY_AUDIT.md
rename to docs/security/aibox_SECURITY_AUDIT.md
diff --git a/aibox/docs/SECURITY_AUDIT_20260801.md b/docs/security/aibox_SECURITY_AUDIT_20260801.md
similarity index 100%
rename from aibox/docs/SECURITY_AUDIT_20260801.md
rename to docs/security/aibox_SECURITY_AUDIT_20260801.md
diff --git a/captcha/docs/SECURITY_AUDIT_20260801.md b/docs/security/captcha_SECURITY_AUDIT_20260801.md
similarity index 100%
rename from captcha/docs/SECURITY_AUDIT_20260801.md
rename to docs/security/captcha_SECURITY_AUDIT_20260801.md
diff --git a/confs/docs/SECURITY_AUDIT_20260801.md b/docs/security/confs_SECURITY_AUDIT_20260801.md
similarity index 100%
rename from confs/docs/SECURITY_AUDIT_20260801.md
rename to docs/security/confs_SECURITY_AUDIT_20260801.md
diff --git a/core/docs/SECURITY_AUDIT_20260801.md b/docs/security/core_SECURITY_AUDIT_20260801.md
similarity index 100%
rename from core/docs/SECURITY_AUDIT_20260801.md
rename to docs/security/core_SECURITY_AUDIT_20260801.md
diff --git a/db/docs/SECURITY_AUDIT_20260801.md b/docs/security/db_SECURITY_AUDIT_20260801.md
similarity index 100%
rename from db/docs/SECURITY_AUDIT_20260801.md
rename to docs/security/db_SECURITY_AUDIT_20260801.md
diff --git a/dnfs/docs/SECURITY_AUDIT_20260801.md b/docs/security/dnfs_SECURITY_AUDIT_20260801.md
similarity index 100%
rename from dnfs/docs/SECURITY_AUDIT_20260801.md
rename to docs/security/dnfs_SECURITY_AUDIT_20260801.md
diff --git a/gateway/docs/SECURITY_AUDIT_20260801.md b/docs/security/gateway_SECURITY_AUDIT_20260801.md
similarity index 100%
rename from gateway/docs/SECURITY_AUDIT_20260801.md
rename to docs/security/gateway_SECURITY_AUDIT_20260801.md
diff --git a/pymsg/docs/SECURITY_AUDIT_20260801.md b/docs/security/pymsg_SECURITY_AUDIT_20260801.md
similarity index 100%
rename from pymsg/docs/SECURITY_AUDIT_20260801.md
rename to docs/security/pymsg_SECURITY_AUDIT_20260801.md
diff --git a/smtp/docs/SECURITY_AUDIT_20260801.md b/docs/security/smtp_SECURITY_AUDIT_20260801.md
similarity index 100%
rename from smtp/docs/SECURITY_AUDIT_20260801.md
rename to docs/security/smtp_SECURITY_AUDIT_20260801.md
diff --git a/static/docs/SECURITY_AUDIT_20260801.md b/docs/security/static_SECURITY_AUDIT_20260801.md
similarity index 100%
rename from static/docs/SECURITY_AUDIT_20260801.md
rename to docs/security/static_SECURITY_AUDIT_20260801.md
diff --git a/waf/docs/SECURITY_AUDIT_20260801.md b/docs/security/waf_SECURITY_AUDIT_20260801.md
similarity index 100%
rename from waf/docs/SECURITY_AUDIT_20260801.md
rename to docs/security/waf_SECURITY_AUDIT_20260801.md