kevin/life-echo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(api,expo): 多智能体与会话收敛、回忆录兼容层移除、后端测试集大幅删减

Browse Source 
- 对齐「多智能体收敛」与「回忆录 stories-first / markdown-first」方向：收紧运行时契约、
  删除过渡兼容路径与双轨逻辑，并同步更新客户端与文档。

- Chat：以 ChatOrchestrator 为实时编排入口；删除独立 conversation_agent，精简 prompts。
- Memoir：删除 memory_agent；MemoirOrchestrator、classification / story_route 与 prompts 收敛到
  prepare_batches + run_story_pipeline_for_category_batch 主链路。
- 将 agents 侧 processor 迁入 feature 层为 background_runner，并移除 features 下重复/过时
  processor 封装。

- 新增 history_store，强化「conversation_messages 为 DB 真源、Redis 为缓存」模型。
- 调整 models、repo、service、session_history；精简 WS message_types，重构 pipeline 与 router。

- 移除章节占位、整章再生等旧路径；章节列表与封面逻辑要求 story 关联；收紧 cover 资格与
  enqueue。
- helpers、repo、service、router、reading_segment_materialize、story_pipeline_sync、pdf_service
  等按 canonical markdown / cover_asset_id 收缩；删除 memoir_images/provider 等冗余。
- tasks：memoir_tasks、chapter_cover_tasks 等大幅瘦身；story_image_tasks 等与当前图片任务对齐。

- core：config、logging、redis、task_tracker 小幅调整。
- auth / user / payment / quota：路由或服务侧删减过时接口或逻辑（如 payment router 行数减少）。

- pyproject.toml、development.sh、.env.example / .env.production、README 等同步说明或变量。

- Alembic 0001_initial_schema 微调（与当前 schema 叙事一致的小改动）。

- 回忆录：types / mappers / api、章节页与 memoir 页与后端契约对齐；markdown-renderer 调整。
- 语音：删除 voice/player，voice-segment-store 相应精简。

- api/tests：删除 conftest 及绝大部分既有测试文件（websocket_baseline、conversation、memoir
  图片、PDF、SMS 等），属有意收缩/待按 backend-test-system 重建的信号。
- docs：新增多智能体收敛与移除兼容层计划摘要；更新 story-first 设计、backend-test-system、
  multi-agent-refactor-plan、实施总结等。

BREAKING CHANGE: 后端对外契约、回忆录章节字段与若干路由/任务行为已变更；大量 API 测试被移除，
  CI 若依赖这些用例需按新策略补测或调整流水线。
This commit is contained in:
Kevin
2026-03-22 16:45:57 +08:00
parent 70070216c4
commit 786ebf8ae6
122 changed files with 2802 additions and 7941 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
api/app/agents/memoir/__init__.py
View File

@@ -1,19 +1,25 @@
"""回忆录模块：MemoryAgent、BackgroundTaskRunner、MemoirOrchestrator、各 Specialist Agent"""
"""回忆录模块：MemoirOrchestrator、各 Specialist Agent。"""
from app.agents.memoir.memory_agent import MemoryAgent
from app.agents.memoir.processor import BackgroundTaskRunner
from app.agents.memoir.orchestrator import MemoirOrchestrator
from app.agents.memoir.extraction_agent import ExtractionAgent, ExtractionResult
from app.agents.memoir.classification_agent import ClassificationAgent
from app.agents.memoir.extraction_agent import ExtractionAgent, ExtractionResult
from app.agents.memoir.narrative_agent import NarrativeAgent
from app.agents.memoir.story_route_agent import StoryRouteAgent, StoryRouteDecision
from app.agents.memoir.orchestrator import MemoirOrchestrator, PreparedMemoirBatches
from app.agents.memoir.story_route_agent import (
StoryBatchPlan,
StoryBatchPlanUnit,
StoryRouteAgent,
StoryRouteDecision,
validate_story_batch_plan,
)
__all__ = [
"MemoryAgent",
"BackgroundTaskRunner",
"MemoirOrchestrator",
"PreparedMemoirBatches",
"StoryRouteAgent",
"StoryRouteDecision",
"StoryBatchPlan",
"StoryBatchPlanUnit",
"validate_story_batch_plan",
"ExtractionAgent",
"ExtractionResult",
"ClassificationAgent",

9
api/app/agents/memoir/classification_agent.py
View File

@@ -7,12 +7,11 @@ from __future__ import annotations
from typing import Any, Optional
from app.core.logging import get_logger
from app.agents.memoir.prompts import (
CHAPTER_CATEGORIES,
get_chapter_classification_prompt,
)
from app.core.logging import get_logger
logger = get_logger(__name__)
@@ -64,8 +63,10 @@ class ClassificationAgent:
response = llm.invoke(prompt)
category = (response.content or "").strip().lower()
if category == "none":
logger.info(
"LLM 判定内容无回忆录价值，跳过: %s...", (text or "")[:80]
logger.debug(
"LLM 判定内容无回忆录价值，跳过: text_len=%s text=%s",
len(text or ""),
text or "",
)
return None
if category in CHAPTER_CATEGORIES:

126
api/app/agents/memoir/memory_agent.py
View File

@@ -1,126 +0,0 @@
"""
回忆录整理 Agent：基于传记结构，将口语改写为书面语，归类到章节
支持异步调用
"""
import json
from typing import Dict, List, Optional
from app.agents.memoir.prompts import (
CHAPTER_CATEGORIES,
STAGE_TO_ORDER,
get_chapter_classification_prompt,
get_text_rewrite_prompt,
)
from app.core.dependencies import get_llm_provider
from app.core.langchain_llm import bind_json_object_mode
from app.core.logging import get_logger
from app.features.memoir.memoir_images.json_payload import extract_json_payload
logger = get_logger(__name__)
def _get_langchain_llm():
try:
provider = get_llm_provider()
return getattr(provider, "langchain_llm", None)
except Exception:
return None
class MemoryAgent:
"""回忆录整理 Agent（支持异步）"""
def __init__(self):
self.llm = _get_langchain_llm()
async def classify_chapter(self, segments_text: str) -> str:
if not self.llm:
return "childhood"
try:
prompt = get_chapter_classification_prompt(segments_text)
response = await self.llm.ainvoke(prompt)
content = (
response.content if hasattr(response, "content") else str(response)
)
category = content.strip().lower()
if category in CHAPTER_CATEGORIES:
return category
except Exception as e:
logger.error("分类章节失败: %s", e)
return "childhood"
async def rewrite_to_literary(
self,
segments_text: str,
chapter_category: str,
existing_content: Optional[str] = None,
) -> Dict:
if not self.llm:
return {
"title": CHAPTER_CATEGORIES.get(chapter_category, "章节"),
"content": segments_text,
"summary": "",
"image_suggestions": [],
}
try:
prompt = get_text_rewrite_prompt(
segments_text, chapter_category, existing_content or ""
)
json_llm = bind_json_object_mode(self.llm, max_tokens=4096)
response = await json_llm.ainvoke(prompt)
content = (
response.content if hasattr(response, "content") else str(response)
)
content = content.strip()
result = json.loads(extract_json_payload(content))
return result
except json.JSONDecodeError:
raw = response.content if hasattr(response, "content") else str(response)
return {
"title": CHAPTER_CATEGORIES.get(chapter_category, "章节"),
"content": raw,
"summary": "",
"image_suggestions": [],
}
except Exception as e:
logger.error("改写文本失败: %s", e)
return {
"title": CHAPTER_CATEGORIES.get(chapter_category, "章节"),
"content": segments_text,
"summary": "",
"image_suggestions": [],
}
async def process_segments(
self,
segments: List[Dict],
existing_chapters: Optional[Dict[str, Dict]] = None,
) -> Dict[str, Dict]:
if existing_chapters is None:
existing_chapters = {}
segments_by_category: Dict[str, List[str]] = {}
for segment in segments:
text = segment.get("transcript_text", "")
if not text:
continue
category = await self.classify_chapter(text)
if category not in segments_by_category:
segments_by_category[category] = []
segments_by_category[category].append(text)
updated_chapters = existing_chapters.copy()
for category, texts in segments_by_category.items():
combined_text = "\n\n".join(texts)
existing_content = existing_chapters.get(category, {}).get("content", "")
result = await self.rewrite_to_literary(
combined_text, category, existing_content
)
updated_chapters[category] = {
"title": result.get("title", CHAPTER_CATEGORIES.get(category, "章节")),
"content": result.get("content", ""),
"summary": result.get("summary", ""),
"image_suggestions": result.get("image_suggestions", []),
"category": category,
"order_index": STAGE_TO_ORDER.get(category, 999),
}
return updated_chapters

113
api/app/agents/memoir/orchestrator.py
View File

@@ -6,21 +6,31 @@ MemoirOrchestrator：按 segment 编排流水线，调用各 Specialist Agent。
from __future__ import annotations
from dataclasses import dataclass
from typing import Any, Callable, Dict, List, Set, Tuple
from app.core.logging import get_logger
from app.features.conversation.models import Segment
from app.agents.state_schema import MemoirStateSchema
from app.agents.memoir.extraction_agent import ExtractionAgent, ExtractionResult
from app.agents.memoir.classification_agent import (
ClassificationAgent,
)
from app.agents.memoir.classification_agent import (
_detect_stage as detect_stage_from_keywords,
)
from app.agents.memoir.extraction_agent import ExtractionAgent, ExtractionResult
from app.agents.state_schema import MemoirStateSchema
from app.core.logging import get_logger
from app.features.conversation.models import Segment
logger = get_logger(__name__)
@dataclass
class PreparedMemoirBatches:
"""Explicit batching result: updated state + segments grouped by chapter category."""
state: MemoirStateSchema
category_to_segments: Dict[str, List[Segment]]
class MemoirOrchestrator:
"""
回忆录生成编排器。
@@ -32,6 +42,57 @@ class MemoirOrchestrator:
self.extraction_agent = ExtractionAgent()
self.classification_agent = ClassificationAgent()
def prepare_batches(
self,
*,
segments: List[Segment],
llm: Any,
get_or_create_state: Callable[[], MemoirStateSchema],
update_slot: Callable[[str, str, str, List[str]], MemoirStateSchema],
) -> PreparedMemoirBatches:
"""
遍历 segments：Extraction → slot 更新 → Classification → 按 category 分桶。
不含锁与写章节/故事（由调用方显式执行）。
"""
state = get_or_create_state()
category_to_segments: Dict[str, List[Segment]] = {}
for segment in segments:
text = segment.transcript_text or ""
initial_stage = detect_stage_from_keywords(
text, state.current_stage or "childhood"
)
stage_slots_raw = state.slots.get(initial_stage, {}) or {}
result: ExtractionResult = self.extraction_agent.extract(
user_message=text,
current_stage=state.current_stage or "childhood",
stage_slots=stage_slots_raw,
llm=llm,
)
detected_stage = result.detected_stage
for slot_name, snippet in result.slots.items():
state = update_slot(detected_stage, slot_name, snippet, [segment.id])
chapter_category = self.classification_agent.classify(
text=text,
fallback_stage=detected_stage,
llm=llm,
)
if chapter_category is None:
logger.debug(
"段落无回忆录价值，跳过: segment_id=%s transcript=%s",
segment.id,
getattr(segment, "transcript_text", None) or "",
)
continue
category_to_segments.setdefault(chapter_category, []).append(segment)
return PreparedMemoirBatches(
state=state,
category_to_segments=category_to_segments,
)
def run(
self,
*,
@@ -63,41 +124,17 @@ class MemoirOrchestrator:
返回 (chapters_to_enqueue, processed_count)。
raise_retry 用于锁竞争时抛出 Celery retry。
"""
state = get_or_create_state()
prepared = self.prepare_batches(
segments=segments,
llm=llm,
get_or_create_state=get_or_create_state,
update_slot=update_slot,
)
state = prepared.state
chapters_to_enqueue: Set[str] = set()
category_to_segments: Dict[str, List[Segment]] = {}
category_to_segments = prepared.category_to_segments
# 1) 遍历 segments：ExtractionAgent → 更新 slots；ClassificationAgent → 聚合
for segment in segments:
text = segment.transcript_text or ""
# 关键词预检测阶段，用于 slot 查找（与原有逻辑一致）
initial_stage = detect_stage_from_keywords(
text, state.current_stage or "childhood"
)
stage_slots_raw = state.slots.get(initial_stage, {}) or {}
result: ExtractionResult = self.extraction_agent.extract(
user_message=text,
current_stage=state.current_stage or "childhood",
stage_slots=stage_slots_raw,
llm=llm,
)
detected_stage = result.detected_stage
for slot_name, snippet in result.slots.items():
state = update_slot(detected_stage, slot_name, snippet, [segment.id])
# ClassificationAgent
chapter_category = self.classification_agent.classify(
text=text,
fallback_stage=detected_stage,
llm=llm,
)
if chapter_category is None:
logger.info("段落无回忆录价值，跳过: segment_id=%s", segment.id)
continue
category_to_segments.setdefault(chapter_category, []).append(segment)
# 2) 按 category 调用 process_category：叙事生成、持久化、封面入队标记
# 按 category 调用 process_category：叙事生成、持久化、封面入队标记
for chapter_category, category_segments in category_to_segments.items():
if not acquire_lock(chapter_category):
logger.warning(

67
api/app/agents/memoir/processor.py
View File

@@ -1,67 +0,0 @@
"""
回忆录后台处理器：debounce 聚合后派发 Celery 任务
实际回忆录生成由 memoir_tasks.process_memoir_segments 调用 MemoirOrchestrator 完成
"""
from __future__ import annotations
from typing import Dict, List
from app.core.logging import get_logger
from app.core.task_tracker import task_tracker
logger = get_logger(__name__)
class BackgroundTaskRunner:
def __init__(self, debounce_seconds: int = 5) -> None:
self.debounce_seconds = debounce_seconds
self._pending: Dict[str, List[str]] = {}
self._timers: Dict[str, object] = {}
async def _submit_task(self, user_id: str, segment_ids: List[str]) -> str | None:
try:
from app.tasks.memoir_tasks import process_memoir_segments
result = process_memoir_segments.delay(user_id, segment_ids)
task_id = result.id
await task_tracker.add_task(user_id, task_id, "memoir")
logger.info(
"已提交 Celery 任务: user_id=%s, task_id=%s, segments=%s",
user_id,
task_id,
len(segment_ids),
)
return task_id
except Exception as e:
logger.error("提交 Celery 任务失败: %s", e)
return None
async def queue_message(self, user_id: str, segment_id: str) -> None:
import asyncio
self._pending.setdefault(user_id, []).append(segment_id)
if user_id in self._timers:
self._timers[user_id].cancel()
async def delayed_submit():
try:
await asyncio.sleep(self.debounce_seconds)
segment_ids = self._pending.pop(user_id, [])
if segment_ids:
await self._submit_task(user_id, segment_ids)
except asyncio.CancelledError:
pass
except Exception as e:
logger.error("延迟提交任务失败: %s", e)
self._timers[user_id] = asyncio.create_task(delayed_submit())
async def flush_pending(self, user_id: str) -> str | None:
if user_id in self._timers:
self._timers[user_id].cancel()
del self._timers[user_id]
segment_ids = self._pending.pop(user_id, [])
if segment_ids:
return await self._submit_task(user_id, segment_ids)
return None

59
api/app/agents/memoir/prompts.py
View File

@@ -386,10 +386,11 @@ def get_narrative_json_prompt(
1. 从对话中提炼与人生经历相关的核心内容，过滤语气词、寒暄、与AI的交互
2. 使用第一人称，改写为流畅的书面叙述，不要直接引用对话原话
3. 只输出新内容的改写，不要重复已有内容
4. 每 200-300 字左右一个段落
5. 如有衔接上下文，确保新内容与之自然衔接
6. **不要使用 Markdown 表格**（不要用 `|` 管道表格）
7. **不要用 `#`、`##` 写故事或章节标题**；标题由系统管理
4. **本批输入对应一个独立叙事单元**：只围绕同一主题/事件链展开，不要写入与上述对话无关的其他话题或回忆
5. 每 200-300 字左右一个段落
6. 如有衔接上下文，确保新内容与之自然衔接
7. **不要使用 Markdown 表格**（不要用 `|` 管道表格）
8. **不要用 `#`、`##` 写故事或章节标题**；标题由系统管理
## 输出格式（严格 JSON）
{{
@@ -417,6 +418,8 @@ def get_story_route_prompt(
- append_story：内容明显延续、补充某一已有故事的主题与时间线，且能对应到具体 candidate id
- new_story：新话题、新人生阶段片段，或与所有候选故事都不够贴合
「故事」在此指：**可独立讲述的一段人生经历**——单一主题或同一事件链；不要假设本批里包含多个互不相关的故事（多段由系统其它步骤处理）。
当前章节（写作容器）：
- category: {chapter_category}
- title: {chapter_title}
@@ -441,6 +444,54 @@ def get_story_route_prompt(
"""
def get_story_batch_plan_prompt(
*,
chapter_category: str,
chapter_title: str,
segments_json: str,
candidate_stories_json: str,
) -> str:
"""同一章节类别下多 segment：划分为若干写入单元（每单元 new 或 append）。输出严格 JSON。"""
return f"""你是回忆录编辑助手。下面同一章节类别下有一批**按时间顺序**的用户口述片段（每段有 id 与文本）。
## 「故事」定义（必须遵守）
一段「故事」= **可独立讲述的一段人生经历**：单一主题或同一事件链，能单独成篇。若话题切换、时间线跳到另一件事、人物/主线明显变化，应作为**新的故事**（new_story），而不是塞进同一段 append。
## 任务
将本批 segment **划分为连续若干块**（每块包含至少一个 segment，顺序不能打乱；每个 segment 必须恰好属于一块）。对每一块决定：
- **append_story**：内容明显延续、补充**某一已有候选故事**的主题与时间线，且能对应到具体 candidate id
- **new_story**：新话题、与所有候选故事都不够贴合、或应独立成篇的片段
当前章节（写作容器）：
- category: {chapter_category}
- title: {chapter_title}
【本批口述片段】（JSON 数组，顺序即口述顺序）
{segments_json}
【候选故事】（仅允许在 append 时选择其中的 id；id 必须原样复制）
{candidate_stories_json}
## 输出 JSON（仅此一个对象，不要 markdown）
{{
"units": [
{{
"segment_ids": ["<按顺序列出本块包含的 segment id>"],
"decision": "new_story" | "append_story",
"target_story_id": "<uuid 或 null；append 时必填且必须来自候选>",
"new_story_title": "<短标题，6-20 字；new_story 时必填，append 时可 null>",
"reason": "<一句中文理由，可选>"
}}
]
}}
规则：
- `units` 中所有 `segment_ids` 拼接后，必须**不重不漏**地覆盖本批全部 id，且顺序与【本批口述片段】数组一致
- 若无法自信匹配某一候选，对该块选 new_story
- new_story_title 应概括该块内容，不要与候选标题重复
"""
def format_evidence_chunks_for_prompt(evidence: dict) -> str:
"""将 retrieve_evidence 结果格式化为简短文本，供叙事 prompt 使用。"""
chunks = evidence.get("relevant_chunks") or []

117
api/app/agents/memoir/story_route_agent.py
View File

@@ -9,7 +9,10 @@ from typing import Any, Literal
from pydantic import BaseModel, field_validator
from app.agents.memoir.prompts import get_story_route_prompt
from app.agents.memoir.prompts import (
get_story_batch_plan_prompt,
get_story_route_prompt,
)
from app.core.langchain_llm import bind_json_object_mode
from app.core.logging import get_logger
from app.features.story.models import Story
@@ -17,6 +20,33 @@ from app.features.story.models import Story
logger = get_logger(__name__)
# 超过此数量跳过批量规划（单次路由），避免 prompt 过大
PLAN_BATCH_MAX_SEGMENTS = 48
class StoryBatchPlanUnit(BaseModel):
"""批量写入中的一个单元（连续 segment 块）。"""
segment_ids: list[str]
decision: Literal["new_story", "append_story"]
target_story_id: str | None = None
new_story_title: str | None = None
reason: str | None = None
@field_validator("target_story_id", mode="before")
@classmethod
def empty_str_to_none_tid(cls, v: Any) -> str | None:
if v is None or v == "":
return None
if isinstance(v, str):
return v.strip() or None
return str(v)
class StoryBatchPlan(BaseModel):
units: list[StoryBatchPlanUnit]
class StoryRouteDecision(BaseModel):
decision: Literal["new_story", "append_story"]
target_story_id: str | None = None
@@ -57,6 +87,51 @@ def _build_candidate_json(stories: list[Story], *, preview_chars: int = 220) ->
return json.dumps(rows, ensure_ascii=False, indent=2)
def _build_segments_json_for_plan(
segments: list[tuple[str, str]], *, text_preview_chars: int = 4000
) -> str:
"""segments: (id, transcript_text) 按口述顺序。"""
rows: list[dict[str, str]] = []
for sid, text in segments:
t = (text or "").strip()
if len(t) > text_preview_chars:
t = t[:text_preview_chars] + "…"
rows.append({"id": sid, "text": t})
return json.dumps(rows, ensure_ascii=False, indent=2)
def validate_story_batch_plan(
ordered_segment_ids: list[str],
plan: StoryBatchPlan,
valid_story_ids: set[str],
) -> tuple[bool, str | None]:
"""
校验：segment 全覆盖、顺序一致、append 目标合法、new_story 有标题。
返回 (ok, error_code)。
"""
if not plan.units:
return False, "empty_units"
flat: list[str] = []
for u in plan.units:
if not u.segment_ids:
return False, "empty_unit_segment_ids"
flat.extend(u.segment_ids)
if len(flat) != len(set(flat)):
return False, "duplicate_segment"
if flat != ordered_segment_ids:
return False, "segment_mismatch"
for u in plan.units:
if u.decision == "append_story":
tid = u.target_story_id
if not tid or tid not in valid_story_ids:
return False, "invalid_append_target"
else:
title = (u.new_story_title or "").strip()
if not title:
return False, "missing_new_title"
return True, None
class StoryRouteAgent:
def decide(
self,
@@ -112,3 +187,43 @@ class StoryRouteAgent:
):
decision.new_story_title = None
return decision
def plan_batch(
self,
*,
chapter_category: str,
chapter_title: str,
segments: list[tuple[str, str]],
candidate_stories: list[Story],
llm: Any,
valid_story_ids: set[str],
) -> StoryBatchPlan | None:
"""
将本批 segment 划分为多个写入单元。解析失败返回 None，由调用方回退 decide()。
"""
if not llm or len(segments) < 2:
return None
payload = _build_candidate_json(candidate_stories)
segments_json = _build_segments_json_for_plan(segments)
prompt = get_story_batch_plan_prompt(
chapter_category=chapter_category,
chapter_title=chapter_title,
segments_json=segments_json,
candidate_stories_json=payload,
)
try:
json_llm = bind_json_object_mode(llm, max_tokens=4096)
response = json_llm.invoke(prompt)
raw = (response.content or "").strip()
data = json.loads(raw)
plan = StoryBatchPlan.model_validate(data)
except Exception as e:
logger.warning("StoryRouteAgent.plan_batch 解析失败: %s", e)
return None
ordered = [s[0] for s in segments]
ok, err = validate_story_batch_plan(ordered, plan, valid_story_ids)
if not ok:
logger.warning("StoryRouteAgent.plan_batch 校验失败: %s", err)
return None
return plan