241 lines
10 KiB
Markdown
241 lines
10 KiB
Markdown
---
|
||
title: "fix: P0 安全修复与代码质量优化"
|
||
status: active
|
||
date: 2026-06-21
|
||
type: fix
|
||
origin: ocr 代码审查 + 全面项目质量评估报告
|
||
---
|
||
|
||
# P0 安全修复与代码质量优化计划
|
||
|
||
## Summary
|
||
|
||
基于 open-code-review 对 auth 功能分支的审查（9 文件 15 评论）和全面项目质量评估，本计划修复 4 个 P0 级安全/Bug 问题、1 个文档不一致问题、1 个核心 UX 缺失，并补强集成测试覆盖。所有修复均有明确的代码证据和 ocr 审查评论支撑。
|
||
|
||
## Problem Frame
|
||
|
||
ocr 审查发现 whoami 冷启动路径存在 2 个安全漏洞（被禁用用户绕过 + 令牌放大风险），1 个数据不一致 Bug（list_active_by_provider 未过滤过期会话），1 个测试崩溃 Bug（asyncio.run 在事件循环内）。此外，CLAUDE.md/AGENTS.md 中路由系统描述与实际实现严重不匹配，前端缺少基础的"停止生成"功能。
|
||
|
||
## Requirements
|
||
|
||
- R1: whoami 冷启动必须检查 `is_active`，被禁用用户不能获取新 access token
|
||
- R2: whoami 冷启动必须实现 refresh token 轮换，防止令牌放大攻击
|
||
- R3: `list_active_by_provider` 必须过滤过期会话，与 docstring 承诺一致
|
||
- R4: 集成测试中 `asyncio.run()` 必须修复，跨用户撤销测试必须可运行
|
||
- R5: CLAUDE.md/AGENTS.md 路由系统描述必须与 RequestPreprocessor 实际实现匹配
|
||
- R6: 前端聊天界面必须支持"停止生成"功能，用户可中途取消 LLM 输出
|
||
- R7: 集成测试必须补齐 ocr 指出的覆盖缺口（404 边界、密码修改端到端、会话撤销验证）
|
||
|
||
## Key Technical Decisions
|
||
|
||
### KTD-1: whoami 冷启动 refresh token 处理策略
|
||
|
||
**决策**: 采用方案 B — 仅签发短期 access token，不创建新 refresh token。
|
||
|
||
**理由**: 客户端已有有效 refresh token，冷启动只需 access token 即可恢复会话。调用 `svc.rotate()` 会增加复杂度且改变客户端持有的 refresh token，而方案 B 更简单、安全（原 refresh token 仍受重用检测保护）。不调用 `create_token_pair`，改为单独签发 access token。
|
||
|
||
### KTD-2: 停止生成的实现方式
|
||
|
||
**决策**: 前端通过 WebSocket 发送 `cancel` 消息（协议已定义），后端通过 CancellationToken 取消正在执行的 Agent 任务。
|
||
|
||
**理由**: WebSocket 协议中已有 `cancel` 消息类型（见 AGENTS.md），后端 BaseAgent 已实现 CancellationToken 协作式取消。只需前端添加按钮和发送逻辑，无需新增后端端点。
|
||
|
||
## Scope Boundaries
|
||
|
||
### In Scope
|
||
|
||
- whoami 冷启动安全修复（is_active + token 策略）
|
||
- list_active_by_provider 过滤修复
|
||
- asyncio.run 测试修复 + 集成测试补强
|
||
- CLAUDE.md/AGENTS.md 路由文档更新
|
||
- 前端"停止生成"按钮
|
||
|
||
### Deferred to Follow-Up Work
|
||
|
||
- 多模态输入支持（C1，需独立计划）
|
||
- 用户反馈机制 thumbs up/down（C3，需独立计划）
|
||
- Prompt Caching（C9，需 LLM Gateway 改造）
|
||
- 多租户隔离逻辑（C7，需独立计划）
|
||
- `: Any` 类型清理（213 处，大规模重构）
|
||
- 吞异常清理（109 处，需逐文件审查）
|
||
- LLM 模块测试覆盖（0.06 比率，需独立计划）
|
||
|
||
---
|
||
|
||
## Implementation Units
|
||
|
||
### U1. 修复 whoami 冷启动安全漏洞
|
||
|
||
**Goal**: 修复 whoami 冷启动路径的 2 个安全漏洞：缺失 is_active 检查 + 令牌放大风险。
|
||
|
||
**Requirements**: R1, R2
|
||
|
||
**Dependencies**: 无
|
||
|
||
**Files**:
|
||
- Modify: `src/agentkit/server/routes/auth.py`（whoami 路由）
|
||
- Modify: `src/agentkit/server/auth/jwt_utils.py`（如需新增单独签发 access token 的函数）
|
||
- Test: `tests/integration/auth/test_auth_routes.py`
|
||
|
||
**Approach**:
|
||
1. 在 whoami 路由中，将 `if row is None` 改为 `if row is None or not bool(row["is_active"])`，返回 401
|
||
2. 移除冷启动路径中的 `create_token_pair` 调用，改为仅签发 access token（使用 jwt_utils 中现有的 access token 创建逻辑）
|
||
3. 不创建新 refresh token，不调用 `svc.rotate()`，客户端保留原 refresh token
|
||
|
||
**Patterns to follow**: `/auth/refresh` 路由中的 `is_active` 检查模式（auth.py 第 514 行）
|
||
|
||
**Test scenarios**:
|
||
- **Happy path**: 被禁用用户（is_active=0）用 refresh token 调用 whoami → 401
|
||
- **Happy path**: 活跃用户用 refresh token 调用 whoami → 200 + 新 access token + 无新 refresh token
|
||
- **Edge case**: 活跃用户用 access token 调用 whoami → 200 + access_token 为 None（行为不变）
|
||
- **Error path**: 不存在的用户 ID（token 被篡改）→ 401
|
||
|
||
**Verification**: `pytest tests/integration/auth/test_auth_routes.py::TestWhoamiColdStart -v` 全部通过
|
||
|
||
---
|
||
|
||
### U2. 修复 list_active_by_provider 过滤过期会话
|
||
|
||
**Goal**: 使 SQL 查询与 docstring 承诺一致，过滤掉已过期的会话。
|
||
|
||
**Requirements**: R3
|
||
|
||
**Dependencies**: 无
|
||
|
||
**Files**:
|
||
- Modify: `src/agentkit/server/auth/session_service.py`（list_active_by_provider 方法）
|
||
- Test: `tests/unit/auth/test_session_service.py`
|
||
|
||
**Approach**:
|
||
1. 在 SQL 查询中添加 `AND expires_at > ?` 条件
|
||
2. 传入当前 UTC 时间的 ISO 格式字符串作为参数
|
||
3. 需要在方法顶部导入 `datetime, timezone`（如未导入）
|
||
|
||
**Patterns to follow**: `list_all` 方法中的 SQL 构造模式
|
||
|
||
**Test scenarios**:
|
||
- **Happy path**: 有 1 个活跃会话 + 1 个过期会话 → 仅返回活跃会话
|
||
- **Happy path**: 所有会话均过期 → 返回空列表
|
||
- **Edge case**: 无会话 → 返回空列表
|
||
- **Edge case**: 会话 expires_at 恰好等于当前时间 → 不返回（边界 > 而非 >=）
|
||
|
||
**Verification**: `pytest tests/unit/auth/test_session_service.py -k list_active_by_provider -v` 通过
|
||
|
||
---
|
||
|
||
### U3. 修复 asyncio.run 测试崩溃 + 补强集成测试
|
||
|
||
**Goal**: 修复 test_revoke_other_user_session_returns_404 中的 asyncio.run 崩溃，并补齐 ocr 指出的 6 个测试覆盖缺口。
|
||
|
||
**Requirements**: R4, R7
|
||
|
||
**Dependencies**: U1
|
||
|
||
**Files**:
|
||
- Modify: `tests/integration/auth/test_auth_routes.py`
|
||
- Modify: `tests/integration/auth/test_admin_routes.py`
|
||
|
||
**Approach**:
|
||
1. 将 `_login_sync_create_user` 改为 `async def`，调用方 `test_revoke_other_user_session_returns_404` 也改为 `async def`
|
||
2. 移除未使用的 `auth_db_with_admin` fixture
|
||
3. 补充测试：
|
||
- `test_non_admin_cannot_list_all_sessions`（admin 路由 403 测试）
|
||
- `test_revoke_session_belonging_to_different_user_returns_404`（admin 撤销不匹配用户会话）
|
||
- `test_admin_list_sessions_for_nonexistent_user_returns_404`
|
||
- `test_admin_revoke_nonexistent_session_returns_404`
|
||
- 密码修改测试：验证当前会话存活 + 用新密码登录
|
||
- 会话撤销测试：撤销后用原 token 调用 whoami → 401
|
||
- 全局会话列表：验证两个用户都会出现
|
||
|
||
**Patterns to follow**: 现有 `test_admin_routes.py` 中的测试模式
|
||
|
||
**Test scenarios**:
|
||
- **Happy path**: asyncio 修复后 test_revoke_other_user_session_returns_404 正常运行
|
||
- **Happy path**: 所有新增测试通过
|
||
- **Error path**: 非管理员访问 /admin/sessions → 403
|
||
- **Error path**: admin 撤销不存在会话 → 404
|
||
- **Integration**: 密码修改 → 旧密码登录失败 → 新密码登录成功
|
||
|
||
**Verification**: `pytest tests/integration/auth/ -v` 全部通过，无崩溃
|
||
|
||
---
|
||
|
||
### U4. 更新路由系统文档
|
||
|
||
**Goal**: 使 CLAUDE.md 和 AGENTS.md 中的路由系统描述与实际 RequestPreprocessor 实现匹配。
|
||
|
||
**Requirements**: R5
|
||
|
||
**Dependencies**: 无
|
||
|
||
**Files**:
|
||
- Modify: `CLAUDE.md`（Request Flow 部分）
|
||
- Modify: `AGENTS.md`（Request Flow 部分）
|
||
|
||
**Approach**:
|
||
1. 将 Request Flow 部分从 "CostAwareRouter (3-layer)" 改为 "RequestPreprocessor (2-layer)"
|
||
2. 更新层级描述：
|
||
- Layer 0: `@skill:xxx` 前缀 → 显式技能选择
|
||
- Layer 1: 正则快速路径（问候/闲聊/身份/知识/算术/翻译）→ DIRECT_CHAT
|
||
- Layer 2: 其他全部 → REACT（LLM 在 agent loop 中自主决策）
|
||
3. 移除对 HeuristicClassifier、SemanticRouter、Capability matching、Vickrey Auction 的描述
|
||
4. 添加设计决策说明（引用 request_preprocessor.py docstring 中的 rationale）
|
||
5. 更新 ExecutionMode 描述（移除 TEAM_COLLAB 从路由层触发，改为 @team 前缀触发）
|
||
|
||
**Patterns to follow**: `src/agentkit/chat/request_preprocessor.py` 的 docstring
|
||
|
||
**Test scenarios**:
|
||
- **Test expectation**: none — 纯文档变更，无行为变化
|
||
|
||
**Verification**: 文档中不再出现 "CostAwareRouter"、"HeuristicClassifier"、"SemanticRouter"（作为当前架构描述），grep 确认
|
||
|
||
---
|
||
|
||
### U5. 前端添加"停止生成"按钮
|
||
|
||
**Goal**: 用户可在 LLM 长输出时中途取消生成。
|
||
|
||
**Requirements**: R6
|
||
|
||
**Dependencies**: 无
|
||
|
||
**Files**:
|
||
- Modify: `src/agentkit/server/frontend/src/components/chat/ChatInput.vue`（添加停止按钮）
|
||
- Modify: `src/agentkit/server/frontend/src/stores/chat.ts`（添加 cancel 状态和发送逻辑）
|
||
- Test: `src/agentkit/server/frontend/src/components/chat/__tests__/ChatInput.test.ts`（如存在）
|
||
|
||
**Approach**:
|
||
1. 在 chat store 中添加 `isGenerating` 状态（true 时显示停止按钮，false 时显示发送按钮）
|
||
2. 添加 `cancelGeneration()` action，通过 WebSocket 发送 `cancel` 消息
|
||
3. 在 ChatInput 组件中，根据 `isGenerating` 切换按钮：发送按钮 ↔ 停止按钮
|
||
4. 停止按钮点击时调用 `cancelGeneration()`
|
||
5. 收到 `final_answer` 或 `error` 事件时，自动将 `isGenerating` 置为 false
|
||
|
||
**Patterns to follow**: 现有 ChatInput.vue 中发送按钮的实现模式
|
||
|
||
**Test scenarios**:
|
||
- **Happy path**: 空闲状态显示发送按钮，生成中显示停止按钮
|
||
- **Happy path**: 点击停止按钮 → 发送 cancel 消息 → isGenerating 变为 false
|
||
- **Edge case**: 生成中输入框禁用或允许继续输入（取决于现有 UX 模式）
|
||
- **Integration**: 收到 final_answer 后 isGenerating 自动重置
|
||
|
||
**Verification**: `npm run typecheck` 通过，手动验证按钮切换和取消功能
|
||
|
||
---
|
||
|
||
## Risks & Dependencies
|
||
|
||
| 风险 | 影响 | 缓解措施 |
|
||
|------|------|----------|
|
||
| U1 修改 whoami 可能影响现有冷启动流程 | 中 | 集成测试覆盖所有 whoami 场景 |
|
||
| U5 修改 chat store 可能影响 WebSocket 状态机 | 中 | 仅添加状态，不修改现有流转 |
|
||
| U4 文档更新可能遗漏其他引用 CostAwareRouter 的位置 | 低 | grep 全仓库搜索 CostAwareRouter |
|
||
|
||
## System-Wide Impact
|
||
|
||
- **U1**: 影响 whoami 端点行为，前端 auth store 的冷启动流程需验证兼容性
|
||
- **U2**: 影响 admin 会话查询结果，数据更准确
|
||
- **U3**: 仅测试代码，无生产影响
|
||
- **U4**: 仅文档，无代码影响
|
||
- **U5**: 影响聊天 UI 交互，需验证 WebSocket cancel 消息处理
|