agent-Specialization/doc/phases/phase3_summary.md

Phase 3 Summary – 鉴权与配额基线

交付成果

1. HTTP / WebSocket 鉴权加固

   • 引入统一速率限制器与失败计数：登录/注册/文件写操作等接口按 IP/用户多维限流，同时重试上限触发临时封禁。
   • 自定义 CSRF 体系：后端提供 /api/csrf-token，前端全局 fetch 包装自动附带 X-CSRF-Token，所有写操作在 before_request 校验；会话 Cookie 统一启用 SameSite=Strict、Secure/HttpOnly 并增加基础安全头。
   • Socket.IO 握手新增一次性 token（含 UA 指纹），连接、重连都会验证 token 并立即销毁，阻断单凭 session cookie 劫持的可能。

2. 模型 / 搜索用量配额

   • 新增 modules/usage_tracker.py，按用户与角色记录滑动窗口用量（普通用户：常规 50/5h、思考 20/5h、搜索 20/24h；管理员 9999），数据持久化在 usage_stats.json。
   • core/main_terminal.py 在每次模型/搜索调用前检查并递增配额，超限时直接拒绝并返回重置时间；web_server.py 同步向前端广播 quota_notice，防止静默失败。
   • UI 用量面板展示实时配额、重置时间，并在输入框侧阻止超限请求；新增右上角 toast 通知提醒配额状态。

3. 界面与体验

   • Web 用量组件、新增安全 toast、自动刷新配额数据（轮询 + Socket 事件），并隐藏 0 次额度的重置提示，避免噪音。

影响评估

• 攻击面收敛：CSRF、防爆破、Socket 凭证等基础鉴权补齐后，未授权调用需要突破多重校验，WebSocket 劫持和暴力破解风险显著下降。
• 可观测性/运维：配额快照和 /api/usage 接口为后续差异化用户组与审计提供依据，可直观查看每类用量与重置时间。
• 用户体验：前端能够即时获知配额状态，避免“点击无响应”，同时 toast 提醒让限额策略更透明。

仍待处理

• 尚未引入 CAPTCHA / MFA、异常告警、CLI API Token 等进一步的身份防护手段。
• Upload/MIME 检查、CSP/内容安全策略与更细粒度的 ACL 仍未落地。
• 配额目前只区分普通/管理员，可在下一阶段扩展“用户组 + 自定义窗口/额度”的配置中心，并联动告警系统。

验证

• python3 -m py_compile web_server.py core/main_terminal.py core/web_terminal.py modules/usage_tracker.py。
• 手动验证：登录界面输错多次触发 429，WebSocket 无 token 无法建立连接；浏览器抓包可见所有写请求均带 X-CSRF-Token。
• 配额体验：普通用户 5 小时窗口内超限时前端弹出提示、API 返回重置时间，5 小时后自动恢复。