docs & ui: 完善 captcha/aibox 文档，登录注册改为邮箱制

- captcha/README.md: 补充字段级接口文档与错误码表
- aibox/README.md: 对照 main.py 源码核对修正（入口/模型/工具/配置）
- static/public/login.html & register.html: 用户名改为邮箱
- static/public/js/register.js: 合并注册页双邮箱框为单一邮箱字段

aibox/README.md

@@ -1,21 +1,24 @@
 # 单AI智能体系统 - WebSocket版本（增强版）
 
-一个功能强大的AI智能体系统，通过WebSocket与客户端交互，支持文件操作、网页访问、记忆管理、任务调度、扩展技能等功能。所有任务都通过AI对话执行，支持实时流式输出和任务状态广播。
+一个基于 DeepSeek API 的**单 AI 智能体**系统，通过 WebSocket 与客户端交互。所有任务（文件操作、网页访问、记忆管理、任务调度等）都由 AI 对话驱动执行，支持实时流式输出与任务状态广播。内置可热重载的技能系统，智能体可通过工具自我进化（更新角色定义、自主创建技能）。
+
+> 本模块为 `micro_servers` 项目中的独立组件，由 `core`（`PMC`）通过 `init.txt` 中的 `bash /opt/micro_servers/aibox/_run.sh` 拉起。它与主干微服务（waf/gateway/static/dnfs/db/ai_review）解耦，是另一套 AI 助手产品。
 
 ## ✨ 核心特性
 
-- 🤖 **单AI智能体**：基于DeepSeek API的智能对话系统，支持思考模式
-- 🔌 **WebSocket通信**：实时双向通信，支持流式输出和任务状态广播
-- 📁 **文件操作**：读写文件、目录列表（支持大文件分页）
-- 🌐 **网页访问**：获取网页内容、提取标题、链接、搜索信息
-- 🧠 **记忆管理**：自动保存和检索对话记忆，保持对话连贯性
+- 🤖 **单 AI 智能体**：基于 DeepSeek API 的智能对话系统，支持思考模式（reasoning 流式输出）
+- 🔌 **WebSocket 通信**：实时双向通信，支持流式输出与任务状态广播
+- 📁 **文件操作**：读写文件、目录列表（支持大文件分页 head/tail）
+- 🌐 **网页访问**：获取网页内容、提取标题、链接与正文
+- 🧠 **记忆管理**：自动保存与检索对话记忆，保持对话连贯性
 - ⏰ **任务系统**：支持一次性、重复（daily/weekly/monthly/custom）、即时任务，自动触发 AI 对话
-- 🔧 **扩展技能**：动态加载`~/.aibox/skills/`目录下的可执行脚本或Markdown技能文件
-- 📦 **对话压缩**：当消息数或Token数达到阈值时自动压缩，保持上下文质量
+- 🔧 **扩展技能**：动态加载 `~/.aibox/skills/` 下的可执行脚本或 Markdown 技能文件
 - 🌍 **多语言支持**：自动检测系统语言，支持中英文
-- 🧬 **智能体自我进化**：通过`update_soul`工具动态更新角色定位和性格定义
+- 🧬 **智能体自我进化**：通过 `update_soul` / `update_identity` 工具动态更新角色定位与用户画像
 - 🔄 **技能热重载**：无需重启即可添加、修改或删除扩展技能
-- 💾 **对话管理**：历史对话归档、开始新对话（重置AI记忆）
+- 🔐 **SOCKS5 代理**：通过 `set_proxy` / `get_proxy` 工具为网页访问与 API 调用配置代理，可持久化
+- 💾 **对话管理**：历史对话归档、开始新对话（重置 AI 记忆并重新加载提示词）
+- 📦 **对话压缩**：消息数或 Token 数达到阈值时自动压缩，保持上下文质量
 
 ## 🚀 快速开始
 
@@ -28,8 +31,7 @@
 ### 安装
 
 ```bash
-# 克隆或下载代码
-# 安装依赖
+# 克隆或下载代码后，安装依赖
 pip install websockets requests beautifulsoup4
 ```
 
@@ -40,17 +42,46 @@ pip install websockets requests beautifulsoup4
 export DEEPSEEK_API_KEY="your-api-key"
 ```
 
-2. **（可选）配置文件**：`~/.aibox/config.json`（系统会自动创建默认配置）
+2. **（可选）配置文件**：`~/.aibox/config.json`（首次启动时自动创建默认配置）
 
 3. **启动服务器**：
 ```bash
-python agent.py
+python main.py
 ```
 
-启动后，WebSocket服务器将运行在 `ws://localhost:8765`
+启动后，WebSocket 服务器将运行在 `ws://localhost:8765`（地址与端口可在 `config.json` 的 `system.websocket_host` / `system.websocket_port` 中修改）。
+
+> 注意：本模块入口文件为 `main.py`（不是 `agent.py`）。`client.py` 为示例 WebSocket 客户端，`voice_client.py` 为语音客户端，`_run.sh` 为被 `core` 拉起的启动脚本。
 
 ## 📁 目录结构
 
+```
+aibox/
+├── main.py            # 服务主程序（WebSocket 服务器 + AI 引擎 + 工具/技能系统）
+├── client.py          # 示例 WebSocket 客户端
+├── voice_client.py    # 语音客户端
+├── entry.html         # 前端入口页
+├── entry1.html        # 前端入口页（变体）
+├── frontend.html      # 前端主页面
+├── skills/            # 内置扩展技能（*.py 可执行脚本 / *.md Markdown 技能）
+│   ├── hello-world.py
+│   ├── aes-crypto.py
+│   ├── bing_search.py
+│   ├── facerec.py
+│   ├── gitclient.py
+│   ├── ssh-exec.py
+│   ├── sftp-transfer.py
+│   └── ...
+├── SKILLS_FORMAT.md   # 技能文件格式说明
+├── _run.sh            # 启动脚本（被 core 守护时调用）
+├── _runcli.sh         # 命令行启动脚本
+├── _set.sh            # 安装脚本
+├── _setenv.sh         # 环境设置脚本
+└── README.md
+```
+
+运行期数据存放于 `~/.aibox/`：
+
 ```
 ~/.aibox/
 ├── config.json              # 配置文件
@@ -59,10 +90,8 @@ python agent.py
 │   ├── 1_*.md               # 基础技能提示词（文件操作、网页访问等）
 │   ├── 99_SOUL.md           # AI 灵魂定义（角色、性格、能力边界）
 │   └── 100_STATUS.md        # AI 状态记录
-├── skills/                  # 扩展技能目录
-│   ├── my_skill             # 可执行技能（无扩展名）
-│   └── guide.md             # Markdown技能
-├── memories.db              # 记忆和任务数据库
+├── skills/                  # 扩展技能目录（运行时从仓库 skills/ 复制或用户自建）
+├── memories.db              # 记忆和任务数据库（SQLite）
 ├── current_conversation.json # 当前对话
 ├── conversation_history.json # 对话索引
 ├── archive/                 # 历史对话归档
@@ -71,7 +100,7 @@ python agent.py
 
 ## 🔧 可用工具
 
-AI智能体可以调用以下工具来完成任务：
+AI 智能体可以调用以下工具来完成任务（由 `Tool` 基类派生，在 `DeepSeekChat` 中注册）：
 
 | 工具名称 | 功能描述 |
 |---------|---------|
@@ -86,11 +115,13 @@ AI智能体可以调用以下工具来完成任务：
 | `reload_skills` | 热重载扩展技能 |
 | `create_skill` | 创建新技能（AI 自主编写 Python 脚本） |
 | `install_skill` | 技能安装指引 |
-| `update_identity` | 更新用户身份信息 |
-| `update_soul` | 更新AI自我定义（智能体进化） |
+| `update_identity` | 更新用户身份信息（`00_IDENTITY.md`） |
+| `update_soul` | 更新 AI 自我定义（`99_SOUL.md`，智能体进化） |
 | `save_memory_and_end_conversation` | 保存记忆并结束对话 |
 | `get_current_time` | 获取当前时间 |
 | `calculator` | 数学计算 |
+| `set_proxy` | 设置 SOCKS5 代理（host/port/可选账号密码，可持久化，即时生效） |
+| `get_proxy` | 查看当前 SOCKS5 代理配置 |
 
 ## 💬 WebSocket API
 
@@ -140,6 +171,8 @@ const ws = new WebSocket('ws://localhost:8765');
 
 ### 支持的命令
 
+> 注意：记忆搜索通过 `memory` 工具（在对话中由 AI 调用）完成，本系统**不存在** `/search` 斜杠命令。
+
 | 命令 | 功能 |
 |-----|------|
 | `/exit` | 退出连接 |
@@ -147,7 +180,6 @@ const ws = new WebSocket('ws://localhost:8765');
 | `/list` | 列出所有历史对话 |
 | `/memories` | 查看最近记忆（支持分页） |
 | `/memos` | 查看待办任务 |
-| `/search <关键词>` | 搜索记忆 |
 | `/config` | 查看配置 |
 | `/reload` | 重载配置 |
 | `/reload_prompts` | 重载提示词 |
@@ -161,7 +193,7 @@ const ws = new WebSocket('ws://localhost:8765');
 |-----|------|
 | `chunk` | AI 响应的片段（流式输出） |
 | `complete` | AI 响应完成 |
-| `reasoning` | AI思考过程（调试模式） |
+| `reasoning` | AI 思考过程（思考模式） |
 | `error` | 错误信息 |
 | `command_result` | 命令执行结果 |
 | `task_status` | 任务状态更新（executing/complete/failed） |
@@ -188,42 +220,29 @@ const ws = new WebSocket('ws://localhost:8765');
 ```json
 // 每天提醒
 {
-  "type": "task",
-  "action": "add",
-  "title": "每日健康提醒",
-  "repeat_type": "daily"
+  "type": "task", "action": "add", "title": "每日健康提醒", "repeat_type": "daily"
 }
 ```
 
 ```json
 // 5分钟后执行
 {
-  "type": "task",
-  "action": "add",
-  "title": "5分钟后提醒",
-  "delay": 300
+  "type": "task", "action": "add", "title": "5分钟后提醒", "delay": 300
 }
 ```
 
 ```json
 // 每30分钟重复
 {
-  "type": "task",
-  "action": "add",
-  "title": "定时检查",
-  "repeat_type": "custom",
-  "repeat_interval": 30,
-  "repeat_interval_unit": "minutes"
+  "type": "task", "action": "add", "title": "定时检查", "repeat_type": "custom",
+  "repeat_interval": 30, "repeat_interval_unit": "minutes"
 }
 ```
 
 ```json
 // 即时任务
 {
-  "type": "task",
-  "action": "add",
-  "title": "检查服务器状态",
-  "is_immediate": true
+  "type": "task", "action": "add", "title": "检查服务器状态", "is_immediate": true
 }
 ```
 
@@ -241,9 +260,8 @@ const ws = new WebSocket('ws://localhost:8765');
 
 #### 1. 可执行技能
 - 放在 `~/.aibox/skills/` 目录
-- 文件必须可执行（`chmod +x`）
-- 支持 `--help` 选项
-- `--help` 第一行为一句话简介，其余为使用说明
+- 文件必须可执行（`chmod +x`），建议不带扩展名
+- 支持 `--help` 选项；`--help` 第一行为一句话简介，其余为使用说明
 
 **示例**：
 ```python
@@ -251,13 +269,9 @@ const ws = new WebSocket('ws://localhost:8765');
 import argparse
 
 def main():
-    parser = argparse.ArgumentParser(
-        description="温度转换工具 - 摄氏度转华氏度"
-    )
-    parser.add_argument("-t", "--temp", type=float, required=True,
-                       help="摄氏温度值")
+    parser = argparse.ArgumentParser(description="温度转换工具 - 摄氏度转华氏度")
+    parser.add_argument("-t", "--temp", type=float, required=True, help="摄氏温度值")
     args = parser.parse_args()
-    
     fahrenheit = args.temp * 9/5 + 32
     print(f"{args.temp}°C = {fahrenheit:.1f}°F")
 
@@ -267,13 +281,12 @@ if __name__ == "__main__":
 
 #### 2. Markdown 技能
 - 文件以 `.md` 结尾
-- 第一行为简介（`# 标题` 或纯文本）
-- 其余为完整的技能内容
+- 第一行为简介（`# 标题` 或纯文本），其余为完整技能内容
 
 **示例**：
 ```markdown
 # 代码审查指南
-提供代码审查的检查清单和最佳实践...
+提供代码审查的检查清单和最佳实践……
 
 ## 检查要点
 1. 代码风格一致性
@@ -289,7 +302,7 @@ if __name__ == "__main__":
 ```
 创建一个技能，功能是将摄氏度转换为华氏度，接受 -c 参数输入温度
 ```
-AI会自动使用 `create_skill` 工具编写脚本并部署。
+AI 会自动使用 `create_skill` 工具编写脚本并部署到 `~/.aibox/skills/`。
 
 #### 方式2：手动创建
 1. 编写脚本，确保支持 `--help`
@@ -304,41 +317,33 @@ chmod +x ~/.aibox/skills/my_skill
 
 #### 方式3：使用安装指引
 ```json
-{
-  "type": "message",
-  "content": "使用 install_skill 工具安装 /path/to/script.py"
-}
+{ "type": "message", "content": "使用 install_skill 工具安装 /path/to/script.py" }
 ```
 
+技能格式详见 [SKILLS_FORMAT.md](SKILLS_FORMAT.md)。
+
 ## 🧠 智能体自我进化
 
-AI可以通过 `update_soul` 工具动态更新 `99_SOUL.md` 文件：
+AI 可以通过 `update_soul` 工具动态更新 `99_SOUL.md`，通过 `update_identity` 工具更新 `00_IDENTITY.md`：
 
 ```json
-{
-  "type": "message",
-  "content": "使用 update_soul 更新我的角色，强调我更注重创造性思维"
-}
+{ "type": "message", "content": "使用 update_soul 更新我的角色，强调我更注重创造性思维" }
 ```
 
-这允许AI在对话中不断优化自己的：
-- 角色定位
-- 性格特点
-- 能力边界
-- 行为准则
-- 价值观
+这允许 AI 在对话中不断优化自己的：角色定位、性格特点、能力边界、行为准则、价值观。
 
 ## 📦 对话压缩
 
 当对话达到阈值时自动压缩：
 
 ```json
-// 配置示例
-"context": {
-  "max_history_messages": 500,
-  "compress_enabled": true,
+// 配置示例（config.json -> context）
+{
+  "max_history_messages": 500,        // 历史消息上限
+  "compress_enabled": true,           // 是否启用压缩
   "compress_message_threshold": 200,  // 消息数阈值
   "compress_token_threshold": 120000, // Token 数阈值
+  "compress_ratio": 0.2,              // 压缩保留比例（早期对话压缩为原长的该比例）
   "compress_keep_recent": 8           // 保留最近消息数
 }
 ```
@@ -363,7 +368,7 @@ AI可以通过 `update_soul` 工具动态更新 `99_SOUL.md` 文件：
 
 ## ⚙️ 配置说明
 
-主要配置项（`~/.aibox/config.json`）：
+主要配置项（`~/.aibox/config.json`，首次启动自动生成）：
 
 ```json
 {
@@ -372,13 +377,16 @@ AI可以通过 `update_soul` 工具动态更新 `99_SOUL.md` 文件：
     "websocket_host": "localhost",
     "websocket_port": 8765,
     "debug_level": 1,
-    "log_file": "~/.aibox/ai.log"
+    "log_file": "~/.aibox/ai.log",
+    "skills_dir": "~/.aibox/skills",
+    "prompts_dir": "~/.aibox/prompts"
   },
   "context": {
     "max_history_messages": 500,
     "compress_enabled": true,
     "compress_message_threshold": 200,
     "compress_token_threshold": 120000,
+    "compress_ratio": 0.2,
     "compress_keep_recent": 8
   },
   "scheduler": {
@@ -388,7 +396,7 @@ AI可以通过 `update_soul` 工具动态更新 `99_SOUL.md` 文件：
   },
   "api": {
     "deepseek_api_url": "https://api.deepseek.com/chat/completions",
-    "deepseek_model": "deepseek-chat",
+    "deepseek_model": "deepseek-v4-flash",
     "api_key_env": "DEEPSEEK_API_KEY"
   },
   "memory": {
@@ -400,10 +408,12 @@ AI可以通过 `update_soul` 工具动态更新 `99_SOUL.md` 文件：
 }
 ```
 
+> 默认模型为 `deepseek-v4-flash`（通过 `api.deepseek_model` 修改）。API Key 从环境变量 `DEEPSEEK_API_KEY` 读取（亦支持 `~/.cert/deepseek.key` 文件）。
+
 ## 🛠️ 命令行参数
 
 ```bash
-python agent.py [选项]
+python main.py [选项]
 
 选项:
   --verbose, -v         显示详细日志
@@ -424,19 +434,19 @@ python agent.py [选项]
 
 ```bash
 # 启动服务器（详细日志）
-python agent.py --verbose
+python main.py --verbose
 
 # 指定端口
-python agent.py --port 9000
+python main.py --port 9000
 
 # 检查任务
-python agent.py --check-memo
+python main.py --check-memo
 
 # 添加任务（命令行）
-python agent.py --memo-add "提醒开会|下午3点会议室A|+1h"
+python main.py --memo-add "提醒开会|下午3点会议室A|+1h"
 
 # 查看所有任务
-python agent.py --memo-list
+python main.py --memo-list
 ```
 
 ## 🔄 架构流程
@@ -452,7 +462,7 @@ python agent.py --memo-list
 │  ┌─────────────┐  ┌─────────────┐  ┌───────────────┐  │
 │  │  消息处理器  │  │  命令处理器  │  │  任务调度器   │  │
 │  └─────────────┘  └─────────────┘  └───────────────┘  │
-└─────────────────┬───────────────────────────────────────┘
+└─────────────────┬──────────────────────────────────────┘
                   │
 ┌─────────────────▼───────────────────────────────────────┐
 │                  AI 对话引擎 (DeepSeek)                  │
@@ -502,6 +512,44 @@ Server -> Client: {type: "command_result", content: "🔄 开始新对话..."}
 Server -> Client: {type: "dialogue_reset", content: "✅ 对话状态已完全重置"}
 ```
 
+## 📝 开发指南
+
+### 添加新工具
+
+1. 继承 `Tool` 基类（位于 `main.py`）
+2. 实现 `get_name()`、`get_description()`、`get_parameters()`、`execute()`
+3. 可选实现 `execute_streaming()` 支持流式输出
+4. 在 `DeepSeekChat` 的工具注册处注册
+
+```python
+class MyTool(Tool):
+    def get_name(self) -> str:
+        return "my_tool"
+
+    def get_description(self) -> str:
+        return "我的自定义工具"
+
+    def get_parameters(self) -> Dict:
+        return {
+            "type": "object",
+            "properties": {"param": {"type": "string"}},
+            "required": ["param"]
+        }
+
+    def execute(self, param: str, **kwargs) -> str:
+        return f"执行结果: {param}"
+```
+
+### 添加新命令
+
+在 `WebSocketHandler` 的命令处理分支（`handle_command`）中添加：
+
+```python
+elif command == "/mycommand":
+    result = "命令执行结果"
+    await self.send_message(websocket, {"type": "command_result", "content": result})
+```
+
 ## ❓ 常见问题
 
 ### Q: API Key 无效怎么办？
@@ -527,30 +575,12 @@ Server -> Client: {type: "dialogue_reset", content: "✅ 对话状态已完全
 5. 确认任务有 `reminder_time`
 
 ### Q: 对话压缩丢失了重要信息？
-**A:** 调整配置：
+**A:** 调整 `config.json` 的 `context` 配置：
 ```json
 "compress_message_threshold": 300,  // 调大阈值
 "compress_keep_recent": 20          // 保留更多最近消息
 ```
 
-### Q: 如何备份数据？
-**A:** 
-```bash
-# 备份整个目录
-tar -czf aibox_backup_$(date +%Y%m%d).tar.gz ~/.aibox/
-
-# 恢复
-tar -xzf aibox_backup_20260101.tar.gz -C ~/
-```
-
-### Q: WebSocket连接断开？
-**A:** 
-1. 检查服务器是否运行：`ps aux | grep agent.py`
-2. 确认端口未被占用：`netstat -tlnp | grep 8765`
-3. 检查防火墙设置
-4. 查看服务器日志
-5. 考虑使用 `--host 0.0.0.0` 允许外部连接
-
 ### Q: 如何让 AI 使用特定技能？
 **A:** 在对话中明确指示：
 ```
@@ -559,82 +589,39 @@ tar -xzf aibox_backup_20260101.tar.gz -C ~/
 
 ### Q: 内存或日志占用过大？
 **A:**
-1. 调整日志配置：
-```json
-"log_max_size": 5242880,   // 5MB
-"log_backup_count": 3
-```
+1. 调整日志配置：`log_max_size`、`log_backup_count`
 2. 清理旧对话归档
 3. 定期清理工具结果缓存
 
+### Q: WebSocket 连接断开？
+**A:**
+1. 检查服务器是否运行：`ps aux | grep main.py`
+2. 确认端口未被占用：`netstat -tlnp | grep 8765`
+3. 检查防火墙设置
+4. 查看服务器日志：`tail -f ~/.aibox/ai.log`
+5. 考虑使用 `--host 0.0.0.0` 允许外部连接
+
 ## 📄 更新日志
 
 ### v2.0 (当前版本)
 - ✅ 新增 `update_soul` 工具（智能体自我进化）
 - ✅ 新增 `create_skill` 工具（AI 自主创建技能）
 - ✅ 新增 `install_skill` 工具（技能安装指引）
+- ✅ 新增 `set_proxy` / `get_proxy` 工具（SOCKS5 代理）
 - ✅ 新增 `task_process` 消息类型（任务执行过程广播）
 - ✅ 支持 Markdown 格式技能文件
 - ✅ 对话压缩支持 Token 数阈值判断
-- ✅ 开始新对话时完全重置AI状态并重新加载提示词
-- ✅ 智能体主动结束对话后重置状态
-- ✅ 任务执行时显示AI完整处理过程
-- ✅ 增强的流式输出支持（思考内容显示）
-- ✅ 技能热重载支持（`reload_skills`）
-- ✅ 记忆搜索支持分页
-- ✅ 任务调度器支持即时任务
+- ✅ 技能热重载（`reload_skills`）
+- ✅ 记忆搜索支持分页、任务调度器支持即时任务
 - ✅ 命令执行支持超时控制
 
 ### v1.0
-- ✅ WebSocket服务器支持
-- ✅ 文件操作、网页访问、记忆管理
-- ✅ 任务调度系统
-- ✅ 扩展技能支持
-- ✅ 多语言支持
-- ✅ 对话管理
+- ✅ WebSocket 服务器、文件/网页/记忆操作、任务调度、扩展技能、多语言、对话管理
 
-## 📝 开发指南
+## 📝 开发指南补充
 
-### 添加新工具
-
-1. 继承 `Tool` 基类
-2. 实现 `get_name()`, `get_description()`, `get_parameters()`, `execute()`
-3. 可选实现 `execute_streaming()` 支持流式输出
-4. 在 `DeepSeekChat._register_tools()` 中注册
-
-```python
-class MyTool(Tool):
-    def get_name(self) -> str:
-        return "my_tool"
-    
-    def get_description(self) -> str:
-        return "我的自定义工具"
-    
-    def get_parameters(self) -> Dict:
-        return {
-            "type": "object",
-            "properties": {
-                "param": {"type": "string"}
-            },
-            "required": ["param"]
-        }
-    
-    def execute(self, param: str, **kwargs) -> str:
-        return f"执行结果: {param}"
-```
-
-### 添加新命令
-
-在 `WebSocketHandler.handle_command()` 中添加：
-
-```python
-elif command == "/mycommand":
-    result = "命令执行结果"
-    await self.send_message(websocket, {
-        "type": "command_result",
-        "content": result
-    })
-```
+### 扩展技能格式
+技能文件命名与格式详见 [SKILLS_FORMAT.md](SKILLS_FORMAT.md)：可执行脚本需支持 `--help`，Markdown 技能首行为简介。
 
 ## 🤝 贡献
 

captcha/README.md

@@ -1,16 +1,18 @@
 # CAPTCHA 验证码服务
 
-一个轻量级的验证码图片服务，仅依赖 Python 标准库实现 HTTP 服务（无需 Flask），配合 Pillow 生成验证码图片。提供图片生成、Token 校验、健康检查等接口，适合作为后端服务的验证码组件。
+一个轻量级的图片验证码服务，仅依赖 Python 标准库实现 HTTP（无需 Flask），配合 Pillow 生成验证码图片。提供图片生成、Token 校验、健康检查三个接口，可作为后端服务的验证码组件独立部署。
+
+服务由 `core`（PMC）的 `init.txt` 拉起，监听 `127.0.0.1:8009`，仅允许本机/内网调用；`gateway` 在登录与注册中可选地启用 CAPTCHA 校验（见 `gateway/README.md`）。
 
 ## 功能特性
 
 - **图片验证码生成**：5 位字符（字母 + 数字），自动排除易混淆字符（`l I 1 O 0 o`）
-- **Token 机制**：每次生成图片返回唯一 Token，校验时一次性消费，防止重放
-- **过期自动清理**：Token 默认 300 秒（5 分钟）失效，每次请求时顺带清理过期项
-- **线程安全**：使用锁保护内存存储，支持并发请求
-- **恒定时间比较**：答案校验使用逐字符异或比较，避免计时攻击
-- **干扰元素**：随机字符颜色、位置偏移、干扰线与噪点，提升识别难度
-- **零框架依赖**：HTTP 层基于 `http.server`，除 Pillow 外无第三方依赖
+- **Token 机制**：每次生成图片返回唯一 Token（32 位十六进制），校验时**一次性消费**，防止重放
+- **过期自动清理**：Token 默认 300 秒（5 分钟）失效；`/captcha/image` 请求时顺带清理过期项，`/captcha/verify` 时若 Token 已不在存储即判为失效
+- **线程安全**：使用锁（`STORE_LOCK`）保护内存存储，支持并发请求
+- **恒定时间比较**：答案校验使用逐字符异或（`diff |= ord(a) ^ ord(b)`），避免计时攻击
+- **干扰元素**：随机字符颜色、垂直位置偏移、干扰线与噪点，提升机器识别难度
+- **零框架依赖**：HTTP 层基于标准库 `http.server`，除 Pillow 外无第三方依赖
 
 ## 技术栈
 
@@ -21,7 +23,6 @@
 ## 安装
 
 ```bash
-# 安装图片处理依赖
 pip install Pillow
 ```
 
@@ -30,8 +31,8 @@ pip install Pillow
 ## 运行
 
 ```bash
-# 方式一：通过启动脚本
-./_run.sh
+# 方式一：通过启动脚本（推荐，由 core 守护时即使用此方式）
+cd captcha && ./_run.sh
 
 # 方式二：直接运行
 python3 captcha_service.py
@@ -41,10 +42,10 @@ python3 captcha_service.py
 
 ## 配置项
 
-在 `captcha_service.py` 顶部可调整以下常量：
+所有可调参数均为 `captcha_service.py` 顶部的模块级常量：
 
 | 常量          | 默认值       | 说明                              |
-| ------------- | ------------ | --------------------- |
+| ------------- | ------------ | --------------------------------- |
 | `CAPTCHA_LEN` | `5`          | 验证码字符长度                    |
 | `CAPTCHA_TTL` | `300`        | Token 有效期（秒）                |
 | `ADDR`        | `127.0.0.1`  | 监听地址                          |
@@ -52,15 +53,37 @@ python3 captcha_service.py
 
 ## API 接口
 
+### 接口总览
+
+| 方法 | 路径              | 说明                                          |
+| ---- | ----------------- | --------------------------------------------- |
+| GET  | `/captcha/image`  | 生成验证码图片，响应头下发 `X-Captcha-Token`  |
+| POST | `/captcha/verify` | 校验用户输入，一次性消费 Token                |
+| GET  | `/health`         | 健康检查                                      |
+
+---
+
 ### 1. 获取验证码图片
 
 ```
 GET /captcha/image
 ```
 
-返回一张 PNG 验证码图片，响应头 `X-Captcha-Token` 携带本次验证的 Token，需在后续校验时一并提供。
+生成一组新验证码（5 位字符 + 对应 Token），返回 PNG 图片二进制流，并在响应头 `X-Captcha-Token` 中携带本次校验所需的 Token。
 
-**示例：**
+**请求**：无参数、无请求体。
+
+**响应头**：
+
+| 头字段            | 取值            | 说明                              |
+| ----------------- | --------------- | --------------------------------- |
+| `Content-Type`    | `image/png`     | 图片格式                          |
+| `Content-Length`  | 数值            | 图片字节数                        |
+| `X-Captcha-Token` | 32 位十六进制串 | 本次验证码的 Token，校验时必须回传 |
+
+**响应体**：二进制 PNG 图片，尺寸 160 × 50。
+
+**示例**：
 
 ```bash
 curl -D - http://127.0.0.1:8009/captcha/image -o captcha.png
@@ -70,9 +93,14 @@ curl -D - http://127.0.0.1:8009/captcha/image -o captcha.png
 
 ```
 Content-Type: image/png
+Content-Length: 3210
 X-Captcha-Token: 3f9a1c2b4d5e6f7a8b9c0d1e2f3a4b5c
 ```
 
+> Token 有效期 300 秒，且**一次性使用**——无论校验成功与否，第一次 `/captcha/verify` 调用后即被消费。
+
+---
+
 ### 2. 校验验证码
 
 ```
@@ -80,7 +108,16 @@ POST /captcha/verify
 Content-Type: application/json
 ```
 
-请求体：
+提交 `/captcha/image` 下发的 Token 与用户输入，比对答案（大小写不敏感）。**Token 在调用后被立即移除（一次性）。**
+
+**请求体字段**：
+
+| 字段    | 类型   | 必填 | 说明                                       |
+| ------- | ------ | ---- | ------------------------------------------ |
+| `token` | string | 是   | `GET /captcha/image` 响应头中的 `X-Captcha-Token` |
+| `answer` | string | 是   | 用户输入的验证码文本，校验前统一转小写，大小写不敏感 |
+
+**请求体示例**：
 
 ```json
 {
@@ -89,19 +126,27 @@ Content-Type: application/json
 }
 ```
 
-响应（校验不区分大小写，Token 校验后即失效）：
+**响应**：
 
-```json
-{ "valid": true }
+| HTTP 状态码 | 响应体                                     | 触发条件                                       |
+| ----------- | ------------------------------------------ | ---------------------------------------------- |
+| `200`       | `{ "valid": true }`                        | Token 有效且答案正确                           |
+| `200`       | `{ "valid": false }`                       | Token 有效但**答案错误**（Token 已消费）      |
+| `400`       | `{ "valid": false, "error": "invalid json" }`            | 请求体非合法 JSON                  |
+| `400`       | `{ "valid": false, "error": "token and answer required" }` | 缺少 `token` 或 `answer` 字段       |
+| `400`       | `{ "valid": false, "error": "invalid or expired token" }`  | Token 无效、已消费或已过期            |
+
+> ⚠️ **注意区分**：答案错误与 Token 错误是两种不同的结果。答案错误（Token 仍有效）返回 `200 {valid:false}`；而 Token 缺失/失效/过期会直接返回 `400`。消费方（如 gateway）应据此分别处理：前者提示"验证码错误"，后者提示"请重新获取验证码"。
+
+**示例**：
+
+```bash
+curl -X POST http://127.0.0.1:8009/captcha/verify \
+  -H 'Content-Type: application/json' \
+  -d '{"token":"3f9a1c2b4d5e6f7a8b9c0d1e2f3a4b5c","answer":"AB3XY"}'
 ```
 
-错误情况：
-
-| HTTP 状态码 | 响应体                                              | 说明                    |
-| ----------- | --------------------------------------------------- | ----------------------- |
-| `400`       | `{ "valid": false, "error": "invalid json" }`       | 请求体非合法 JSON       |
-| `400`       | `{ "valid": false, "error": "token and answer required" }` | 缺少 token 或 answer    |
-| `400`       | `{ "valid": false, "error": "invalid or expired token" }`  | Token 无效或已过期      |
+---
 
 ### 3. 健康检查
 
@@ -109,28 +154,46 @@ Content-Type: application/json
 GET /health
 ```
 
+**响应**（HTTP 200）：
+
 ```json
 { "status": "ok", "service": "captcha" }
 ```
 
+---
+
+## 数据模型与 Token 生命周期
+
+- **存储**：进程内存字典 `captcha_store`，键为 Token，值为 `{ answer: <小写答案>, created_at: <Unix 时间戳> }`。
+- **生成**：`GET /captcha/image` 时写入一条记录，并返回对应 Token。
+- **消费**：`POST /captcha/verify` 时 `pop` 移除该 Token，无论答案对错，均不可再次使用。
+- **过期**：超过 `CAPTCHA_TTL`（300 秒）即视为失效。`/captcha/image` 会在每次生成时顺带清理过期项；`/captcha/verify` 时若 Token 不在存储中（过期、未生成或已消费），统一返回 `400 invalid or expired token`。
+
+## 集成关系
+
+- 由 `core`（`PMC`）通过 `init.txt` 中的 `bash /opt/micro_servers/captcha/_run.sh` 拉起并守护。
+- `gateway` 在 `/login` 与 `/register` 中可选地启用 CAPTCHA 校验（以 `captcha_token` + `captcha_answer` 字段传入，见 `gateway/README.md`）。
+- 在集中式日志链路中，`captcha` 作为 `service` 名之一，可经 `log_client` SDK 推送日志至 `db` 的 `/log/ingest`。
+
 ## 典型使用流程
 
 1. 客户端调用 `GET /captcha/image`，保存返回的图片与响应头中的 `X-Captcha-Token`。
 2. 用户根据图片内容输入验证码文本。
 3. 客户端调用 `POST /captcha/verify`，提交 `token` 与用户输入的 `answer`。
-4. 服务端比对答案（小写化、恒定时间比较），返回 `valid` 结果，Token 随即作废。
+4. 服务端比对答案（小写化、恒定时间比较），返回 `valid` 结果；Token 随即作废（无论对错）。
 
 ## 项目结构
 
 ```
 captcha/
 ├── captcha_service.py   # 服务主程序（HTTP 服务 + 验证码生成与校验）
-├── _run.sh              # 启动脚本
+├── _run.sh              # 启动脚本（cd 后 exec python3 captcha_service.py）
 └── README.md
 ```
 
 ## 注意事项
 
-- 验证码存储在进程内存中，服务重启后所有 Token 失效，不适合多实例水平扩展场景（如需分布式可替换为 Redis 等外部存储）。
-- 默认仅监听 `127.0.0.1`，仅供本机或内网调用；如需对外暴露请配合反向代理并做好限流。
-- 答案校验不区分大小写，Token 一经校验即从内存中移除（无论对错）。
+- 验证码存储在进程内存中，服务重启后所有 Token 失效；**不支持多实例水平扩展**（如需分布式部署，应将 `captcha_store` 替换为 Redis 等外部存储，并相应调整过期清理逻辑）。
+- 默认仅监听 `127.0.0.1`，仅供本机或内网调用；如需对外暴露，请配合反向代理（如 `gateway`/`waf`）并做好限流。
+- 答案校验不区分大小写；Token 一经校验即从内存中移除（一次性使用）。
+- 字体缺失时自动回退到 PIL 默认字体，可能影响验证码观感，部署前建议确认 DejaVu 字体已安装。

static/public/js/register.js

@@ -1,11 +1,9 @@
 const form = document.getElementById('form');
-const usernameInput = document.getElementById('regusername');
 const emailInput = document.getElementById('regemail');
 const codeInput = document.getElementById('code');
 const getCodeButton = document.getElementById('getCode');
 const passwordInput = document.getElementById('regpsw');
 const repeatPasswordInput = document.getElementById('repwd');
-const msgTip = document.getElementById('msgTip');
 const emlTip = document.getElementById('emlTip');
 const pwdTip = document.getElementById('pwdTip');
 const codeTip = document.getElementById('codeTip');
@@ -21,27 +19,16 @@ form.addEventListener('reset', function () {
 });
 
 function clearTipStyle() {
-	msgTip.innerHTML = '';
 	emlTip.innerHTML = '';
 	pwdTip.innerHTML = '';
 	codeTip.innerHTML = '';
 
-	msgTip.classList.remove('tip-red', 'tip-yellow', 'tip-green');
 	emlTip.classList.remove('tip-red', 'tip-yellow', 'tip-green');
 	pwdTip.classList.remove('tip-red', 'tip-yellow', 'tip-green');
 	codeTip.classList.remove('tip-red', 'tip-yellow', 'tip-green');
 }
 clearTipStyle();
 
-function checkUsername() {
-	const result = FormValidators.username(usernameInput.value);
-	msgTip.innerHTML = '';
-	msgTip.classList.remove('tip-red', 'tip-yellow', 'tip-green');
-	msgTip.textContent = result.message;
-	msgTip.classList.add(result.className);
-	return result.valid ? result.value : false;
-}
-
 function checkEmail() {
 	const result = FormValidators.email(emailInput.value);
 	emlTip.innerHTML = '';
@@ -103,15 +90,12 @@ function checkCode() {
 	return code;
 }
 
-usernameInput.addEventListener('focus', checkUsername);
 passwordInput.addEventListener('focus', checkPassword);
 repeatPasswordInput.addEventListener('focus', checkPassword);
 
-usernameInput.addEventListener('input', checkUsername);
 passwordInput.addEventListener('input', checkPassword);
 repeatPasswordInput.addEventListener('input', checkPassword);
 
-usernameInput.addEventListener('blur', checkUsername);
 passwordInput.addEventListener('blur', checkPassword);
 repeatPasswordInput.addEventListener('blur', checkPassword);
 
@@ -146,16 +130,15 @@ getCodeButton.addEventListener('click', function () {
 form.addEventListener('submit', async function (e) {
 	e.preventDefault();
 
-	const username = checkUsername();
 	const email = checkEmail();
 	const password = checkPassword();
 	const code = checkCode();
 
-	if (!username || !email || !password || !code) {
+	if (!email || !password || !code) {
 		return;
 	}
 	const jsonBody = JSON.stringify({
-		username,
+		username: email,
 		password
 	});
 

static/public/login.html

@@ -11,8 +11,8 @@
 			<h2>用户登录</h2>
 			<form id="form" novalidate>
 				<div>
-					<label>用户名/推荐邮箱：</label>
-					<input type="text" id="loginUsername" placeholder="请输入用户名">
+					<label>邮箱：</label>
+					<input type="text" id="loginUsername" placeholder="请输入邮箱">
 					<span id="msgTip"></span>
 					<label>密码：</label>
 					<input type="password" id="loginPassword" placeholder="请输入密码">

static/public/register.html

@@ -11,9 +11,6 @@
 			<h2>注册页面</h2>
 			<form id="form">
 				<div>
-					<label>用户名/推荐邮箱：</label>
-					<input type="text" id="regusername" placeholder="请输入用户名">
-					<span id="msgTip" ></span>
 				<label>邮箱号：</label>
 					<input type="email" id="regemail" placeholder="请输入邮箱号">
 					<div class="code-box">验证码：