12 KiB

Raw Blame History

首页 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 通过

12 KiB Raw Blame History