Files

HaHafeng 4ed67a8846 fix(admin): Fix Prompt management list not showing version info and add debug diagnostics

Summary:
- Fix Prompt list API response schema missing activeVersion and draftVersion fields
- Fastify was filtering out undefined schema fields, causing version columns to show empty
- Add detailed diagnostic logging for Prompt debug mode troubleshooting
- Verify debug mode works correctly (DRAFT version is used when debug enabled)

Changes:
- backend/src/common/prompt/prompt.routes.ts: Add activeVersion and draftVersion to response schema
- backend/src/common/prompt/prompt.service.ts: Add diagnostic logs for setDebugMode and get methods
- PKB module: Various authentication and document handling fixes from previous session

Tested: Debug mode verified working - v2 DRAFT version correctly loaded when debug enabled

2026-01-13 22:22:10 +08:00

14 KiB

Raw Blame History

AIA 模块 V2.1 开发计划

版本：V2.1
创建日期：2026-01-11
计划周期：约 8-11 天
策略：重写后端 + 复用数据库 + 新开发前端
关联PRD：01-需求分析/AIA模块PRD.md
关联原型：01-需求分析/AI智能问答V2.html

📋 开发策略概述

核心决策

组件	策略	理由
后端	🔴 重写	旧版不符合云原生规范（console.log、未使用平台能力）
数据库	✅ 复用	aia_schema 已完善，字段满足需求
前端	🔴 新开发	复用 shared/components/Chat 通用组件，全新UI

技术规范

规范	要求
日志	使用 `logger` from `@/common/logging`（禁止 console.log）
存储	使用 `storage` from `@/common/storage`
缓存	使用 `cache` from `@/common/cache`
队列	使用 `jobQueue` from `@/common/jobs`
Prompt	使用 `promptService.get()` from `@/common/prompts`
代码位置	`backend/src/modules/aia/`
API路由	`/api/v2/aia/*`

📊 数据库状态（✅ 已完成）

表结构（3个表）

aia_schema.projects        ✅ 保留
aia_schema.conversations   ✅ 保留
aia_schema.messages        ✅ 保留 + 新增字段

新增字段（2026-01-11 已迁移）

表	字段	类型	说明
messages	`thinking_content`	TEXT	深度思考内容 `<think>...</think>`
messages	`attachments`	JSONB	附件数组（上限5个，单个≤20MB，文本≤30K tokens）

已删除表

表	原因
`general_conversations`	功能重叠，使用 conversations.project_id = NULL
`general_messages`	功能重叠

🗓️ 开发阶段

Phase 1: 后端重写（3-4天）

Day 1: 模块骨架 + 核心服务

目标：搭建模块结构，迁移核心对话服务

任务清单：

1.1 创建模块目录结构

backend/src/modules/aia/
├── controllers/
│   ├── conversationController.ts
│   ├── agentController.ts
│   └── projectController.ts
├── services/
│   ├── conversationService.ts
│   ├── agentService.ts
│   └── projectService.ts
├── routes/
│   └── index.ts
├── types/
│   └── index.ts
└── index.ts

1.2 重写 conversationService
- 从 legacy 复制核心逻辑
- 替换 console.log → logger
- 使用 prisma.message（已在 aia_schema）
- 添加 thinkingContent 处理逻辑
- 保持流式输出能力
1.3 重写 agentService
- 改用 promptService.get() 获取 Prompt
- 缓存智能体配置（使用 cache）
1.4 注册 v2 路由
- 注册到 /api/v2/aia/*
- 保持 legacy 路由兼容（逐步迁移）

验收标准：

基础对话功能可用
流式输出正常
日志输出到 logger

Day 2: 深度思考 + 附件上传

目标：实现 V2.1 新增功能

任务清单：

2.1 深度思考模式
- 检测 LLM 输出中的 <think>...</think> 标签
- 提取并存储到 messages.thinking_content
- 从 content 中移除 think 标签
- 流式输出时分离 thinking 和 content
2.2 附件上传服务
- 使用 storage.upload() 上传到 OSS
- 调用 Python 微服务提取文本
- Token 计数（使用 tiktoken）
- 截断处理（超过 30K tokens）
- 存储附件信息到 messages.attachments
2.3 附件注入 LLM 上下文
- 组装附件文本到 User Prompt
- 控制总 Token 长度

技术规格：

// 附件处理配置
const ATTACHMENT_CONFIG = {
  maxCount: 5,              // 每条消息最多5个附件
  maxSizePerFile: 20 * 1024 * 1024,  // 单个文件20MB
  maxTokens: 30000,         // 提取文本最多30K tokens
  supportedTypes: ['pdf', 'docx', 'txt', 'xlsx'],
};

验收标准：

深度思考内容正确分离存储
附件上传成功
附件文本正确注入 LLM

Day 3: 意图路由 + 知识库集成

目标：实现全局意图路由，完善知识库引用

任务清单：

3.1 意图路由服务
- 新建 intentRouterService.ts
- 调用 Router Agent 识别意图
- 返回目标 Agent ID + 预填 Prompt
- 添加 500ms 防抖（前端实现）
3.2 完善知识库集成
- 复用 PKB 模块的 RAG 检索
- 智能引用系统（[来源N]）
- 引用清单格式化

3.3 API 端点完善

POST /api/v2/aia/intent/route          # 意图路由
POST /api/v2/aia/conversations         # 创建对话
GET  /api/v2/aia/conversations         # 对话列表
GET  /api/v2/aia/conversations/:id     # 对话详情
POST /api/v2/aia/conversations/:id/messages/stream  # 发送消息（流式）
POST /api/v2/aia/conversations/:id/attachments      # 上传附件
GET  /api/v2/aia/agents                # 智能体列表
GET  /api/v2/aia/agents/:id            # 智能体详情

验收标准：

意图路由正确识别并跳转
知识库引用正确显示
所有 API 端点可用

Day 4: 测试 + 文档

目标：完成后端测试和文档

任务清单：

4.1 单元测试
- conversationService 测试
- 深度思考解析测试
- 附件处理测试
4.2 集成测试
- 完整对话流程
- 附件上传流程
- 知识库检索流程
4.3 API 文档
- 更新 REST Client 测试文件
- 编写 API 使用示例

验收标准：

测试覆盖核心功能
API 文档完整

Phase 2: 前端开发（5-7天）

Day 5-6: 智能体大厅（Dashboard）

目标：实现首页智能体大厅

任务清单：

5.1 创建模块目录结构

frontend-v2/src/modules/aia/
├── pages/
│   ├── Dashboard.tsx          # 智能体大厅
│   └── Workspace.tsx          # 对话工作台
├── components/
│   ├── AgentPipeline.tsx      # 5阶段流水线
│   ├── AgentCard.tsx          # 智能体卡片
│   ├── IntentSearch.tsx       # 意图搜索框
│   ├── ConversationList.tsx   # 历史会话列表
│   ├── ThinkingBlock.tsx      # 深度思考折叠块
│   ├── AttachmentUpload.tsx   # 附件上传
│   ├── AttachmentCard.tsx     # 附件卡片
│   └── SlashCommands.tsx      # 快捷指令
├── hooks/
│   ├── useConversation.ts
│   ├── useAgents.ts
│   └── useIntentRouter.ts
├── api/
│   └── index.ts
├── types/
│   └── index.ts
└── index.tsx

5.2 智能体流水线（AgentPipeline）
- 5阶段布局（严格还原 V11 原型）
- 3色视觉体系
- 卡片点击跳转 Workspace
- 工具卡片跳转外部模块（DC/ST）
5.3 意图搜索框（IntentSearch）
- 顶部大搜索框
- 500ms 防抖
- 调用意图路由 API
- 自动跳转目标 Agent

验收标准：

5阶段流水线正确展示
意图搜索功能可用
与原型图一致

Day 7-8: 对话工作台（Workspace）

目标：实现沉浸式对话界面

任务清单：

7.1 工作台布局
- Gemini 风格（大留白、少分割线）
- 左侧侧边栏（历史会话，可折叠）
- 主对话区（Header + 消息列表 + 输入框）

7.2 复用 Chat 通用组件

import { ChatContainer } from '@/shared/components/Chat';

<ChatContainer
  providerConfig={{
    apiEndpoint: '/api/v2/aia/conversations/:id/messages/stream',
    requestFn: sendMessageWithStream,
  }}
  customMessageRenderer={renderAIAMessage}
/>

7.3 深度思考折叠块（ThinkingBlock）
- 可折叠灰色引用块
- 生成中展开，完成后自动收起
- 显示"已深度思考 (耗时 Xs)"
7.4 附件上传组件
- 支持拖拽上传
- 文件类型/大小校验
- 上传进度显示
- 消息气泡下方附件卡片
7.5 历史会话列表
- 按时间分组（今天、昨天、7天前）
- 桌面端固定显示
- 移动端抽屉滑出

验收标准：

Gemini 风格 UI
深度思考正确展示
附件上传完整流程
历史会话切换

Day 9: Markdown 增强 + 快捷指令

目标：增强对话体验

任务清单：

9.1 Markdown 渲染增强
- KaTeX 公式渲染（医学公式）
- 表格横向滚动
- 代码块语法高亮 + 一键复制
9.2 快捷指令（SlashCommands）
- 输入 / 弹出菜单
- 支持：/润色, /扩写, /翻译, /导出Word
- 键盘导航
9.3 结果操作栏
- Hover 显示工具栏
- 复制（Markdown 源码）
- 重新生成
- 导出 Word（调用 RVW 导出服务）

验收标准：

公式正确渲染
快捷指令可用
操作栏功能完整

Day 10: 移动端适配

目标：响应式布局适配

任务清单：

10.1 Dashboard 移动端
- 隐藏复杂导航
- 卡片单列流式布局
- 时间轴样式调整
10.2 Workspace 移动端
- 侧边栏改为抽屉
- 输入框键盘适配（scrollIntoView）
- 发送按钮始终可见
10.3 触控优化
- 按钮 active 态
- 触控区域优化

验收标准：

md (768px) 断点响应正确
移动端交互流畅

Day 11: 集成测试 + 优化

目标：完成整体测试和优化

任务清单：

11.1 端到端测试
- 完整对话流程
- 附件上传流程
- 深度思考流程
- 知识库引用流程
11.2 性能优化
- TTFB < 1.5s
- 移动端 LCP < 1s
- 意图搜索防抖
11.3 Bug 修复
11.4 文档更新
- 更新模块状态文档
- 更新系统当前状态

验收标准：

所有功能正常
性能达标
文档完整

📁 文件清单

后端新增文件

backend/src/modules/aia/
├── controllers/
│   ├── conversationController.ts    # ~300行
│   ├── agentController.ts           # ~150行
│   └── projectController.ts         # ~200行
├── services/
│   ├── conversationService.ts       # ~500行（核心）
│   ├── agentService.ts              # ~200行
│   ├── projectService.ts            # ~150行
│   ├── intentRouterService.ts       # ~100行（新）
│   └── attachmentService.ts         # ~200行（新）
├── routes/
│   └── index.ts                     # ~100行
├── types/
│   └── index.ts                     # ~100行
└── index.ts                         # ~20行

预计总计：~2000行

前端新增文件

frontend-v2/src/modules/aia/
├── pages/
│   ├── Dashboard.tsx                # ~400行
│   └── Workspace.tsx                # ~500行
├── components/
│   ├── AgentPipeline.tsx            # ~300行
│   ├── AgentCard.tsx                # ~100行
│   ├── IntentSearch.tsx             # ~150行
│   ├── ConversationList.tsx         # ~200行
│   ├── ThinkingBlock.tsx            # ~100行
│   ├── AttachmentUpload.tsx         # ~200行
│   ├── AttachmentCard.tsx           # ~80行
│   └── SlashCommands.tsx            # ~150行
├── hooks/
│   ├── useConversation.ts           # ~150行
│   ├── useAgents.ts                 # ~100行
│   └── useIntentRouter.ts           # ~80行
├── api/
│   └── index.ts                     # ~200行
├── types/
│   └── index.ts                     # ~100行
└── index.tsx                        # ~50行

预计总计：~2900行

🔗 依赖关系

后端依赖

依赖	来源	说明
`logger`	`@/common/logging`	日志服务
`storage`	`@/common/storage`	OSS存储
`cache`	`@/common/cache`	Redis/PG缓存
`jobQueue`	`@/common/jobs`	异步任务
`promptService`	`@/common/prompts`	Prompt管理
`LLMFactory`	`@/common/llm`	LLM适配器
`prisma`	`@/config/database`	数据库
`ExtractionClient`	`@/clients`	文档提取
`TokenService`	`@/services`	Token计数

前端依赖

依赖	来源	说明
`ChatContainer`	`@/shared/components/Chat`	通用对话组件
`Ant Design`	`antd`	UI组件库
`Ant Design X`	`@ant-design/x`	AI对话组件
`KaTeX`	`katex`	公式渲染
`react-markdown`	`react-markdown`	Markdown渲染

📈 风险评估

风险	概率	影响	缓解措施
流式输出兼容性	中	高	复用已验证的 SSE 代码
附件提取超时	中	中	使用 jobQueue 异步处理
移动端适配问题	低	中	提前规划断点和布局
Prompt管理服务未就绪	低	中	可临时回退到文件读取

✅ 验收标准

功能验收

智能体大厅完整展示
意图搜索正确路由
多轮对话正常
流式输出流畅
深度思考正确折叠
附件上传完整
知识库引用正确
快捷指令可用
移动端适配正常

性能验收

TTFB < 1.5s
移动端 LCP < 1s
意图搜索响应 < 500ms

质量验收

无 console.log（使用 logger）
代码符合云原生规范
API 文档完整
单元测试覆盖核心功能

📝 更新日志

日期	版本	内容
2026-01-11	V1.0	创建开发计划

计划制定人：AI Assistant
审核人：待定
批准人：待定

14 KiB Raw Blame History Unescape Escape

AIA 模块 V2.1 开发计划

📋 开发策略概述

核心决策

技术规范

📊 数据库状态（✅ 已完成）

表结构（3个表）

新增字段（2026-01-11 已迁移）

已删除表

🗓️ 开发阶段

Phase 1: 后端重写（3-4天）

Day 1: 模块骨架 + 核心服务

Day 2: 深度思考 + 附件上传

Day 3: 意图路由 + 知识库集成

Day 4: 测试 + 文档

Phase 2: 前端开发（5-7天）

Day 5-6: 智能体大厅（Dashboard）

Day 7-8: 对话工作台（Workspace）

Day 9: Markdown 增强 + 快捷指令

Day 10: 移动端适配

Day 11: 集成测试 + 优化

📁 文件清单

后端新增文件

前端新增文件

🔗 依赖关系

后端依赖

前端依赖

📈 风险评估

✅ 验收标准

功能验收

性能验收

质量验收

📝 更新日志

14 KiB

Raw Blame History