weichen/Agent-System
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(spec): 编写历史多轮对话持久化与已批准交付物标杆案例语义检索设计规范

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
WeiCHEN
2026-09-08 13:31:39 +08:00
co-authored by Cursor
parent 86d9e31c00
commit dd36da4aa7
1 changed files with 292 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/specs/2026-09-08-semantic-chat-history-and-case-retrieval-design.md
+292
View File
@@ -0,0 +1,292 @@
# 历史多轮对话持久化与已批准交付物标杆案例语义检索设计规范
## 一、 背景与业务目标 (Background & Objectives)
在医疗器械 CDMO 商务与研发协同体系中，商务对接人员和技术专家需要频繁应对两类核心痛点：
1. **多轮对话上下文断裂与无法回溯**：以往会话仅缓存在服务内存中，服务重启后多轮历史消息丢失，无法跨会话查看历史决策；此外缺乏对历史多轮对话的分页查询与语义召回支持；
2. **往期成功案例与标杆经验沉淀孤立**：历史项目中由各阶段专员编制、并经审批人终审生效的正式合规交付物（如注册评估、系统架构设计、CDO工时报价表）未能自动提取为高价值知识。新项目立项咨询时，无法迅速检索出“是否做过同类产品？当年怎么报的注册？工时和价格是多少？”，导致知识资产浪费与重复踩坑。
本规范旨在设计并落地**「双核联动：多轮会话持久化与上下文回溯 + 标杆案例语义向量自推荐」**引擎：
- **多轮会话持久化与重构**：实现 `chat_sessions` 与 `chat_messages` 的双向读写，支持根据 `session_id` 恢复上下文与历史记忆；
- **终态交付物自动向量化沉淀**：受控文档审批通过（`approved`）时，自动触发清洗、切片、向量化并存入 `context_memory_chunks`；
- **双路语义召回与参谋锦囊赋能**：结合 `pgvector` 余弦相似度与全文分词检索，在自然语言提问与阶段推进中自动召回 Top-K 标杆案例，注入贴身业务参谋决策锦囊（B轨），实现经验复用与智能辅助。
---
## 二、 整体架构与数据流图 (Architecture & Data Flow)
```
┌──────────────────────────────────────────────┐
│ 客户端 / Web / CLI │
└───────┬───────────────────────────────▲──────┘
│ (1) Chat / Stream 请求 │ (6) 参谋回复 + 标杆案例建议
▼ │
┌──────────────────────────────┐ │
│ Chat / Session 调度引擎 │ │
└───────┬──────────────▲───────┘ │
│ │ (3) 注入历史与相似标杆 │
(2) 持久化 │ │ │
多轮消息 ▼ │ │
┌──────────────────────────────┐ │ ┌──────────────────────────────┐
│ ContextManager 记忆引擎 │───┴───┤ 语义向量化与双路检索 │
│ (chat_sessions & messages) │ │ (context_memory_chunks) │
└──────────────────────────────┘ └──────────────▲───────────────┘
│
(4) 终态触发 │ (5) 章节切片 +
自动索引 │ bge-m3 / Mock 向量化
┌──────────────┴───────────────┐
│ 受控文档审批引擎 (DocGov) │
│ (ApproverApprove 终态归档) │
└──────────────────────────────┘
```
### 数据流关键节点：
1. **请求接入与会话恢复**：API 收到请求时，若内存未命中则从 PostgreSQL 加载历史消息并重构 `UserProjectContext`；
2. **多轮留痕**：用户发言与参谋应答写入 `chat_messages`，并异步驱动用户工作习惯偏好更新；
3. **标杆案例沉淀**：受控文档在审批人生效（`approved`）后，自动提取 Markdown 二级章节，生成 1024 维向量切片，打上 `domain = "approved_case"` 入库；
4. **混合召回**：在自然语言提问时，基于 `pgvector` HNSW 索引与全文检索综合打分，过滤低于阈值（0.60）的噪音；
5. **决策赋能**：将相似案例的器械类型、核心合规依据、参考报价与避坑点注入 B 轨参谋锦囊中的 `RecommendedCases`。
---
## 三、 数据库模式设计 (Database Schema)
基于已有 `deploy/postgres/context_init.sql`，核心表映射如下：
### 1. `chat_sessions` & `chat_messages`
```sql
CREATE TABLE IF NOT EXISTS chat_sessions (
id BIGSERIAL PRIMARY KEY,
session_id TEXT NOT NULL UNIQUE,
user_id BIGINT REFERENCES users(id) ON DELETE SET NULL,
project_id BIGINT REFERENCES projects(id) ON DELETE SET NULL,
title TEXT NOT NULL DEFAULT '对话协同会话',
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE TABLE IF NOT EXISTS chat_messages (
id BIGSERIAL PRIMARY KEY,
session_id TEXT NOT NULL,
user_id BIGINT,
role TEXT NOT NULL, -- 'user' | 'assistant' | 'system'
content TEXT NOT NULL,
intent TEXT NOT NULL DEFAULT '',
branch TEXT NOT NULL DEFAULT '',
metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
```
### 2. `context_memory_chunks` (向量与全文混合存储)
```sql
CREATE TABLE IF NOT EXISTS context_memory_chunks (
id BIGSERIAL PRIMARY KEY,
domain TEXT NOT NULL, -- 'approved_case', 'chat_history', 'project_doc'
project_id BIGINT REFERENCES projects(id) ON DELETE CASCADE,
user_id BIGINT REFERENCES users(id) ON DELETE SET NULL,
reference_id TEXT NOT NULL DEFAULT '', -- 对应 doc_id 或 session_id
title TEXT NOT NULL DEFAULT '', -- 章节标题或案例标题
content TEXT NOT NULL, -- 章节正文提要
chunk_hash TEXT NOT NULL DEFAULT '', -- 幂等防重哈希
embedding vector(1024), -- 1024 维向量
tsv tsvector, -- 全文检索分词
importance_weight NUMERIC(4,2) NOT NULL DEFAULT 1.00,
metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX IF NOT EXISTS idx_mem_chunks_domain_proj ON context_memory_chunks(domain, project_id, created_at DESC);
CREATE INDEX IF NOT EXISTS idx_mem_chunks_hash ON context_memory_chunks(chunk_hash);
CREATE INDEX IF NOT EXISTS idx_mem_chunks_tsv ON context_memory_chunks USING gin (tsv);
CREATE INDEX IF NOT EXISTS idx_mem_chunks_vec ON context_memory_chunks USING hnsw (embedding vector_cosine_ops);
```
---
## 四、 核心数据模型与 Go 接口定义 (Data Models & Interfaces)
### 1. 案例推荐与会话查询结构体 (`internal/ctxmgr/types.go`)
```go
package ctxmgr
import (
"time"
)
// CaseRecommendationItem 相似标杆案例自推荐条目
type CaseRecommendationItem struct {
DocID string `json:"doc_id"`
ProjectID int64 `json:"project_id"`
ProjectName string `json:"project_name"`
TaskKey string `json:"task_key"`
ArtifactTitle string `json:"artifact_title"`
SectionTitle string `json:"section_title"`
SummarySnippet string `json:"summary_snippet"`
KeyRegulations []string `json:"key_regulations,omitempty"`
SimilarityScore float64 `json:"similarity_score"`
ApprovedAt string `json:"approved_at"`
}
// CaseSearchOptions 标杆案例语义检索参数
type CaseSearchOptions struct {
Query string `json:"query"`
TaskKey string `json:"task_key,omitempty"`
ExcludeDoc string `json:"exclude_doc,omitempty"`
Limit int `json:"limit"`
MinScore float64 `json:"min_score"`
}
// SessionFilter 历史会话查询过滤条件
type SessionFilter struct {
UserID int64 `json:"user_id,omitempty"`
ProjectID int64 `json:"project_id,omitempty"`
Limit int `json:"limit"`
Offset int `json:"offset"`
}
// ChatSessionSummary 会话摘要说明
type ChatSessionSummary struct {
SessionID string `json:"session_id"`
Title string `json:"title"`
UserID int64 `json:"user_id"`
ProjectID int64 `json:"project_id,omitempty"`
ProjectName string `json:"project_name,omitempty"`
MessageCount int `json:"message_count"`
LastMessage string `json:"last_message,omitempty"`
UpdatedAt time.Time `json:"updated_at"`
}
```
### 2. 贴身业务参谋锦囊扩展 (`internal/squad/types.go`)
```go
type AdvisorBriefing struct {
MaturityScore int `json:"maturity_score"`
MaturityLevel string `json:"maturity_level"`
MaturityHeadline string `json:"maturity_headline"`
BaselineAssumptions []string `json:"baseline_assumptions"`
ProactiveRisks []string `json:"proactive_risks"`
RecommendedActions []string `json:"recommended_actions"`
CommunicationKit string `json:"communication_kit"`
RecommendedCases []CaseRecommendationItem `json:"recommended_cases,omitempty"` // 💡 往期标杆案例自推荐
}
```
### 3. ContextManager 核心接口契约 (`internal/ctxmgr/manager.go`)
```go
// IndexApprovedDocument 对已终审批准的交付物执行切片、向量化与入库沉淀
func (m *ContextManager) IndexApprovedDocument(ctx context.Context, doc *docgov.DocumentRecord, markdownBody string) ([]int64, error)
// SearchSimilarCases 检索与指定查询最相似的往期标杆案例
func (m *ContextManager) SearchSimilarCases(ctx context.Context, opts CaseSearchOptions) ([]CaseRecommendationItem, error)
// ListChatSessions 分页查询历史会话
func (m *ContextManager) ListChatSessions(ctx context.Context, filter SessionFilter) ([]ChatSessionSummary, error)
// GetChatHistory 分页获取指定会话多轮历史消息
func (m *ContextManager) GetChatHistory(ctx context.Context, sessionID string, limit, offset int) ([]ChatMessageRecord, error)
// RestoreSessionContext 从持久化存储中重建会话上下文
func (m *ContextManager) RestoreSessionContext(ctx context.Context, sessionID string) (*coordinator.UserProjectContext, []chat.Message, error)
```
---
## 五、 RESTful API 契约设计
### 1. 历史会话列表查询
- **路径**：`GET /api/v1/chat/sessions`
- **查询参数**：
- `user_id` (可选): 用户ID
- `project_id` (可选): 项目ID
- `limit` (默认 20, 最大 100)
- `offset` (默认 0)
- **响应格式**：
```json
[
{
"session_id": "sess_1788844000",
"title": "超声软组织手术刀研发项目咨询",
"user_id": 301,
"project_id": 501,
"project_name": "超声软组织切割止血手术设备",
"message_count": 6,
"last_message": "已完成法规初筛与初步架构评估",
"updated_at": "2026-09-08T13:18:30Z"
}
]
```
### 2. 指定会话多轮历史消息查询
- **路径**：`GET /api/v1/chat/messages?session_id={session_id}&limit=50&offset=0`
- **响应格式**：
```json
[
{
"id": 1,
"session_id": "sess_1788844000",
"user_id": 301,
"role": "user",
"content": "我们要做一款超声止血刀，主要用于外科软组织切割闭合。",
"intent": "SUPPLEMENT_INFO",
"branch": "EXPECTATION_HIT",
"created_at": "2026-09-08T13:10:00Z"
},
{
"id": 2,
"session_id": "sess_1788844000",
"user_id": 0,
"role": "assistant",
"content": "已为您锁定超声软组织设备初始画像...",
"intent": "ADVANCE_STAGE",
"branch": "EXPECTATION_HIT",
"created_at": "2026-09-08T13:10:05Z"
}
]
```
### 3. 标杆案例语义自推荐检索
- **路径**：`GET /api/v1/context/cases/recommend?query={query}&task_key={task_key}&limit=3`
- **响应格式**：
```json
[
{
"doc_id": "doc_proj1001_feasibility_reg",
"project_name": "4K超高清荧光硬管内窥镜摄像系统",
"task_key": "feasibility_reg",
"artifact_title": "注册路径可行性评估报告",
"section_title": "## 关键性能与型检预估",
"summary_snippet": "针对微创荧光内窥镜，重点关注YY 0068.1硬管镜机械强度与双波长光学滤光衰减特性...",
"key_regulations": ["YY 0068.1", "GB 9706.1-2020", "YY 9706.218"],
"similarity_score": 0.88,
"approved_at": "2026-09-08T13:16:41Z"
}
]
```
---
## 六、 离线降级与异常处理规范 (Error Handling & Fallback)
1. **确定性降级向量生成器 (Deterministic Fallback Embedder)**：
- 当 Embedder 服务未配置或由于网络断开无法连接外部端点时，自动启用基于语义哈希的高维正交投影算法，将文本特征投射为 1024 维单位向量，确保在单元测试与离线环境无依赖运行。
2. **切片幂等防重 (`chunk_hash`)**：
- 采用 `SHA256(doc_id + ":" + section_title + ":" + content)` 唯一索引，重复审批或多次执行不会产生冗余垃圾切片。
3. **阈值截断与低匹配度静默**：
- 设定相似度硬截断门限（0.60），低于此匹配度的案例不予推荐，避免无意义弱关联案例误导用户。
---
## 七、 质量验收与测试方案 (Test & Quality Gate)
1. **单元测试与集成测试**：
- `internal/ctxmgr/chat_history_test.go`：多轮对话分页查询、双向写入与上下文重建；
- `internal/ctxmgr/case_recommend_test.go`：文档切片向量化入库与 pgvector 语义相似度召回；
- `internal/server/chat_history_api_test.go`：RESTful API 契约与 HTTP 状态码端到端校验。
2. **CLI 真实交互演练**：
- 验证用户在自然语言问询时，贴身业务参谋决策锦囊中呈现清晰的高亮标杆案例推荐板块。
3. **测试报告归档**：
- 统一归档至 `.doc/test-reports/2026-09-08-semantic-chat-and-case-retrieval-test-report.md`。