# 首页 Agent 实施计划

> 设计文档：`docs/superpowers/specs/2026-08-06-homepage-agent-design.md`

## 实施顺序总览

按依赖关系分 7 个阶段，每阶段完成后验证再进入下一阶段。

---

## 阶段 1：数据库 Schema + 迁移

**目标：** 建立数据基础，后续所有功能依赖于此。

### 任务 1.1 修改 `llm_providers.userId` 为可空
- 文件：`packages/drizzle-pkg/lib/schema/llm.ts`
- 改动：去掉 `userId` 的 `.notNull()`
- 注意：保留 `.references(() => users.id, { onDelete: "cascade" })`

### 任务 1.2 修正 `AgentToolTypes` enum
- 文件：`packages/drizzle-pkg/lib/schema/agent-tool.ts`
- 改动：在 `AgentToolTypes` 数组中补充 `"user-info"`

### 任务 1.3 新增 `agent_sessions` 表
- 文件：`packages/drizzle-pkg/lib/schema/agent.ts`（新建）
- 字段：见设计文档 `agent_sessions` 表定义
- 索引：`userId` + `deletedAt`、`tempToken`

### 任务 1.4 新增 `agent_messages` 表
- 文件：`packages/drizzle-pkg/lib/schema/agent.ts`
- 字段：见设计文档 `agent_messages` 表定义
- 索引：`sessionId` + `sortOrder`

### 任务 1.5 新增 `agent_message_feedback` 表
- 文件：`packages/drizzle-pkg/lib/schema/agent.ts`
- 字段：见设计文档 `agent_message_feedback` 表定义
- 唯一约束：`messageId` + `userId`

### 任务 1.6 导出新 schema
- 文件：`packages/drizzle-pkg/lib/schema/index.ts`
- 导出 `agentSessions`、`agentMessages`、`agentMessageFeedback`

### 任务 1.7 生成数据库迁移
- 命令：`bun run db:generate`
- 验证：检查生成的迁移 SQL 文件，确认包含 3 个新表 + `llm_providers` 修改

### 任务 1.8 执行迁移
- 命令：`bun run db:migrate`
- 验证：`bun run db:studio` 查看新表结构

---

## 阶段 2：配置注册 + LLM Service 扩展

**目标：** 为后端 API 提供配置读写和系统级模型查询能力。

### 任务 2.1 注册 agent 配置项到 CONFIG_REGISTRY
- 文件：`server/service/config/registry.ts`
- 新增 5 个配置项：`agentSystemPrompt`(global)、`agentDefaultModelId`(global)、`agentTitleModelId`(global)、`agentPublicToolSlugs`(global)、`preferredLlmModelId`(user)
- 参考现有配置项的注册模式

### 任务 2.2 LLM service 新增系统级查询函数
- 文件：`server/service/llm/index.ts`
- 新增函数：
  - `getSystemProviderById(id)` — `WHERE userId IS NULL`
  - `getSystemModelById(id)` — 关联 provider.userId IS NULL
  - `listSystemModels()` — 列出所有系统级模型
- 参考现有 `getProviderById`、`getModelById`、`listModels` 的实现模式

### 任务 2.3 扩展 `resolveModel` 支持系统级模型
- 文件：`server/service/llm/index.ts` 或相关 resolveModel 所在文件
- 确保未登录用户能使用系统级 provider/model（userId IS NULL）
- 已登录用户可使用自己的或系统级的 model

---

## 阶段 3：后端 API — Session 管理

**目标：** 实现 session CRUD，支撑前端侧边栏和对话区。

### 任务 3.1 Agent session service
- 文件：`server/service/agent/session.ts`（新建）
- 函数：
  - `createSession({ userId?, tempToken?, modelId?, expiresAt? })`
  - `getSessionById(id)`
  - `listSessions({ userId?, tempToken?, page, pageSize })`
  - `updateSession(id, { title?, modelId?, enableThinking?, enableTools? })`
  - `softDeleteSession(id)`
  - `getMessagesBySession(sessionId, { before?, limit })`
  - `saveMessage({ sessionId, role, content, parts?, modelId?, inputTokens?, outputTokens?, sortOrder })`
  - `getMaxSortOrder(sessionId)`
  - `truncateMessagesAfter(sessionId, sortOrder)` — 硬删除
  - `deleteMessage(messageId)` — 硬删除 + 级联删除 feedback

### 任务 3.2 临时 session token 工具
- 文件：`server/service/agent/temp-token.ts`（新建）
- 函数：
  - `generateTempToken()` — 64 位随机 hex
  - `setTempTokenCookie(event, token)` — HttpOnly cookie
  - `getTempTokenFromCookie(event)` — 读取 cookie
  - `clearTempTokenCookie(event)` — 清除 cookie

### 任务 3.3 身份识别工具
- 文件：`server/service/agent/identity.ts`（新建）
- 函数：`resolveAgentIdentity(event)` — 返回 `{ userId: number | null, tempToken: string | null }`
- 逻辑：先检查登录态（`getCurrentUser`），未登录则读 cookie tempToken

### 任务 3.4 Session API 路由
- 文件（新建）：
  - `server/api/agent/sessions/index.get.ts` — 分页列表
  - `server/api/agent/sessions/index.post.ts` — 新建 session
  - `server/api/agent/sessions/[id]/index.get.ts` — session 详情 + 首页消息
  - `server/api/agent/sessions/[id]/index.put.ts` — 重命名
  - `server/api/agent/sessions/[id]/index.delete.ts` — 软删除
  - `server/api/agent/sessions/[id]/config.put.ts` — 更新 session 配置
  - `server/api/agent/sessions/[id]/messages.get.ts` — 消息分页加载
- 参考现有 API 路由的响应格式（`{ code: 0, data: ... }`）

---

## 阶段 4：后端 API — 对话核心

**目标：** 实现流式对话、工具注入、限流、编辑/重新生成。

### 任务 4.1 限流服务
- 文件：`server/service/agent/rate-limit.ts`（新建）
- 内存 Map 实现：
  - `checkRateLimit(sessionId, ip)` — 返回 `{ sessionRemaining, ipRemaining, blocked: boolean }`
  - `incrementRateLimit(sessionId, ip)` — assistant 回复完成后调用
  - 每日 0 点重置（日期字符串比对）

### 任务 4.2 工具注入扩展
- 文件：`server/service/agent-tool/index.ts`
- 修改 `getEnabledToolsForLlm` 或新增函数：
  - 已登录 + enableTools：全部 enabled 工具（需审批）
  - 已登录 + !enableTools：空列表
  - 未登录：`agentPublicToolSlugs` 白名单工具（自动执行，无需审批）
- 新增参数：`{ userId, enableTools, publicToolSlugs }`

### 任务 4.3 标题生成服务
- 文件：`server/service/agent/title.ts`（新建）
- 函数：`generateTitle(sessionId, firstUserMessage, titleModelId)`
- 使用 `titleModelId` 指定的系统级模型，非流式调用
- 失败兜底：保持"新对话"标题，日志记录

### 任务 4.4 对话 API
- 文件：`server/api/agent/chat/index.post.ts`（新建）
- 核心流程（见设计文档"核心流程"10 步）
- 复用现有 `streamText` + `toUIMessageStreamResponse` 模式
- 响应头注入限流信息（未登录用户）
- `onFinish` 回调：保存 assistant message + 更新 session lastActiveAt + 限流计数 + 异步标题生成

### 任务 4.5 工具审批 API
- 文件：`server/api/agent/chat/tool-approve.post.ts`（新建）
- 逻辑：approved=true 执行工具，approved=false 返回拒绝结果

### 任务 4.6 反馈 API
- 文件：`server/api/agent/feedback.post.ts`（新建）
- UPSERT 逻辑（messageId + userId 唯一约束）

### 任务 4.7 迁移 API
- 文件：`server/api/agent/migrate.post.ts`（新建）
- 逻辑：查询 tempToken 关联 session → 更新 userId + 清除 tempToken + 清除 cookie

---

## 阶段 5：后端 API — 管理员配置

**目标：** 管理员可配置 system prompt、默认模型、公开工具白名单、系统级 provider/model。

### 任务 5.1 管理员 agent 配置 API
- 文件（新建）：
  - `server/api/admin/agent-config/index.get.ts` — 读取所有 agent 配置
  - `server/api/admin/agent-config/system-prompt.put.ts`
  - `server/api/admin/agent-config/default-model.put.ts`
  - `server/api/admin/agent-config/public-tools.put.ts`
- 复用 config service 的 `getGlobalConfigValue` / `setGlobalConfigValue`

### 任务 5.2 系统级 provider/model 管理 API
- 文件（新建）：
  - `server/api/admin/llm/providers/index.get.ts` — 列出系统级 providers
  - `server/api/admin/llm/providers/index.post.ts` — 创建系统级 provider
  - `server/api/admin/llm/models/index.get.ts` — 列出系统级 models
  - `server/api/admin/llm/models/index.post.ts` — 创建系统级 model
- 权限校验：仅管理员可访问

---

## 阶段 6：前端 — Layout + Composables

**目标：** 建立 agent 前端骨架。

### 任务 6.1 Agent layout
- 文件：`app/layouts/agent.vue`（新建）
- 全屏布局：侧边栏（260px 固定）+ 主对话区
- 无 TopNav、无 BoContainer
- 移动端（< 768px）侧边栏抽屉化

### 任务 6.2 `useAgentSessions` composable
- 文件：`app/composables/useAgentSessions.ts`（新建）
- 状态：`sessions`、`currentSession`、`loading`、`hasMore`
- 方法：`init()`、`loadMore()`、`createSession()`、`switchSession(id)`、`renameSession(id, title)`、`deleteSession(id)`、`updateConfig(id, config)`

### 任务 6.3 `useAgentChat` composable
- 文件：`app/composables/useAgentChat.ts`（新建）
- 基于现有 `useLlmChat` 改造（参考设计文档"useAgentChat 核心设计"5 点差异）
- 状态：`messages`、`isStreaming`、`error`
- 方法：`loadMessages(sessionId)`、`send(content, opts?)`、`stop()`、`clear()`、`editMessage(messageId, content)`、`regenerate()`
- 流式解析：复用 `useLlmChat` 的 MessagePart 模型和 SSE 事件解析

### 任务 6.4 `useAgentRateLimit` composable
- 文件：`app/composables/useAgentRateLimit.ts`（新建）
- 状态：`sessionRemaining`、`ipRemaining`、`blocked`
- 方法：`updateFromHeaders(headers)`、`reset()`

### 任务 6.5 首页改造
- 文件：`app/pages/index.vue`
- 改动：`definePageMeta({ layout: 'agent' })`，渲染 `AgentChatArea` + `AgentSidebar`

---

## 阶段 7：前端 — 组件实现

**目标：** 实现 15 个 agent 组件 + 管理员配置页。

### 任务 7.1 `AgentSidebar` + `AgentSidebarItem`
- 侧边栏：新对话按钮 + session 列表 + 用户信息底部
- 列表项：标题 + 操作菜单（重命名、删除）
- 使用 `useAgentSessions`

### 任务 7.2 `AgentChatArea`
- 主对话区容器：工具栏 + 消息列表 + 输入框
- 空状态显示 `AgentWelcome`

### 任务 7.3 `AgentToolbar`
- 汉堡按钮（移动端）+ 模型选择器 + 推理开关 + 工具开关 + system prompt 按钮
- 未登录用户仅显示模型名

### 任务 7.4 `AgentMessageList` + `AgentMessageItem` + `AgentMessageParts`
- 消息列表：日期分隔线 + 滚动管理（自动滚动/回到最新/顶部加载）
- 消息项：角色区分（用户右侧/assistant 左侧）+ markdown 渲染
- Parts 渲染：text/reasoning/tool-call/tool-result/tool-approval

### 任务 7.5 `AgentToolCallBlock` + `AgentToolResultBlock`
- 工具调用折叠展示：工具名 + 状态图标（✓/✗/调用中/待审批）
- 审批按钮（已登录用户）
- 工具结果折叠展示

### 任务 7.6 `AgentReasoningBlock`
- 推理过程：可折叠 + 流式打字效果
- 默认展开，显示在回复文本上方

### 任务 7.7 `AgentInput`
- 多行自适应输入框 + 发送按钮 + 停止按钮
- Enter 发送 + Shift+Enter 换行
- 限流时禁用 + 提示

### 任务 7.8 `AgentModelSelector`
- 模型下拉选择器
- 已登录用户可切换，未登录用户只读

### 任务 7.9 `AgentSystemPromptModal` + `AgentFeedbackButtons` + `AgentWelcome`
- System prompt 查看弹窗（仅登录用户）
- 反馈按钮（仅登录用户，👍/👎 + 可修改）
- 欢迎页（logo + 示例问题）

### 任务 7.10 管理员配置页
- 文件：`app/pages/admin/agent-config.vue`（新建）
- 三个区块：system prompt 编辑 + 默认模型/标题模型选择 + 公开工具白名单
- 系统级 provider/model 管理入口

---

## 阶段 8：定时任务 + 集成验证

### 任务 8.1 临时 session 清理定时任务
- 文件：`server/scheduler/` 下新增任务
- 每 10 分钟扫描：删除 `expiresAt < now AND deletedAt IS NULL` 的临时 session 及其消息

### 任务 8.2 集成验证
- 启动项目：`bun run dev`
- 验证流程：
  1. 未登录用户访问首页 → 自动创建临时 session → 发送消息 → 流式回复
  2. 未登录用户限流生效（20 条 session / 50 条 IP）
  3. 已登录用户访问首页 → 加载 session 列表 → 切换 session → 发送消息
  4. 已登录用户工具审批流程
  5. 编辑消息 + 重新生成
  6. 登录后迁移临时 session
  7. 管理员配置页设置 system prompt + 默认模型 + 公开工具
  8. 移动端侧边栏抽屉化

### 任务 8.3 Lint + TypeCheck
- 命令：`bun run lint` + `bun run typecheck`
- 修复所有错误

---

## 验证检查点

| 阶段 | 验证方式 |
|------|---------|
| 1 | `bun run db:studio` 查看新表 |
| 2 | 单元测试或手动调用 config service |
| 3 | curl/Postman 测试 session CRUD API |
| 4 | curl 测试对话 API 流式响应 |
| 5 | curl 测试管理员配置 API |
| 6 | 浏览器查看 agent layout 骨架 |
| 7 | 浏览器完整交互测试 |
| 8 | 端到端流程验证 + lint/typecheck 通过 |