Merge branch 'feature/rag2' into develop

* feature/rag2:
  [fix] system prompt fit error
  [modify] QA pair

.github/workflows/release-notify-wechat.yml

@@ -0,0 +1,164 @@
+name: Release Notify Workflow
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  notify:
+    if: >
+      github.event.pull_request.merged == true &&
+      startsWith(github.event.pull_request.base.ref, 'release')
+    runs-on: ubuntu-latest
+
+    steps:
+      # 防止 GitHub HEAD 未同步
+      - run: sleep 3
+
+      # 1️⃣ 获取分支 HEAD
+      - name: Get HEAD
+        id: head
+        run: |
+          HEAD_SHA=$(curl -s \
+            -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
+            https://api.github.com/repos/${{ github.repository }}/git/ref/heads/${{ github.event.pull_request.base.ref }} \
+            | jq -r '.object.sha')
+          echo "head_sha=$HEAD_SHA" >> $GITHUB_OUTPUT
+
+      # 2️⃣ 判断是否最终PR
+      - name: Check Latest
+        id: check
+        run: |
+          if [ "${{ github.event.pull_request.merge_commit_sha }}" = "${{ steps.head.outputs.head_sha }}" ]; then
+            echo "ok=true" >> $GITHUB_OUTPUT
+          else
+            echo "ok=false" >> $GITHUB_OUTPUT
+          fi
+
+      # 3️⃣ 尝试从 PR body 提取 Sourcery 摘要
+      - name: Extract Sourcery Summary
+        if: steps.check.outputs.ok == 'true'
+        id: sourcery
+        env:
+          PR_BODY: ${{ github.event.pull_request.body }}
+        run: |
+          python3 << 'PYEOF'
+          import os, re
+
+          body = os.environ.get("PR_BODY", "") or ""
+          match = re.search(
+              r"## Summary by Sourcery\s*\n(.*?)(?=\n## |\Z)",
+              body,
+              re.DOTALL
+          )
+
+          if match:
+              summary = match.group(1).strip()
+              found = "true"
+          else:
+              summary = ""
+              found = "false"
+
+          with open("sourcery_summary.txt", "w", encoding="utf-8") as f:
+              f.write(summary)
+
+          with open(os.environ["GITHUB_OUTPUT"], "a") as gh:
+              gh.write(f"found={found}\n")
+              gh.write("summary<<EOF\n")
+              gh.write(summary + "\n")
+              gh.write("EOF\n")
+          PYEOF
+
+      # 4️⃣ Fallback: 获取 commits + 通义千问总结
+      - name: Get Commits
+        if: steps.check.outputs.ok == 'true' && steps.sourcery.outputs.found == 'false'
+        run: |
+          curl -s \
+            -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
+            ${{ github.event.pull_request.commits_url }} \
+            | jq -r '.[].commit.message' | head -n 20 > commits.txt
+
+      - name: AI Summary (Qwen Fallback)
+        if: steps.check.outputs.ok == 'true' && steps.sourcery.outputs.found == 'false'
+        id: qwen
+        env:
+          DASHSCOPE_API_KEY: ${{ secrets.DASHSCOPE_API_KEY }}
+        run: |
+          python3 << 'PYEOF'
+          import json, os, urllib.request
+
+          with open("commits.txt", "r") as f:
+              commits = f.read().strip()
+
+          prompt = "请用中文总结以下代码提交，输出3-5条要点，面向测试人员。直接输出编号列表，不要输出标题或前言：\n" + commits
+          payload = {"model": "qwen-plus", "input": {"prompt": prompt}}
+          data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+
+          req = urllib.request.Request(
+              "https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation",
+              data=data,
+              headers={
+                  "Authorization": "Bearer " + os.environ["DASHSCOPE_API_KEY"],
+                  "Content-Type": "application/json"
+              }
+          )
+          resp = urllib.request.urlopen(req)
+          result = json.loads(resp.read().decode())
+          summary = result.get("output", {}).get("text", "AI 摘要生成失败")
+
+          with open(os.environ["GITHUB_OUTPUT"], "a") as gh:
+              gh.write("summary<<EOF\n")
+              gh.write(summary + "\n")
+              gh.write("EOF\n")
+          PYEOF
+
+      # 5️⃣ 企业微信通知（Markdown）
+      - name: Notify WeChat
+        if: steps.check.outputs.ok == 'true'
+        env:
+          WECHAT_WEBHOOK: ${{ secrets.WECHAT_WEBHOOK }}
+          BRANCH: ${{ github.event.pull_request.base.ref }}
+          AUTHOR: ${{ github.event.pull_request.user.login }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}
+          SOURCERY_FOUND: ${{ steps.sourcery.outputs.found }}
+          SOURCERY_SUMMARY: ${{ steps.sourcery.outputs.summary }}
+          QWEN_SUMMARY: ${{ steps.qwen.outputs.summary }}
+        run: |
+          python3 << 'PYEOF'
+          import json, os, urllib.request
+
+          if os.environ.get("SOURCERY_FOUND") == "true":
+              label = "Summary by Sourcery"
+              summary = os.environ.get("SOURCERY_SUMMARY", "")
+          else:
+              label = "AI变更摘要"
+              summary = os.environ.get("QWEN_SUMMARY", "AI 摘要生成失败")
+
+          pr_number = os.environ.get("PR_NUMBER", "")
+          short_sha = os.environ.get("MERGE_SHA", "")[:7]
+
+          content = (
+            "## 🚀 Release 发布通知\n"
+            "> <20> **分支**: " + os.environ["BRANCH"] + "\n"
+            "> 👤 **提交人**: " + os.environ["AUTHOR"] + "\n"
+            "> 📝 **标题**: " + os.environ["PR_TITLE"] + "\n"
+            "> 🔢 **PR编号**: #" + pr_number + "\n"
+            "> 🔖 **Commit**: " + short_sha + "\n\n"
+            "### 🧠 " + label + "\n" +
+            summary + "\n\n"
+            "---\n"
+            "🔗 [查看PR详情](" + os.environ["PR_URL"] + ")"
+          )
+          payload = {"msgtype": "markdown", "markdown": {"content": content}}
+          data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+          req = urllib.request.Request(
+            os.environ["WECHAT_WEBHOOK"],
+            data=data,
+            headers={"Content-Type": "application/json"}
+          )
+          resp = urllib.request.urlopen(req)
+          print(resp.read().decode())
+          PYEOF

.github/workflows/sync-to-gitee.yml

@@ -0,0 +1,33 @@
+name: Sync to Gitee
+
+on:
+  push:
+    branches:
+      - '**' # All branchs
+    tags:
+      - '**'      # All version tags (v1.0.0, etc.)
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Source Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Sync to Gitee
+        run: |
+          GITEE_URL="https://${{ secrets.GITEE_USERNAME }}:${{ secrets.GITEE_TOKEN }}@gitee.com/hangzhou-hongxiong-intelligent_1/MemoryBear.git"
+          git remote add gitee "$GITEE_URL"
+
+          # 遍历并推送所有分支
+          for branch in $(git branch -r | grep -v HEAD | sed 's/origin\///'); do
+            echo "Syncing branch: $branch"
+            git push -f gitee "origin/$branch:refs/heads/$branch"
+          done
+
+          # 推送所有标签
+          echo "Syncing tags..."
+          git push gitee --tags --force

.gitignore

@@ -18,6 +18,7 @@ examples/
 .kiro
 .vscode
 .idea
+.claude
 
 # Temporary outputs
 .DS_Store
@@ -25,10 +26,14 @@ examples/
 time.log
 celerybeat-schedule.db
 search_results.json
+redbear-mem-metrics/
+redbear-mem-benchmark/
+pitch-deck/
 
 api/migrations/versions
 tmp
 files
+powers/ 
 
 # Exclude dep files
 huggingface.co/

CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing to MemoryBear
+
+感谢你对 MemoryBear 的关注！我们欢迎任何形式的贡献。
+
+## 如何贡献
+
+### 报告问题
+
+- 使用 [GitHub Issues](https://github.com/SuanmoSuanyangTechnology/MemoryBear/issues) 提交 Bug 报告或功能建议
+- 提交前请先搜索是否已有相同的 Issue
+
+### 提交代码
+
+1. Fork 本仓库
+2. 创建功能分支：`git checkout -b feature/your-feature-name`
+3. 提交更改：遵循 [Conventional Commits](https://www.conventionalcommits.org/) 格式
+4. 推送分支：`git push origin feature/your-feature-name`
+5. 创建 Pull Request
+6. Pull Request合并的目标分支为develop
+
+### Commit 格式
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+```
+
+**Type 类型：**
+
+| Type | 说明 |
+|------|------|
+| `feat` | 新功能 |
+| `fix` | Bug 修复 |
+| `docs` | 文档更新 |
+| `style` | 代码格式（不影响逻辑） |
+| `refactor` | 重构（非新功能、非修复） |
+| `perf` | 性能优化 |
+| `test` | 测试相关 |
+| `chore` | 构建/工具链变更 |
+
+**示例：**
+
+```
+feat(extraction): add ALIAS_OF relationship for entity deduplication
+fix(search): correct hybrid search ranking when activation values are missing
+docs(readme): update architecture diagram with generated images
+```
+
+### 开发环境
+
+```bash
+# 后端
+cd api
+pip install uv && uv sync
+source .venv/bin/activate
+pytest  # 运行测试
+
+# 前端
+cd web
+npm install
+npm run lint  # 代码检查
+npm run dev   # 开发服务器
+```
+
+### 代码规范
+
+- Python：遵循 PEP 8，行宽不超过 120 字符
+- TypeScript：通过 ESLint 检查
+- 提交前确保测试通过
+
+## 行为准则
+
+请保持友善和尊重。我们致力于为所有人提供一个开放、包容的社区环境。

README.md

@@ -1,213 +1,306 @@
-<img width="2346" height="1310" alt="image" src="https://github.com/user-attachments/assets/bc73a64d-cd1e-4d22-be3e-04ce40423a20" />
+<img width="2346" height="1310" alt="MemoryBear Hero Banner" src="https://github.com/user-attachments/assets/2c0a3f72-1a14-4017-93c8-a7f490d545b6" />
 
-# MemoryBear empowers AI with human-like memory capabilities
+<div align="center">
+
+# MemoryBear — Empowering AI with Human-Like Memory
+
+**Next-Generation AI Memory Management System · Perceive · Extract · Associate · Forget**
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-3.12+-green?logo=python&logoColor=white)](https://www.python.org/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-teal?logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)
+[![Neo4j](https://img.shields.io/badge/Neo4j-4.4+-blue?logo=neo4j&logoColor=white)](https://neo4j.com/)
+[![Gitee Sync](https://img.shields.io/github/actions/workflow/status/SuanmoSuanyangTechnology/MemoryBear/sync-to-gitee.yml?label=Gitee%20Sync&logo=gitee&logoColor=white)](https://github.com/SuanmoSuanyangTechnology/MemoryBear/actions/workflows/sync-to-gitee.yml)
 
 [中文](./README_CN.md) | English
 
-### [Installation Guide](#memorybear-installation-guide)
-### Paper: <a href="https://memorybear.ai/pdf/memoryBear" target="_blank" rel="noopener noreferrer">《Memory Bear AI: A Breakthrough from Memory to Cognition》</a>
-## Project Overview
-MemoryBear is a next-generation AI memory system independently developed by RedBear AI. Its core breakthrough lies in moving beyond the limitations of traditional "static knowledge storage". Inspired by the cognitive mechanisms of biological brains, MemoryBear builds an intelligent knowledge-processing framework that spans the full lifecycle of perception, refinement, association, and forgetting.The system is designed to free machines from the trap of mere "information accumulation", enabling deep knowledge understanding, autonomous evolution, and ultimately becoming a key partner in human-AI cognitive collaboration.
+[Quick Start](#quick-start) · [Installation](#installation) · [Core Features](#core-features) · [Architecture](#architecture) · [Benchmarks](#benchmarks) · [Papers](#papers)
 
-## MemoryBear was created to address these challenges
-### 1. Core causes of knowledge forgetting in single models</br>
-Context window limitations: Mainstream large language models typically have context windows of 8k-32k tokens. In long conversations, earlier messages are pushed out of the window, causing later responses to lose their historical context.For example, a user says in turn 1, "I'm allergic to seafood", but by turn 5 when they ask, "What should I have for dinner tonight?" the model may have already forgotten the allergy information.</br>
+</div>
 
-Gap between static knowledge bases and dynamic data: The model's training corpus is a static snapshot (e.g., data up to 2023) and cannot continuously absorb personalized information from user interactions, such as preferences or order history. External memory modules are required to supplement and maintain this dynamic, user-specific knowledge.</br>
+---
 
-Limitations of the attention mechanism: In Transformer architectures, self-attention becomes less effective at capturing long-range dependencies as the sequence grows. This leads to a recency bias, where the model overweights the latest input and ignores crucial information that appeared earlier in the conversation.</br>
+## Overview
 
-### 2. Memory gaps in multi-agent collaboration</br>
-Data silos between agents: Different agents-such as a consulting agent, after-sales agent, and recommendation agent-often maintain their own isolated memories without a shared layer. As a result, users have to repeat information. For instance, after providing their address to the consulting agent, the user may be asked for it again by the after-sales agent.</br>
+MemoryBear is a next-generation AI memory system developed by RedBear AI. Its core breakthrough lies in moving beyond the limitations of traditional "static knowledge storage". Inspired by the cognitive mechanisms of biological brains, MemoryBear builds an intelligent knowledge-processing framework that spans the full lifecycle of **perception → extraction → association → forgetting**.
 
-Inconsistent dialogue state: When switching between agents in multi-turn interactions, key dialogue state-such as the user's current intent or past issue labels-may not be passed along completely. This causes service discontinuities. For example,a user transitions from "product inquiry" to "complaint", but the new agent does not inherit the complaint details discussed earlier.</br>
+Unlike traditional memory tools that treat knowledge as static data to be retrieved, MemoryBear emulates the hippocampus's memory encoding, the neocortex's knowledge consolidation, and synaptic pruning-based forgetting — enabling knowledge to dynamically evolve with life-like properties. This shifts the relationship between AI and users from **passive lookup** to **proactive cognitive assistance**.
 
-Conflicting decisions: Agents that only see partial memory can generate contradictory responses. For example, a recommendation agent might suggest products that the user is allergic to, simply because it does not have access to the user's recorded health constraints.</br>
+## Papers
 
-### 3. Semantic ambiguity during model reasoning distorted understanding of personalized context</br>
-Personalized signals in user conversations-such as domain-specific jargon, colloquial expressions, or context-dependent references-are often not encoded accurately, leading to semantic drift in how the model interprets memory. For instance, when the user refers to "that plan we discussed last time", the model may be unable to reliably locate the specific plan in previous conversations. Broken cross-lingual and dialect memory links in multilingual or dialect-rich scenarios, cross-language associations in memory may fail. When a user mixes Chinese and English in their requests, the model may struggle to integrate information expressed across languages.</br>
+| Paper | Description |
+|-------|-------------|
+| 📄 [Memory Bear AI: A Breakthrough from Memory to Cognition](https://memorybear.ai/pdf/memoryBear) | MemoryBear core technical report |
+| 📄 [Memory Bear AI Memory Science Engine for Multimodal Affective Intelligence](https://arxiv.org/abs/2603.22306) | Technical report on multimodal affective intelligence memory engine |
+| 📄 [A-MBER: Affective Memory Benchmark for Emotion Recognition](https://arxiv.org/abs/2604.07017) | Affective memory benchmark dataset |
 
-Typical example: A user says: "Last time customer support told me it could be processed 'as an urgent case'. What's the status now?" If the system never encoded what "urgent" corresponds to in terms of a concrete service level, the model can only respond with vague, unhelpful answers.</br>
+## Why MemoryBear
 
-## Core Positioning of MemoryBear
-Unlike traditional memory management tools that treat knowledge as static data to be retrieved, MemoryBear is designed around the goal of simulating the knowledge-processing logic of the human brain. It builds a closed-loop system that spans the entire lifecycle-from knowledge intake to intelligent output. By emulating the hippocampus's memory encoding, the neocortex's knowledge consolidation, and synaptic pruning-based forgetting mechanisms, MemoryBear enables knowledge to dynamically evolve with "life-like" properties. This fundamentally redefines the relationship between knowledge and its users-shifting from passive lookup to proactive cognitive assistance.</br>
+### Knowledge Forgetting in Single Models
 
-## Core Philosophy of MemoryBear
-MemoryBear's design philosophy is rooted in deep insight into the essence of human cognition: the value of knowledge does not lie in its accumulation, but in the continuous transformation and refinement that occurs as it flows.
+- **Context window limits**: Mainstream LLMs have 8k–32k token windows. In long conversations, early messages are pushed out, causing responses to lose historical context
+- **Static knowledge gap**: Training data is a static snapshot — it cannot absorb personalized information (preferences, history) from live interactions
+- **Recency bias**: Transformer self-attention weakens on long-range dependencies, overweighting recent input and ignoring earlier critical information
 
-In traditional systems, once stored, knowledge becomes static-hard to associate across domains and incapable of adapting to users' cognitive needs. MemoryBear, by contrast, is built on the belief that true intelligence emerges only when knowledge undergoes a full evolutionary process: raw information distilled into structured rules, isolated rules connected into a semantic network, redundant information intelligently forgotten. Through this progression, knowledge shifts from mere informational memory to genuine cognitive understanding, enabling the emergence of real intelligence.</br>
+### Memory Gaps in Multi-Agent Collaboration
 
-## Core Features of MemoryBear
-As an intelligent memory management system inspired by biological cognitive processes, MemoryBear centers its capabilities on two dimensions: full-lifecycle knowledge memory management and intelligent cognitive evolution. It covers the complete chain-from memory ingestion and refinement to storage, retrieval, and dynamic optimization-while providing a standardized service architecture that ensures efficient integration and invocation across applications.</br>
+- **Data silos**: Different agents (consulting, after-sales, recommendation) maintain isolated memories, forcing users to repeat information
+- **Inconsistent dialogue state**: When switching agents, user intent and history labels are not fully passed along, causing service discontinuities
+- **Decision conflicts**: Agents with partial memory can produce contradictory responses (e.g., recommending products a user is allergic to)
 
-### 1. Memory Extraction Engine: Multi-dimensional Structured Refinement as the Foundation of Cognition</br>
-Memory extraction is the starting point of MemoryBear's cognitive-oriented knowledge management. Unlike traditional data extraction, which performs "mechanical transformation", MemoryBear focuses on semantic-level parsing of unstructured information and standardized multi-format outputs, ensuring precise compatibility with downstream graph construction and intelligent retrieval. Core capabilities include:</br>
+### Semantic Ambiguity in Reasoning
 
-Accurate parsing of diverse information types: The engine automatically identifies and extracts core information from declarative sentences, removing redundant modifiers while preserving the essential subject-action-object logic. It also extracts structured triples (e.g., "MemoryBear-core functionality-knowledge extraction"), providing atomic data units for graph storage and ensuring high-accuracy knowledge association.</br>
+- Domain jargon, colloquial expressions, and context-dependent references are not accurately encoded, leading to semantic drift in memory interpretation
+- Cross-language memory associations fail in multilingual or dialect-rich scenarios
 
-Temporal information anchoring: For time-sensitive knowledge-such as event logs, policy documents, or experimental data-the engine automatically extracts timestamps and associates them with the content. This enables time-based reasoning and resolves the "temporal confusion" found in traditional knowledge systems.</br>
+<img width="2294" height="1154" alt="Why MemoryBear" src="https://github.com/user-attachments/assets/5e4192d8-ab76-402a-9e80-50d6ede147b9" />
 
-Intelligent pruning summarization: Based on contextual semantic understanding, the engine generates summaries that cover all key information with strong logical coherence. Users may customize summary length (50-500 words) and emphasis (technical, business, etc.), enabling fast knowledge acquisition across scenarios.Example: For a 10-page technical document, MemoryBear can produce a concise summary including core parameters, implementation logic, and application scenarios in under 3 seconds.</br>
+---
 
-### 2. Graph Storage: Neo4j-Powered Visual Knowledge Networks</br>
-The storage layer adopts a graph-first architecture, integrating with the mature Neo4j graph database to manage knowledge entities and relationships efficiently. This overcomes limitations of traditional relational databases-such as weak relational modeling and slow complex queries-and mirrors the biological "neuron-synapse" cognition model.</br>
+## Core Features
 
-Key advantages include:
-Scalable, flexible storage: supportting millions of entities and tens of millions of relational edges, covering 12 core relationship types (hierarchical, causal, temporal, logical, etc.) to fit multi-domain knowledge applications. Seamless integration with the extraction module: Extracting triples synchronize directly into Neo4j, automatically constructing the initial knowledge graph with zero manual mapping. Interactive graph visualization: users can intuitively explore entity connection paths, adjust relationship weights, and perform hybrid "machine-generated + human-optimized" graph management.</br>
+<img width="2294" height="1154" alt="MemoryBear Core Features" src="https://github.com/user-attachments/assets/5ae1e2bf-24be-4487-9065-7209f2a57f65" />
 
-### 3. Hybrid Search: Keyword + Semantic Vector for Precision and Intelligence</br>
-To overcome the classic tradeoff-precision but rigidity vs. fuzziness but inaccuracy-MemoryBear implements a hybrid retrieval framework combining keyword search and semantic vector search.</br>
+### Memory Extraction Engine
 
-Keyword search: Optimized with Lucene, enabling millisecond-level exact matching of structured Semantic vector search:Powered by BERT embeddings, transforming queries into high-dimensional vectors for deep semantic comparison. This allows recognition of synonyms, near-synonyms, and implicit intent.For example, the query "How to optimize memory decay efficiency?" may surface related knowledge such as "forgetting-mechanism parameter tuning" or "memory strength evaluation methods".
-Intelligent fusion strategy:Semantic retrieval expands the candidate space; keyword retrieval then performs precise filtering.This dual-stage process increases retrieval accuracy to 92%, improving by 35% compared with single-mode retrieval.</br>
+Performs **semantic-level parsing** of unstructured conversations and documents to extract:
 
-### 4. Memory Forgetting Engine: Dynamic Decay Based on Strength & Timeliness</br>
-Forgetting is one of MemoryBear's defining features-setting it apart from static knowledge systems. Inspired by the brain's synaptic pruning mechanism, MemoryBear models forgetting using a dual-dimension approach based on memory strength and time decay, ensuring redundant knowledge is removed while key knowledge retains cognitive priority.</br>
+- **Core declarative information**: Strips redundant modifiers, preserving subject-action-object logic
+- **Structured triples**: Automatically extracts entity relationships (e.g., `MemoryBear → core function → knowledge extraction`) as atomic units for graph storage
+- **Temporal anchoring**: Automatically extracts and tags timestamps, enabling time-based knowledge tracing
+- **Intelligent summarization**: Customizable length (50–500 words) and focus; generates concise summaries of 10-page documents in under 3 seconds
 
-Implementation details:Each knowledge item is assigned an initial memory strength (determined by extraction quality and manual importance labels). Strength is updated dynamically according to usage frequency and association activity; A configurable time-decay cycle defines how different knowledge types (core rules vs. temporary data) lose strength over time. When knowledge falls below the strength threshold and exceeds its validity period, it enters a three-stage lifecycle: Dormancy-retained but with lower retrieval priority. Decay-gradually compressed to reduce storage cost. Clearance -permanently removed and archived into cold storage. This mechanism maintains redundant knowledge under 8%, reducing waste by over 60% compared with systems lacking forgetting capabilities.</br>
+### Graph Storage (Neo4j)
 
-### 5. Self-Reflection Engine: Periodic Optimization for Autonomous Memory Evolution</br>
-The self-reflection mechanism is key to MemoryBear's "intelligent self-improvement'. It periodically revisits, validates, and optimizes existing knowledge, mimicking the human behavior of review and retrospection.</br>
+**Graph-first architecture** integrated with Neo4j, overcoming the weak relational modeling of traditional databases:
 
-A scheduled reflection process runs automatically at midnight each day, performing:
-1. Consistency checks, Detects logical conflicts across related knowledge (e.g., contradictory attributes for the same entity), flags suspicious records, and routes them for human verification;
-2. Value assessment, Evaluates invocation frequency and contribution to associations. High-value knowledge is reinforced; low-value knowledge experiences accelerated decay;
-3. Association optimization, Adjusts relationship weights based on recent usage and retrieval behavior, strengthening high-frequency association paths.</br>
+- Supports millions of entities and tens of millions of relational edges
+- Covers 12 core relationship types: hierarchical, causal, temporal, logical, and more
+- Extracted triples sync directly to Neo4j, automatically building the initial knowledge graph
+- Interactive graph visualization with "machine-generated + human-optimized" collaborative management
 
-### 6. FastAPI Services: Standardized API Layer for Efficient Integration & Management</br>
-To support seamless integration with external business systems, MemoryBear uses FastAPI to build a unified service architecture that exposes both management and service APIs with high performance, easy integration, and strong consistency. Service-side APIs cover knowledge extraction, graph operations, search queries, forgetting management, and more. Support JSON/XML formats, with average latency below 50 ms, and a single instance sustaining 1000 QPS concurrency. Management-side APIs provide configuration, permissions, log queries, batch knowledge import/export, reflection cycle adjustments, and other operational capabilities. Swagger API documentation is auto-generated, including parameter descriptions, request samples, and response schemas, enabling rapid integration and testing. The architecture is compatible with enterprise microservice ecosystems, supports Docker-based deployment, and integrates easily with CRM, OA, R&D management, and various business applications.</br>
+### Hybrid Search
 
-## MemoryBear Architecture Overview
-<img width="2294" height="1154" alt="image" src="https://github.com/user-attachments/assets/3afd3b49-20ea-4847-b9ed-38b646a4ad89" />
-</br>
-- Memory Extraction Engine: Preprocessing, deduplication, and structured knowledge extraction</br>
-- Memory Forgetting Engine: Memory strength modeling and decay strategies</br>
-- Memory Reflection Engine: Evaluation and rewriting of stored memories</br>
-- Retrieval Services: Keyword search, semantic search, and hybrid retrieval</br>
-- Agent & MCP Integration: Multi-tool collaborative agent capabilities</br>
+**Keyword retrieval + semantic vector retrieval** dual-engine fusion:
 
-## Metrics
-We evaluate MemoryBear across multiple datasets covering different types of tasks, comparing its performance with other memory-enabled systems. The evaluation metrics include F1 score (F1), BLEU-1 (B1), and LLM-as-a-Judge score (J)-where higher values indicate better performance. MemoryBear achieves state-of-the-art results across all task categories: 
-In single-hop scenarios, MemoryBear leads in precision, answer matching quality, and task specificity.
-In multi-hop reasoning, it demonstrates stronger information coherence and higher reasoning accuracy.
-In open generalization tasks, it exhibits superior capability in handling diverse, unbounded information and maintaining high-quality generalization.
-In temporal reasoning tasks, it excels at aligning and processing time-sensitive information.
-Across the core metrics of all four task types, MemoryBear consistently outperforms other competing systems in the industry, including Mem O, Zep, and LangMem, demonstrating significantly stronger overall performance.
+- Keyword search powered by Elasticsearch for millisecond-level exact matching of structured information
+- Semantic vector search via BERT embeddings, recognizing synonyms, near-synonyms, and implicit intent
+- Semantic retrieval expands the candidate space; keyword retrieval then performs precise filtering
+- Retrieval accuracy reaches **92%**, improving **35%** over single-mode retrieval
 
-<img width="2256" height="890" alt="image" src="https://github.com/user-attachments/assets/5ff86c1f-53ac-4816-976d-95b48a4a10c0" />
-MemoryBear's vector-based knowledge memory (non-graph version) achieves substantial improvements in retrieval efficiency while maintaining high accuracy. Its overall accuracy surpasses the best existing full-text retrieval methods (72.90 ± 0.19%). More importantly, it maintains low latency across critical metrics-including Search Latency and Total Latency at both p50 and p95-demonstrating the characteristics of higher performance with greater latency efficiency. This effectively resolves the common bottleneck in full-text retrieval systems, where high accuracy typically comes at the cost of significantly increased latency.
+### Memory Forgetting Engine
 
-<img width="2248" height="498" alt="image" src="https://github.com/user-attachments/assets/2759ea19-0b71-4082-8366-e8023e3b28fe" />
-MemoryBear further unlocks its potential in tasks requiring complex reasoning and relationship awareness through the integration of a knowledge-graph architecture. Although graph traversal and reasoning introduce a slight retrieval overhead, this version effectively keeps latency within an efficient range by optimizing graph-query strategies and decision flows. More importantly, the graph-based MemoryBear pushes overall accuracy to a new benchmark (75.00 ± 0.20%). While maintaining high accuracy, it delivers performance metrics that significantly surpass all other methods, demonstrating the decisive advantage of structured memory systems.
+Inspired by the brain's **synaptic pruning** mechanism, using a dual-dimension model of memory strength and time decay:
 
-<img width="2238" height="342" alt="image" src="https://github.com/user-attachments/assets/c928e094-45a2-414b-831a-6990b711ed07" />
+- Each knowledge item is assigned an initial memory strength, updated dynamically by usage frequency and association activity
+- When strength falls below threshold, knowledge enters a **dormancy → decay → clearance** three-stage lifecycle
+- Redundant knowledge maintained below **8%**, reducing waste by over **60%** compared to systems without forgetting
 
-# MemoryBear Installation Guide
-## 1. Prerequisites
+### Self-Reflection Engine
 
-### 1.1 Environment Requirements
+Scheduled daily reflection process, mimicking human review and retrospection:
 
-* Node.js 20.19+ or 22.12+- Required for running the frontend
+- **Consistency checks**: Detects logical conflicts across related knowledge, flags suspicious records for human review
+- **Value assessment**: Evaluates invocation frequency and association contribution; reinforces high-value knowledge, accelerates decay of low-value knowledge
+- **Association optimization**: Adjusts relationship weights based on recent usage, strengthening high-frequency association paths
 
-* Python 3.12- Backend runtime environment
+### FastAPI Service Layer
 
-* PostgreSQL 13+- Primary relational database
+Unified service architecture exposing two API surfaces:
 
-* Neo4j 4.4+- Graph database (used for storing the knowledge graph)
+| API Type | Path Prefix | Auth | Purpose |
+|----------|-------------|------|---------|
+| Management API | `/api` | JWT | System config, permissions, log queries |
+| Service API | `/v1` | API Key | Knowledge extraction, graph ops, search, forgetting control |
 
-* Redis 6.0+- Cache layer and message queue
+- Average response latency below **50ms**, single instance sustaining **1000 QPS**
+- Auto-generated Swagger documentation
+- Docker-ready, compatible with enterprise microservice ecosystems (CRM, OA, R&D management)
 
-## 2. Getting the Project
+---
 
-### 1. Download Method
+## Architecture
 
-Clone via Git (recommended):
+<img src="https://github.com/user-attachments/assets/650e3d02-a8a1-4550-9fce-dceb38e9542d" alt="MemoryBear System Architecture" width="100%"/>
 
-```plain&#x20;text
+**Celery Three-Queue Async Architecture:**
+
+| Queue | Worker Type | Concurrency | Purpose |
+|-------|-------------|-------------|---------|
+| `memory_tasks` | threads | 100 | Memory read/write (asyncio-friendly) |
+| `document_tasks` | prefork | 4 | Document parsing (CPU-bound) |
+| `periodic_tasks` | prefork | 2 | Scheduled tasks, reflection engine |
+
+---
+
+## Benchmarks
+
+Evaluation metrics include F1 score (F1), BLEU-1 (B1), and LLM-as-a-Judge score (J) — higher values indicate better performance.
+
+MemoryBear consistently outperforms competing systems including Mem0, Zep, and LangMem across all four task categories:
+
+<img width="2256" height="890" alt="Benchmark Results" src="https://github.com/user-attachments/assets/163ea5b5-b51d-4941-9f6c-7ee80977cdbc" />
+
+**Vector version (non-graph)**: Achieves substantially improved retrieval efficiency while maintaining high accuracy. Overall accuracy surpasses the best existing full-text retrieval methods (72.90 ± 0.19%), while maintaining low latency at both p50 and p95 for Search Latency and Total Latency.
+
+<img width="2248" height="498" alt="Vector Version Metrics" src="https://github.com/user-attachments/assets/5e5dae2c-1dde-4f69-88ca-95a9b665b5b2" />
+
+**Graph version**: Integrating the knowledge graph architecture pushes overall accuracy to a new benchmark (**75.00 ± 0.20%**), delivering performance metrics that significantly surpass all other methods.
+
+<img width="2238" height="342" alt="Graph Version Metrics" src="https://github.com/user-attachments/assets/b1eb1c05-da9b-4074-9249-7a9bbb40e9d2" />
+
+---
+
+## Quick Start
+
+### Docker Compose (Recommended)
+
+**Prerequisites**: [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed.
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/SuanmoSuanyangTechnology/MemoryBear.git
+cd MemoryBear/api
+
+# 2. Start base services (PostgreSQL / Neo4j / Redis / Elasticsearch)
+# Pull and start these images via Docker Desktop first (see Installation section 3.2)
+
+# 3. Configure environment variables
+cp env.example .env
+# Edit .env with your database connections and LLM API keys
+
+# 4. Initialize the database
+pip install uv && uv sync
+alembic upgrade head
+
+# 5. Start API + Celery Workers + Beat scheduler
+docker-compose up -d
+
+# 6. Initialize the system and get the admin account
+curl -X POST http://127.0.0.1:8002/api/setup
+```
+
+> **Note**: `docker-compose.yml` includes the API service and Celery Workers only. Base services (PostgreSQL, Neo4j, Redis, Elasticsearch) must be started separately.
+>
+> **Port info**: Docker Compose defaults to port `8002`; manual startup defaults to port `8000`. The installation guide below uses manual startup (`8000`) as the example.
+
+After startup:
+- API docs: http://localhost:8002/docs
+- Frontend: http://localhost:3000 (after starting the web app)
+
+**Default admin credentials:**
+- Account: `admin@example.com`
+- Password: `admin_password`
+
+### Manual Start
+
+> Quick commands below — see [Installation](#installation) for detailed steps.
+
+```bash
+# Backend
+cd api
+pip install uv && uv sync
+alembic upgrade head
+uv run -m app.main
+
+# Frontend (new terminal)
+cd web
+npm install && npm run dev
+```
+
+---
+
+## Installation
+
+### 1. Environment Requirements
+
+| Component | Version | Purpose |
+|-----------|---------|---------|
+| Python | 3.12+ | Backend runtime |
+| Node.js | 20.19+ or 22.12+ | Frontend runtime |
+| PostgreSQL | 13+ | Primary database |
+| Neo4j | 4.4+ | Knowledge graph storage |
+| Redis | 6.0+ | Cache and message queue |
+| Elasticsearch | 8.x | Hybrid search engine |
+
+### 2. Get the Project
+
+```bash
 git clone https://github.com/SuanmoSuanyangTechnology/MemoryBear.git
 ```
 
-### 2. Directory Structure Explanation
+<img src="https://github.com/SuanmoSuanyangTechnology/MemoryBear/releases/download/assets-v1.0/assets__directory-structure.svg" alt="Directory Structure" width="100%"/>
 
-<img width="5238" height="1626" alt="diagram" src="https://github.com/user-attachments/assets/416d6079-3f34-40c3-9bcf-8760d186741a" />
+### 3. Backend API Service
 
+#### 3.1 Install Python Dependencies
 
-## Installation Steps
-
-### 1. Start the Backend API Service
-
-#### 1.1 Install Python Dependencies
-
-```python
-# 0. Install the dependency management tool: uv
+```bash
+# Install uv package manager
 pip install uv
 
-# 1. Switch to the API directory
+# Switch to the API directory
 cd api
 
-# 2. Install dependencies
-uv sync 
-
-# 3. Activate the Virtual Environment (Windows)
-.venv\Scripts\Activate.ps1  # run inside /api directory
-api\.venv\Scripts\activate  # run inside project root directory
-.venv\Scripts\activate.bat  # run inside /api directory
+# Install dependencies
+uv sync
 
+# Activate virtual environment
+# Windows (PowerShell, inside /api)
+.venv\Scripts\Activate.ps1
+# Windows (cmd, inside /api)
+.venv\Scripts\activate.bat
+# macOS / Linux
+source .venv/bin/activate
 ```
 
-#### 1.2 Install Required Base Services (Docker Images)
+#### 3.2 Install Base Services (Docker Images)
 
-Use Docker Desktop to install the necessary service images.
+Download [Docker Desktop](https://www.docker.com/products/docker-desktop/) and pull the required images.
 
-* **Docker Desktop download page:** &#x68;ttps://www.docker.com/products/docker-desktop/
+**PostgreSQL** — search → select → pull
 
-* **PostgreSQL**
+<img width="1280" height="731" alt="PostgreSQL Pull" src="https://github.com/user-attachments/assets/96272efe-50ca-4a32-9686-5f23bc3f6c93" />
 
-  **Pull the Image**
+<img width="1280" height="731" alt="PostgreSQL Container" src="https://github.com/user-attachments/assets/074ea9da-9a3d-401b-b14b-89b81e05487e" />
 
-  search-select-pull
+<img width="1280" height="731" alt="PostgreSQL Running" src="https://github.com/user-attachments/assets/a14744cd-9350-4a2f-87dd-6105b072487d" />
 
-  <img width="1280" height="731" alt="image-9" src="https://github.com/user-attachments/assets/0609eb5f-e259-4f24-8a7b-e354da6bae4d" />
+**Neo4j** — pull the same way. When creating the container, map two required ports and set an initial password:
+- `7474`: Neo4j Browser
+- `7687`: Bolt protocol
 
+<img width="1280" height="731" alt="Neo4j Container" src="https://github.com/user-attachments/assets/881dca96-aec0-4d43-82d0-bb0402eadaf8" />
 
-**Create the Container**
+<img width="1280" height="731" alt="Neo4j Running" src="https://github.com/user-attachments/assets/87423c90-22e8-44a9-a00a-df5d4dce4909" />
 
-<img width="1280" height="731" alt="image-8" src="https://github.com/user-attachments/assets/d57b3206-1df1-42a4-80fd-e71f37201a25" />
+**Redis** — same steps as above.
 
+**Elasticsearch**
 
-**Service Started Successfully**
+Pull the Elasticsearch 8.x image and create a container, mapping ports `9200` (HTTP API) and `9300` (cluster communication). For initial setup, disable security to simplify configuration:
 
-<img width="1280" height="731" alt="image" src="https://github.com/user-attachments/assets/76e04c54-7a36-46ec-a68e-241ad268e427" />
+```bash
+docker run -d --name elasticsearch \
+  -p 9200:9200 -p 9300:9300 \
+  -e "discovery.type=single-node" \
+  -e "xpack.security.enabled=false" \
+  elasticsearch:8.15.0
+```
 
+#### 3.3 Configure Environment Variables
 
-* **Neo4j**
+```bash
+cp env.example .env
+```
 
-**Pull the Image** from Docker Desktop, the same way as with PostgreSQL.
-
-**Create the Neo4j Container** ensure that you map **the two required ports** 7474 - Neo4j Browser, 7687 - Bolt protocol. Additionally, you must set an initial password for the Neo4j database during container creation.
-
-<img width="1280" height="731" alt="image-1" src="https://github.com/user-attachments/assets/6bfb0c27-74e8-45f7-b381-189325d516bd" />
-
-
-**Service Started Successfully**
-
-<img width="1280" height="731" alt="image-2" src="https://github.com/user-attachments/assets/0d28b4fa-e8ed-4c05-8983-7a47f0a892d1" />
-
-
-* **Redis**
-
-The same as above
-
-#### 1.3 Configure environment variables
-
-Copy env.example as.env and fill in the configuration
+Fill in the core configuration in `.env`:
 
 ```bash
 # Neo4j Graph Database
 NEO4J_URI=bolt://localhost:7687
 NEO4J_USERNAME=neo4j
 NEO4J_PASSWORD=your-password
-#  Neo4j Browser Access URL (optional documentation)
 
 # PostgreSQL Database
 DB_HOST=127.0.0.1
@@ -216,131 +309,165 @@ DB_USER=postgres
 DB_PASSWORD=your-password
 DB_NAME=redbear-mem
 
-# Database Migration Configuration
-# Set to true to automatically upgrade database schema on startup
-DB_AUTO_UPGRADE=true  # For the first startup, keep this as true to create the schema in an empty database.
+# Set to true on first startup to auto-migrate the database
+DB_AUTO_UPGRADE=true
 
 # Redis
 REDIS_HOST=127.0.0.1
 REDIS_PORT=6379
-REDIS_DB=1 
+REDIS_DB=1
 
-# Celery (Using Redis as broker)
-BROKER_URL=redis://127.0.0.1:6379/0
-RESULT_BACKEND=redis://127.0.0.1:6379/0
+# Celery
+REDIS_DB_CELERY_BROKER=1
+REDIS_DB_CELERY_BACKEND=2
 
-# JWT Secret Key (Formation method: openssl rand -hex 32)
+# Elasticsearch
+ELASTICSEARCH_HOST=127.0.0.1
+ELASTICSEARCH_PORT=9200
+
+# JWT Secret Key (generate with: openssl rand -hex 32)
 SECRET_KEY=your-secret-key-here
 ```
 
-#### 1.4 Initialize the PostgreSQL Database
+#### 3.4 Initialize the PostgreSQL Database
 
-MemoryBear uses Alembic migration files included in the project to create the required table structures in a newly created, empty PostgreSQL database.
+Verify the database connection in `alembic.ini`:
 
-**(1) Configure the Database Connection**
-
-Ensure that the sqlalchemy.url value in the project's alembic.ini file points to your empty PostgreSQL database. Example format:
-
-```bash
+```ini
 sqlalchemy.url = postgresql://<username>:<password>@<host>:<port>/<database_name>
 ```
 
-Also verify that target_metadata in migrations/env.py is correctly linked to the ORM model's metadata object.
+Apply all migrations to create the full schema:
 
-**(2) Apply the Migration Files**
-
-Run the following command inside the API directory. Alembic will automatically detect the empty database and apply all outstanding migrations to create the full schema:
 ```bash
 alembic upgrade head
 ```
 
-<img width="1076" height="341" alt="image-3" src="https://github.com/user-attachments/assets/9edda79d-4637-46e3-bee3-2eec39975d59" />
+<img width="1076" height="341" alt="Alembic Migration" src="https://github.com/user-attachments/assets/6970a8e6-712b-4f49-937a-f5870a2d1a2a" />
 
+<img width="1280" height="680" alt="Database Tables" src="https://github.com/user-attachments/assets/8bbec421-de0c-472b-a7ce-8b89cc1e2efd" />
 
-Use Navicat to inspect the database tables created by the Alembic migration process.
+#### 3.5 Start the API Service
 
-<img width="1280" height="680" alt="image-4" src="https://github.com/user-attachments/assets/aa5c1d98-bdc3-4d25-acb2-5c8cf6ecd3f5" />
-
-
-#### Start the API Service
-
-```python
+```bash
 uv run -m app.main
 ```
 
-Access the API documentation at http://localhost:8000/docs
+Access API documentation at http://localhost:8000/docs
 
-<img width="1280" height="675" alt="image-5" src="https://github.com/user-attachments/assets/68fa62b4-2c4f-4cf0-896c-41d59aa7d712" />
+<img width="1280" height="675" alt="API Docs" src="https://github.com/user-attachments/assets/6d1c71b7-9ee8-4f80-9bed-19c410d6e85f" />
 
+#### 3.6 Start Celery Workers (Optional, for async tasks)
 
-### 2. Start the Frontend Web Application
+```bash
+# Memory worker (thread pool, asyncio-friendly, high concurrency)
+celery -A app.celery_worker.celery_app worker --loglevel=info --pool=threads --concurrency=100 --queues=memory_tasks
 
-#### 2.1 Install Dependencies
+# Document worker (prefork, CPU-bound parsing)
+celery -A app.celery_worker.celery_app worker --loglevel=info --pool=prefork --concurrency=4 --queues=document_tasks
 
-```python
-# Switch to the web directory
+# Periodic worker (reflection engine, scheduled tasks)
+celery -A app.celery_worker.celery_app worker --loglevel=info --pool=prefork --concurrency=2 --queues=periodic_tasks
+
+# Beat scheduler
+celery -A app.celery_worker.celery_app beat --loglevel=info
+```
+
+### 4. Frontend Web Application
+
+#### 4.1 Install Dependencies
+
+```bash
 cd web
-
-# Install dependencies
 npm install
 ```
 
-#### 2.2 Update the API Proxy Configuration
+#### 4.2 Update API Proxy Configuration
 
-Edit web/vite.config.ts and update the proxy target to point to your backend API service:
+Edit `web/vite.config.ts`:
 
-```python
+```typescript
 proxy: {
   '/api': {
-    target: 'http://127.0.0.1:8000',  // Change to the backend address, windows users 127.0.0.1  macOS users 0.0.0.0
+    target: 'http://127.0.0.1:8000',  // Windows: 127.0.0.1 | macOS: 0.0.0.0
     changeOrigin: true,
   },
 }
-
 ```
 
-#### 2.3 Start the Frontend Service
+#### 4.3 Start the Frontend Service
 
-```python
-# Start the web service
+```bash
 npm run dev
-
 ```
 
-After the service starts, the console will output the URL for accessing the frontend interface.
+<img width="935" height="311" alt="Frontend Start" src="https://github.com/user-attachments/assets/8b08fc46-01d0-458b-ab4d-f5ac04bc2510" />
 
-<img width="935" height="311" alt="image-6" src="https://github.com/user-attachments/assets/cba1074a-440c-4866-8a94-7b6d1c911a93" />
+<img width="1280" height="652" alt="Frontend UI" src="https://github.com/user-attachments/assets/542dbee3-8cd4-4b16-a8e5-36f8d6153820" />
 
+### 5. Initialize the System
 
-<img width="1280" height="652" alt="image-7" src="https://github.com/user-attachments/assets/a719dc0a-cbdd-4ba1-9b21-123d5eac32eb" />
+```bash
+# Initialize the database and obtain the super admin account
+curl -X POST http://127.0.0.1:8000/api/setup
+```
 
+**Super admin credentials:**
+- Account: `admin@example.com`
+- Password: `admin_password`
 
-## 4. User Guide
+### 6. Full Startup Checklist
 
-step1: Retrieve the Project.
+```
+Step 1  Clone the repository
+Step 2  Start base services (PostgreSQL / Neo4j / Redis / Elasticsearch)
+Step 3  Configure .env environment variables
+Step 4  Run alembic upgrade head to initialize the database
+Step 5  uv run -m app.main to start the backend API
+Step 6  npm run dev to start the frontend
+Step 7  curl -X POST http://127.0.0.1:8000/api/setup to initialize the system
+Step 8  Log in to the frontend with the admin account
+```
 
-step2: Start the Backend API Service.
+---
 
-step3: Start the Frontend Web Application.
+## Tech Stack
 
-step4: Enter curl.exe -X POST http://127.0.0.1:8000/api/setup in the terminal to access the interface, initialize the database, and obtain the super administrator account.
+| Layer | Technology |
+|-------|------------|
+| Backend Framework | FastAPI + Uvicorn |
+| Async Tasks | Celery (3 queues: memory / document / periodic) |
+| Primary Database | PostgreSQL 13+ |
+| Graph Database | Neo4j 4.4+ |
+| Search Engine | Elasticsearch 8.x (keyword + semantic vector hybrid) |
+| Cache / Queue | Redis 6.0+ |
+| ORM | SQLAlchemy 2.0 + Alembic |
+| LLM Integration | LangChain / OpenAI / DashScope / AWS Bedrock |
+| MCP Integration | fastmcp + langchain-mcp-adapters |
+| Frontend Framework | React 18 + TypeScript + Vite |
+| UI Components | Ant Design 5.x |
+| Graph Visualization | AntV X6 + ECharts + D3.js |
+| Package Manager | uv (backend) / npm (frontend) |
 
-step5: Super Administrator Credentials
-Account: admin@example.com
-Password: admin_password
-
-step6: Log In to the Frontend Interface.
+---
 
 ## License
-This project is licensed under the Apache License 2.0. For details, see the LICENSE file.
+
+This project is licensed under the [Apache License 2.0](LICENSE).
+
+---
 
 ## Community & Support
 
-Join our community to ask questions, share your work, and connect with fellow developers.
+- **Bug Reports & Feature Requests**: [GitHub Issues](https://github.com/SuanmoSuanyangTechnology/MemoryBear/issues)
+- **Contribute**: Please read our [Contributing Guide](CONTRIBUTING.md). Submit [Pull Requests](https://github.com/SuanmoSuanyangTechnology/MemoryBear/pulls) on a feature branch following Conventional Commits format
+- **Discussions**: [GitHub Discussions](https://github.com/SuanmoSuanyangTechnology/MemoryBear/discussions)
+- **WeChat Community**: Scan the QR code below to join our WeChat group
 
-- **GitHub Issues**: Report bugs, request features, or track known issues via [GitHub Issues](https://github.com/SuanmoSuanyangTechnology/MemoryBear/issues).
-- **GitHub Pull Requests**: Contribute code improvements or fixes through [Pull Requests](https://github.com/SuanmoSuanyangTechnology/MemoryBear/pulls).
-- **GitHub Discussions**: Ask questions, share ideas, and engage with the community in [GitHub Discussions](https://github.com/SuanmoSuanyangTechnology/MemoryBear/discussions).
-- **WeChat**: Scan the QR code below to join our WeChat community group.
-- ![wecom-temp-114020-47fe87a75da439f09f5dc93a01593046](https://github.com/user-attachments/assets/8c81885c-4134-40d5-96e2-7f78cc082dc6)
-- **Contact**: If you are interested in contributing or collaborating, feel free to reach out at tianyou_hubm@redbearai.com
+![WeChat QR](https://github.com/user-attachments/assets/8c81885c-4134-40d5-96e2-7f78cc082dc6)
+
+- **Star History**:
+
+[![Star History Chart](https://api.star-history.com/svg?repos=SuanmoSuanyangTechnology/MemoryBear&type=Date)](https://star-history.com/#SuanmoSuanyangTechnology/MemoryBear&Date)
+
+- **Contact**: tianyou_hubm@redbearai.com

README_CN.md

@@ -1,188 +1,311 @@
-<img width="2346" height="1310" alt="image" src="https://github.com/user-attachments/assets/bc73a64d-cd1e-4d22-be3e-04ce40423a20" />
+<img width="2346" height="1310" alt="MemoryBear Hero Banner" src="https://github.com/user-attachments/assets/77f3e31a-3a20-4f17-8d2d-d88d85acf19e" />
 
-# MemoryBear 让AI拥有如同人类一样的记忆
+<div align="center">
+
+# MemoryBear — 让 AI 拥有如同人类一样的记忆
+
+**新一代 AI 记忆管理系统 · 感知 · 提炼 · 关联 · 遗忘**
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-3.12+-green?logo=python&logoColor=white)](https://www.python.org/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-teal?logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com/)
+[![Neo4j](https://img.shields.io/badge/Neo4j-4.4+-blue?logo=neo4j&logoColor=white)](https://neo4j.com/)
+[![Gitee Sync](https://img.shields.io/github/actions/workflow/status/SuanmoSuanyangTechnology/MemoryBear/sync-to-gitee.yml?label=Gitee%20Sync&logo=gitee&logoColor=white)](https://github.com/SuanmoSuanyangTechnology/MemoryBear/actions/workflows/sync-to-gitee.yml)
 
 中文 | [English](./README.md)
 
-### [安装教程](#memorybear安装教程)
-### 论文：<a href="https://memorybear.ai/pdf/memoryBear" target="_blank" rel="noopener noreferrer">《Memory Bear AI: 从记忆到认知的突破》</a>
+[快速开始](#快速开始) · [安装教程](#安装教程) · [核心特性](#核心特性) · [架构总览](#架构总览) · [实验室指标](#实验室指标) · [论文](#论文)
+
+</div>
+
+---
+
 ## 项目简介
-MemoryBear是红熊AI自主研发的新一代AI记忆系统，其核心突破在于跳出传统知识“静态存储”的局限，以生物大脑认知机制为原型，构建了具备“感知-提炼-关联-遗忘”全生命周期的智能知识处理体系。该系统致力于让机器摆脱“信息堆砌”的困境，实现对知识的深度理解与自主进化，成为人类认知协作的核心伙伴。
 
-## MemoryBear是从解决这些问题来的
-### 一、单模型知识遗忘的核心原因</br>
-上下文窗口限制：主流大模型上下文窗口通常为 8k-32k tokens，长对话中早期信息会被 “挤出”，导致后续回复脱离历史语境：如用户第 1 轮说 “我对海鲜过敏”，第 5 轮问 “推荐今晚的菜品” 时模型可能遗忘过敏信息。</br>
-静态知识库与动态数据割裂：大模型训练时的静态知识库如截止 2023 年数据，无法实时吸收用户对话中的个性化信息如用户偏好、历史订单，需依赖外部记忆模块补充。</br>
-模型注意力机制缺陷：Transformer 的自注意力对长距离依赖的捕捉能力随序列长度下降，出现 “近因效应”更关注最新输入，忽略早期关键信息。</br>
+MemoryBear 是红熊 AI 自主研发的新一代 AI 记忆系统，核心突破在于跳出传统知识"静态存储"的局限，以生物大脑认知机制为原型，构建了具备**感知 → 提炼 → 关联 → 遗忘**全生命周期的智能知识处理体系。
 
-### 二、多 Agent 协作的记忆断层问题</br>
-Agent 数据孤岛：不同 Agent如咨询 Agent、售后 Agent、推荐 Agent各自维护独立记忆，未建立跨模块的共享机制，导致用户重复提供信息如用户向咨询 Agent 说明地址后，售后 Agent 仍需再次询问。</br>
-对话状态不一致：多轮交互中 Agent 切换时，对话状态如用户当前意图、历史问题标签传递不完整，引发服务断层如用户从 “产品咨询” 转 “投诉” 时，新 Agent 未继承前期投诉细节。</br>
-决策冲突：不同 Agent 基于局部记忆做出的响应可能矛盾如推荐 Agent 推荐用户过敏的产品，因未获取健康禁忌的历史记录。</br>
+与传统记忆管理工具将知识视为"待检索的静态数据"不同，MemoryBear 通过复刻大脑海马体的记忆编码、新皮层的知识固化及突触修剪的遗忘机制，让知识具备动态演化的"生命特征"，将 AI 与用户的交互关系从**被动查询**升级为**主动辅助认知**。
 
-### 三、模型推理过程中的 “语义歧义” 引发理解偏差</br>
-用户对话中的个性化信息如行业术语、口语化表达、上下文指代未被准确编码，导致模型对记忆内容的语义解析失真，比如对用户历史对话中的模糊表述如 “上次说的那个方案”无法准确定位具体内容。</br>
-多语言、方言场景中，跨语种记忆关联失效如用户混用中英描述需求时，模型无法整合多语言信息。</br>
-典型案例：用户说之前客服说可以‘加急处理’现在进度如何？模型因未记录 “加急” 对应的具体服务等级，回复笼统模糊。</br>
+## 论文
 
-## MemoryBear核心定位
-与传统记忆管理工具将知识视为“待检索的静态数据”不同，MemoryBear以“模拟人类大脑知识处理逻辑”为核心目标，构建了从知识摄入到智能输出的闭环体系。系统通过复刻大脑海马体的记忆编码、新皮层的知识固化及突触修剪的遗忘机制，让知识具备动态演化的“生命特征”，彻底重构了知识与使用者之间的交互关系——从“被动查询”升级为“主动辅助记忆认知”
+| 论文 | 描述 |
+|------|------|
+| 📄 [Memory Bear AI: A Breakthrough from Memory to Cognition](https://memorybear.ai/pdf/memoryBear) | MemoryBear 核心技术报告 |
+| 📄 [Memory Bear AI Memory Science Engine for Multimodal Affective Intelligence](https://arxiv.org/abs/2603.22306) | 多模态情感智能记忆科学引擎技术报告 |
+| 📄 [A-MBER: Affective Memory Benchmark for Emotion Recognition](https://arxiv.org/abs/2604.07017) | 情感记忆基准测试集 |
 
-## MemoryBear核心哲学
-MemoryBear的设计哲学源于对人类认知本质的深刻洞察：知识的价值不在于存量积累，而在于动态流转中的价值升华。传统系统中，知识一旦存储便陷入“静止状态”，难以形成跨领域关联，更无法主动适配使用者的认知需求；而MemoryBear坚信，只有让知识经历“原始信息提炼为结构化规则、孤立规则关联为知识网络、冗余信息智能遗忘”的完整过程，才能实现从“信息记忆”到“认知理解”的跨越，最终涌现出真正的智能。
+## 为什么需要 MemoryBear
 
-## MemoryBear核心特性
-MemoryBear作为模仿生物大脑认知过程的智能记忆管理系统，其核心特性围绕“记忆知识全生命周期管理”与“智能认知进化”两大维度构建，覆盖记忆从摄入提炼到存储检索、动态优化的完整链路，同时通过标准化服务架构实现高效集成与调用。
+### 单模型的知识遗忘
 
-### 一、记忆萃取引擎：多维度结构化提炼，夯实认知基础</br>
-记忆萃取是MemoryBear实现“认知化管理”的起点，区别于传统数据提取的“机械转换”，其核心优势在于对非结构化信息的“语义级解析”与“多格式标准化输出”，精准适配后续图谱构建与智能检索需求。具体能力包括：</br>
-多类型信息精准解析：可自动识别并提取文本中的陈述句核心信息，剥离冗余修饰成分，保留“主体-行为-对象”核心逻辑；同时精准抽取三元组数据（如“MemoryBear-核心功能-知识萃取”），为图谱存储提供基础数据单元，保障知识关联的准确性。</br>
-时序信息锚定：针对含有时效性的知识（如事件记录、政策文件、实验数据），自动提取并标记时间戳信息，支持“时间维度”的知识追溯与关联，解决传统知识管理中“时序混乱”导致的认知偏差问题。</br>
-智能剪枝生成：基于上下文语义理解，生成“关键信息全覆盖+逻辑连贯性强”的摘要内容，支持自定义摘要长度（50-500字）与侧重点（如技术型、业务型），适配不同场景的知识快速获取需求。例如对10页技术文档处理时，可在3秒内生成含核心参数、实现逻辑与应用场景的精简摘要。</br>
+- **上下文窗口限制**：主流大模型上下文窗口通常为 8k–32k tokens，长对话中早期信息会被"挤出"，导致后续回复脱离历史语境
+- **静态知识库割裂**：训练数据是静态快照，无法实时吸收用户对话中的个性化信息（偏好、历史记录等）
+- **注意力近因效应**：Transformer 自注意力对长距离依赖的捕捉能力随序列长度下降，过度关注最新输入而忽略早期关键信息
 
-### 二、图谱存储：对接Neo4j，构建可视化知识网络</br>
-存储层采用“图数据库优先”的架构设计，通过对接业界成熟的Neo4j图数据库，实现知识实体与关系的高效管理，突破传统关系型数据库“关联弱、查询繁”的局限，契合生物大脑“神经元关联”的认知模式。</br>
-该特性核心价值体现在：一是支持海量实体与多元关系的灵活存储，可管理百万级知识实体及千万级关联关系，涵盖“上下位、因果、时序、逻辑”等12种核心关系类型，适配多领域知识场景；二是与知识萃取模块深度联动，萃取的三元组数据可直接同步至Neo4j，自动构建初始知识图谱，无需人工二次映射；三是支持图谱可视化交互，用户可直观查看实体关联路径，手动调整关系权重，实现“机器构建+人工优化”的协同管理。</br>
+### 多 Agent 协作的记忆断层
 
-### 三、混合搜索：关键词+语义向量，兼顾精准与智能</br>
-为解决传统搜索“要么精准但僵化，要么模糊但失准”的痛点，MemoryBear采用“关键词检索+语义向量检索”的混合搜索架构，实现“精准匹配”与“意图理解”的双重目标。</br>
-其中，关键词检索基于Lucene引擎优化，针对知识中的核心实体、关键参数等结构化信息实现毫秒级精准定位，保障“明确需求”下的高效检索；语义向量检索则通过BERT模型对查询语句进行语义编码，将其转化为高维向量后与知识库中的向量数据比对，可识别同义词、近义词及隐含意图，例如用户查询“如何优化记忆衰减效率”时，系统可关联到“遗忘机制参数调整”“记忆强度评估方法”等相关知识。两种检索方式智能融合：先通过语义检索扩大候选范围，再通过关键词检索精准筛选，使检索准确率提升至92%，较单一检索方式平均提升35%。</br>
+- **数据孤岛**：不同 Agent（咨询、售后、推荐）各自维护独立记忆，用户需重复提供相同信息
+- **对话状态不一致**：Agent 切换时，用户意图、历史问题标签传递不完整，引发服务断层
+- **决策冲突**：基于局部记忆的 Agent 可能给出矛盾响应（如推荐用户过敏的产品）
 
-### 四、记忆遗忘引擎：基于强度与时效的动态衰减，模拟生物记忆特性</br>
-遗忘是MemoryBear区别于传统静态知识管理工具的核心特性之一，其灵感源于生物大脑“突触修剪”机制，通过“记忆强度+时效”双维度模型实现知识的逐步衰减，避免冗余知识占用资源，保障核心知识的“认知优先级”。</br>
-具体实现逻辑为：系统为每条知识分配“初始记忆强度”（由萃取质量、人工标注重要性决定），并结合“调用频率、关联活跃度”实时更新强度值；同时设定“时效衰减周期”，根据知识类型（如核心规则、临时数据）差异化配置衰减速率。当知识强度低于阈值且超过设定时效后，将进入“休眠-衰减-清除”三阶段流程：休眠阶段保留数据但降低检索优先级，衰减阶段逐步压缩存储体积，清除阶段则彻底删除并备份至冷存储。该机制使系统冗余知识占比控制在8%以内，较传统无遗忘机制系统降低60%以上。</br>
+### 语义歧义导致的理解偏差
 
-### 五、自我反思引擎：定期回顾优化，实现记忆自主进化</br>
-自我反思机制是MemoryBear实现“智能升级”的关键，通过定期对已有记忆进行回顾、校验与优化，模拟人类“复盘总结”的认知行为，持续提升知识体系的准确性与有效性。</br>
-系统默认每日凌晨触发自动反思流程，核心动作包括：一是“一致性校验”，对比关联知识间的逻辑冲突（如同一实体的矛盾属性），标记可疑知识并推送人工审核；二是“价值评估”，统计知识的调用频次、关联贡献度，将高价值知识强化记忆强度，低价值知识加速衰减；三是“关联优化”，基于近期检索与使用行为，调整知识间的关联权重，强化高频关联路径。此外，支持人工触发专项反思（如新增核心知识后），并提供反思报告可视化展示优化结果，实现“自主进化+人工监督”的双重保障。</br>
+- 行业术语、口语化表达、上下文指代未被准确编码，导致模型对记忆内容的语义解析失真
+- 多语言混用场景中，跨语种记忆关联失效
 
-### 六、FastAPI服务：标准化API输出，实现高效集成与管理</br>
-为保障系统与外部业务场景的高效对接，MemoryBear采用FastAPI构建统一服务架构，实现管理端与服务端API的集中暴露，具备“高性能、易集成、强规范”的核心优势。服务端API涵盖知识萃取、图谱操作、搜索查询、遗忘控制等全功能模块，支持JSON/XML多格式数据交互，响应延迟平均低于50ms，单实例可支撑1000QPS并发请求；管理端API则提供系统配置、权限管理、日志查询等运维功能，支持通过API实现批量知识导入导出、反思周期调整等操作。同时，系统自动生成Swagger API文档，包含接口参数说明、请求示例与返回格式定义，开发者可快速完成集成调试。该架构已适配企业级微服务体系，支持Docker容器化部署，可灵活对接CRM、OA、研发管理等各类业务系统。</br>
+<img width="2294" height="1154" alt="Why MemoryBear" src="https://github.com/user-attachments/assets/62453bc9-8422-4480-9645-e2abb57f0204" />
 
-## MemoryBear架构总览
-<img width="2294" height="1154" alt="image" src="https://github.com/user-attachments/assets/3afd3b49-20ea-4847-b9ed-38b646a4ad89" />
-</br>
-- 记忆萃取引擎（Extraction Engine）：预处理、去重、结构化提取</br>
-- 记忆遗忘引擎（Forgetting Engine）：记忆强度模型与衰减策略</br>
-- 记忆自我反思引擎（Reflection Engine）：评价与重写记忆</br>
-- 检索服务：关键词、语义与混合检索</br>
-- Agent 与 MCP：提供多工具协作的智能体能力</br>
+---
+
+## 核心特性
+
+<img width="2294" height="1154" alt="MemoryBear Core Features" src="https://github.com/user-attachments/assets/e90153d3-378f-47e8-a367-622121621566" />
+
+### 记忆萃取引擎
+
+从非结构化对话和文档中进行**语义级解析**，精准提取：
+
+- **陈述句核心信息**：剥离冗余修饰，保留"主体-行为-对象"核心逻辑
+- **三元组数据**：自动抽取实体关系（如 `MemoryBear → 核心功能 → 知识萃取`），为图谱存储提供基础数据单元
+- **时序信息锚定**：自动提取并标记时间戳，支持时间维度的知识追溯
+- **智能摘要生成**：支持自定义摘要长度（50–500 字）与侧重点，10 页技术文档 3 秒内生成精简摘要
+
+### 图谱存储（Neo4j）
+
+采用**图数据库优先**架构，对接 Neo4j，突破传统关系型数据库"关联弱、查询繁"的局限：
+
+- 支持百万级知识实体及千万级关联关系
+- 涵盖上下位、因果、时序、逻辑等 12 种核心关系类型
+- 萃取的三元组直接同步至 Neo4j，自动构建初始知识图谱
+- 支持图谱可视化交互，实现"机器构建 + 人工优化"协同管理
+
+### 混合搜索
+
+**关键词检索 + 语义向量检索**双引擎融合：
+
+- 关键词检索基于 Elasticsearch，毫秒级精准定位结构化信息
+- 语义向量检索通过 BERT 模型编码，识别同义词、近义词及隐含意图
+- 先语义扩大候选范围，再关键词精准筛选，检索准确率达 **92%**，较单一方式提升 **35%**
+
+### 记忆遗忘引擎
+
+灵感源于生物大脑**突触修剪**机制，通过"记忆强度 + 时效"双维度模型实现知识动态衰减：
+
+- 每条知识分配初始记忆强度，结合调用频率和关联活跃度实时更新
+- 知识强度低于阈值后进入**休眠 → 衰减 → 清除**三阶段流程
+- 系统冗余知识占比控制在 **8%** 以内，较无遗忘机制系统降低 **60%** 以上
+
+### 自我反思引擎
+
+每日定时触发自动反思流程，模拟人类"复盘总结"认知行为：
+
+- **一致性校验**：检测关联知识间的逻辑冲突，标记可疑知识推送人工审核
+- **价值评估**：统计调用频次和关联贡献度，高价值知识强化，低价值知识加速衰减
+- **关联优化**：基于近期检索行为调整知识间关联权重，强化高频关联路径
+
+### FastAPI 服务层
+
+统一服务架构，暴露两套 API：
+
+| API 类型 | 路径前缀 | 认证方式 | 用途 |
+|----------|----------|----------|------|
+| 管理端 API | `/api` | JWT | 系统配置、权限管理、日志查询 |
+| 服务端 API | `/v1` | API Key | 知识萃取、图谱操作、搜索查询、遗忘控制 |
+
+- 平均响应延迟低于 **50ms**，单实例支撑 **1000 QPS** 并发
+- 自动生成 Swagger 文档，支持 Docker 容器化部署
+- 兼容企业级微服务体系，可对接 CRM、OA、研发管理等业务系统
+
+---
+
+## 架构总览
+
+<img src="https://github.com/user-attachments/assets/bc356ed3-9159-41c5-bd73-125a67e06ced" alt="MemoryBear System Architecture" width="100%"/>
+
+**Celery 三队列异步架构：**
+
+| 队列 | Worker 类型 | 并发 | 用途 |
+|------|-------------|------|------|
+| `memory_tasks` | threads | 100 | 记忆读写（asyncio 友好） |
+| `document_tasks` | prefork | 4 | 文档解析（CPU 密集） |
+| `periodic_tasks` | prefork | 2 | 定时任务、反思引擎 |
+
+---
 
 ## 实验室指标
-我们采用不同问题的数据集中，通过具备记忆功能的系统，进行性能对比。评估指标包括F1分数（F1）、BLEU-1（B1）以及LLM-as-a-Judge分数（J），数值越高表示表现越好，性能更高。
-MemoryBear 在 “单跳场景” 的精准度、结果匹配度与任务特异性表现上，均处于领先，“多跳”更强的信息连贯性与推理准确性，“开放泛化”对多样，无边界信息的处理质量与泛化能力更优，“时序”对时效性信息的匹配与处理表现更出色，四大任务的核心指标中，均优于 行业内的其他海外竞争对手Mem O、Zep、Lang Mem 等现有方法，整体性能更突出。
-<img width="2256" height="890" alt="image" src="https://github.com/user-attachments/assets/5ff86c1f-53ac-4816-976d-95b48a4a10c0" />
-Memory Bear 基于向量的知识记忆非图谱版本，成功在保持高准确性的同时，极大地优化了检索效率。该方法在总体准确性上的表现已明显高于现有最高全文检索方法（72.90 ± 0.19%）。更重要的是，它在关键的延迟指标（包括 Search Latency 和 Total Latency 的 p50/p95）上也保持了较低水平，充分体现出 “性能更优且延迟更高效” 的特点，解决了全文检索方法的高准确性伴随的高延迟瓶颈。
-<img width="2248" height="498" alt="image" src="https://github.com/user-attachments/assets/2759ea19-0b71-4082-8366-e8023e3b28fe" />
-Memory Bear 通过集成知识图谱架构，在需要复杂推理和关系感知的任务上进一步释放了潜力。虽然图谱的遍历和推理可能会引入轻微的检索开销，但该版本通过优化图检索策略和决策流，成功将延迟控制在高效范围。更关键的是，基于图谱的 Memory Bear 将总体准确性推至新的高度（75.00 ± 0.20%），在保持准确性的同时，整体指标显著优于其他所有方法，证明了“结构化记忆带来的性能决定性优势”。
-<img width="2238" height="342" alt="image" src="https://github.com/user-attachments/assets/c928e094-45a2-414b-831a-6990b711ed07" />
 
-# MemoryBear安装教程
-## 一、前期准备
+评估指标包括 F1 分数（F1）、BLEU-1（B1）以及 LLM-as-a-Judge 分数（J），数值越高表示性能越好。
 
-### 1.环境要求
+MemoryBear 在四大任务类型的核心指标中，均优于行业内竞争对手 Mem0、Zep、LangMem 等现有方法：
 
-* Node.js 20.19+ 或 22.12+  前端运行环境
+<img width="2256" height="890" alt="Benchmark Results" src="https://github.com/user-attachments/assets/163ea5b5-b51d-4941-9f6c-7ee80977cdbc" />
 
-* Python 3.12  后端运行环境
+**向量版本（非图谱）**：在保持高准确性的同时极大优化了检索效率，总体准确性明显高于现有最高全文检索方法（72.90 ± 0.19%），且在 Search Latency 和 Total Latency 的 p50/p95 上保持较低水平。
 
-* PostgreSQL 13+ 主数据库
+<img width="2248" height="498" alt="Vector Version Metrics" src="https://github.com/user-attachments/assets/5e5dae2c-1dde-4f69-88ca-95a9b665b5b2" />
 
-* Neo4j 4.4+ 图数据库（存储知识图谱）
+**图谱版本**：通过集成知识图谱架构，将总体准确性推至新高度（**75.00 ± 0.20%**），在保持准确性的同时整体指标显著优于所有其他方法。
 
-* Redis 6.0+ 缓存和消息队列
+<img width="2238" height="342" alt="Graph Version Metrics" src="https://github.com/user-attachments/assets/b1eb1c05-da9b-4074-9249-7a9bbb40e9d2" />
 
-## 二、项目获取
+---
 
-### 1.获取方式
+## 快速开始
 
-Git克隆（推荐）：
+### Docker Compose 一键启动（推荐）
 
-```plain&#x20;text
+**前提条件**：已安装 [Docker Desktop](https://www.docker.com/products/docker-desktop/)。
+
+```bash
+# 1. 克隆项目
+git clone https://github.com/SuanmoSuanyangTechnology/MemoryBear.git
+cd MemoryBear/api
+
+# 2. 启动基础服务（PostgreSQL / Neo4j / Redis / Elasticsearch）
+# 请先通过 Docker Desktop 拉取并启动以下镜像（详见安装教程 3.2 节）
+
+# 3. 配置环境变量
+cp env.example .env
+# 编辑 .env，填写数据库连接信息和 LLM API Key
+
+# 4. 初始化数据库
+pip install uv && uv sync
+alembic upgrade head
+
+# 5. 启动 API + Celery Workers + Beat 调度器
+docker-compose up -d
+
+# 6. 初始化系统，获取超级管理员账号
+curl -X POST http://127.0.0.1:8002/api/setup
+```
+
+> **注意**：`docker-compose.yml` 包含 API 服务和 Celery Workers，基础服务（PostgreSQL、Neo4j、Redis、Elasticsearch）需要单独启动。
+>
+> **端口说明**：Docker Compose 部署默认端口为 `8002`，手动启动默认端口为 `8000`。下文安装教程以手动启动（`8000`）为例。
+
+服务启动后访问：
+- API 文档：http://localhost:8002/docs
+- 管理后台：http://localhost:3000（启动前端后）
+
+**默认管理员账号：**
+- 账号：`admin@example.com`
+- 密码：`admin_password`
+
+### 手动启动
+
+> 以下为精简命令，详细步骤请参考 [安装教程](#安装教程)。
+
+```bash
+# 后端
+cd api
+pip install uv && uv sync
+alembic upgrade head
+uv run -m app.main
+
+# 前端（新终端）
+cd web
+npm install && npm run dev
+```
+
+---
+
+## 安装教程
+
+### 一、环境要求
+
+| 组件 | 版本要求 | 用途 |
+|------|----------|------|
+| Python | 3.12+ | 后端运行环境 |
+| Node.js | 20.19+ 或 22.12+ | 前端运行环境 |
+| PostgreSQL | 13+ | 主数据库 |
+| Neo4j | 4.4+ | 知识图谱存储 |
+| Redis | 6.0+ | 缓存与消息队列 |
+| Elasticsearch | 8.x | 混合搜索引擎 |
+
+### 二、项目获取
+
+```bash
 git clone https://github.com/SuanmoSuanyangTechnology/MemoryBear.git
 ```
 
-### 2.目录说明
+<img src="https://github.com/SuanmoSuanyangTechnology/MemoryBear/releases/download/assets-v1.0/assets__directory-structure.svg" alt="Directory Structure" width="100%"/>
 
-<img width="5238" height="1626" alt="diagram" src="https://github.com/user-attachments/assets/416d6079-3f34-40c3-9bcf-8760d186741a" />
+### 三、后端 API 服务启动
 
-
-## 三、安装步骤
-
-### 1.后端API服务启动
-
-#### 1.1 安装python依赖
-
-```python
-# 0.安装依赖管理工具uv
-pip install uv
-
-# 1.终端切换API目录
-cd api
-
-# 2.安装依赖
-uv sync 
-
-# 3.激活虚拟环境 (Windows)
-.venv\Scripts\Activate.ps1  （powershell，在api目录下）
-api\.venv\Scripts\activate （powershell，在根目录下）
-.venv\Scripts\activate.bat （cmd，在api目录下）
-
-```
-
-#### 1.2 安装必备基础服务（docker镜像）
-
-使用docker desktop安装所需的docker镜像
-
-* **docker desktop安装地址：**&#x68;ttps://www.docker.com/products/docker-desktop/
-
-* **PostgreSQL**
-
-  **拉取镜像**
-
-  search——select——pull
-
-  <img width="1280" height="731" alt="image-9" src="https://github.com/user-attachments/assets/0609eb5f-e259-4f24-8a7b-e354da6bae4d" />
-
-
-**创建容器**
-
-<img width="1280" height="731" alt="image-8" src="https://github.com/user-attachments/assets/d57b3206-1df1-42a4-80fd-e71f37201a25" />
-
-
-**服务启动成功**
-
-<img width="1280" height="731" alt="image" src="https://github.com/user-attachments/assets/76e04c54-7a36-46ec-a68e-241ad268e427" />
-
-
-* **Neo4j**
-
-**拉取镜像**，与PostgreSQL一样从docker desktop中拉取镜像
-
-**创建容器**，Neo4j 默认需要映射**2 个关键端口**（7474 对应 Browser，7687 对应 Bolt 协议），同时需设置初始密码
-
-<img width="1280" height="731" alt="image-1" src="https://github.com/user-attachments/assets/6bfb0c27-74e8-45f7-b381-189325d516bd" />
-
-
-**服务成功启动**
-
-<img width="1280" height="731" alt="image-2" src="https://github.com/user-attachments/assets/0d28b4fa-e8ed-4c05-8983-7a47f0a892d1" />
-
-
-* **Redis**
-
-同上
-
-#### 1.3 配置环境变量
-
-复制 env.example 为 .env 并填写配置
+#### 3.1 安装 Python 依赖
 
 ```bash
-# Neo4j 图数据库 
+# 安装依赖管理工具 uv
+pip install uv
+
+# 切换到 API 目录
+cd api
+
+# 安装依赖
+uv sync
+
+# 激活虚拟环境
+# Windows (PowerShell，在 api 目录下)
+.venv\Scripts\Activate.ps1
+# Windows (cmd，在 api 目录下)
+.venv\Scripts\activate.bat
+# macOS / Linux
+source .venv/bin/activate
+```
+
+#### 3.2 安装基础服务（Docker 镜像）
+
+使用 Docker Desktop 安装所需镜像：[下载 Docker Desktop](https://www.docker.com/products/docker-desktop/)
+
+**PostgreSQL**
+
+拉取镜像：search → select → pull
+
+<img width="1280" height="731" alt="PostgreSQL Pull" src="https://github.com/user-attachments/assets/96272efe-50ca-4a32-9686-5f23bc3f6c93" />
+
+创建容器：
+
+<img width="1280" height="731" alt="PostgreSQL Container" src="https://github.com/user-attachments/assets/074ea9da-9a3d-401b-b14b-89b81e05487e" />
+
+<img width="1280" height="731" alt="PostgreSQL Running" src="https://github.com/user-attachments/assets/a14744cd-9350-4a2f-87dd-6105b072487d" />
+
+**Neo4j**
+
+拉取镜像方式同上。创建容器时需映射两个关键端口，并设置初始密码：
+- `7474`：Neo4j Browser
+- `7687`：Bolt 协议
+
+<img width="1280" height="731" alt="Neo4j Container" src="https://github.com/user-attachments/assets/881dca96-aec0-4d43-82d0-bb0402eadaf8" />
+
+<img width="1280" height="731" alt="Neo4j Running" src="https://github.com/user-attachments/assets/87423c90-22e8-44a9-a00a-df5d4dce4909" />
+
+**Redis**：同上步骤拉取并创建容器。
+
+**Elasticsearch**
+
+拉取 Elasticsearch 8.x 镜像并创建容器，映射端口 `9200`（HTTP API）和 `9300`（集群通信）。首次启动建议关闭安全认证以简化配置：
+
+```bash
+docker run -d --name elasticsearch \
+  -p 9200:9200 -p 9300:9300 \
+  -e "discovery.type=single-node" \
+  -e "xpack.security.enabled=false" \
+  elasticsearch:8.15.0
+```
+
+#### 3.3 配置环境变量
+
+```bash
+cp env.example .env
+```
+
+编辑 `.env` 填写以下核心配置：
+
+```bash
+# Neo4j 图数据库
 NEO4J_URI=bolt://localhost:7687
 NEO4J_USERNAME=neo4j
 NEO4J_PASSWORD=your-password
-# Neo4j Browser访问地址
 
 # PostgreSQL 数据库
 DB_HOST=127.0.0.1
@@ -191,133 +314,165 @@ DB_USER=postgres
 DB_PASSWORD=your-password
 DB_NAME=redbear-mem
 
-# Database Migration Configuration
-# Set to true to automatically upgrade database schema on startup
-DB_AUTO_UPGRADE=true  # 首次启动设为true自动迁移数据库 在空白数据库创建表结构
+# 首次启动设为 true，自动迁移数据库
+DB_AUTO_UPGRADE=true
 
 # Redis
 REDIS_HOST=127.0.0.1
 REDIS_PORT=6379
-REDIS_DB=1 
+REDIS_DB=1
 
-# Celery (使用Redis作为broker)
-BROKER_URL=redis://127.0.0.1:6379/0
-RESULT_BACKEND=redis://127.0.0.1:6379/0
+# Celery
+REDIS_DB_CELERY_BROKER=1
+REDIS_DB_CELERY_BACKEND=2
 
-# JWT密钥 (生成方式: openssl rand -hex 32)
+# Elasticsearch
+ELASTICSEARCH_HOST=127.0.0.1
+ELASTICSEARCH_PORT=9200
+
+# JWT 密钥（生成方式：openssl rand -hex 32）
 SECRET_KEY=your-secret-key-here
 ```
 
-#### 1.4 PostgreSQL数据库建立
+#### 3.4 初始化 PostgreSQL 数据库
 
-通过项目中已有的 alembic 数据库迁移文件，为全新创建的空白 PostgreSQL 数据库创建对应的表结构。
+确认 `alembic.ini` 中的数据库连接配置：
 
-**（1）配置数据库连接**
-
-确认项目中`alembic.ini`文件的`sqlalchemy.url`配置指向你的空白 PostgreSQL 数据库，格式示例：
-
-```bash
-sqlalchemy.url = postgresql://用户名:密码@数据库地址:端口/空白数据库名
+```ini
+sqlalchemy.url = postgresql://用户名:密码@数据库地址:端口/数据库名
 ```
 
-同时检查 migrations`/env.py`中`target_metadata`是否正确关联到 ORM 模型的`metadata`（确保迁移脚本和模型一致）
-
-**（2）执行迁移文件**
-
-在API目录执行以下命令，alembic 会自动识别空白数据库，并执行所有未应用的迁移脚本，创建完整表结构：
+执行迁移，创建完整表结构：
 
 ```bash
 alembic upgrade head
 ```
 
-<img width="1076" height="341" alt="image-3" src="https://github.com/user-attachments/assets/9edda79d-4637-46e3-bee3-2eec39975d59" />
+<img width="1076" height="341" alt="Alembic Migration" src="https://github.com/user-attachments/assets/6970a8e6-712b-4f49-937a-f5870a2d1a2a" />
 
+<img width="1280" height="680" alt="Database Tables" src="https://github.com/user-attachments/assets/8bbec421-de0c-472b-a7ce-8b89cc1e2efd" />
 
-通过Navicat查看迁移创建的数据库表结构
+#### 3.5 启动 API 服务
 
-<img width="1280" height="680" alt="image-4" src="https://github.com/user-attachments/assets/aa5c1d98-bdc3-4d25-acb2-5c8cf6ecd3f5" />
-
-
-#### API服务启动
-
-```python
+```bash
 uv run -m app.main
 ```
 
 访问 API 文档：http://localhost:8000/docs
 
-<img width="1280" height="675" alt="image-5" src="https://github.com/user-attachments/assets/68fa62b4-2c4f-4cf0-896c-41d59aa7d712" />
+<img width="1280" height="675" alt="API Docs" src="https://github.com/user-attachments/assets/6d1c71b7-9ee8-4f80-9bed-19c410d6e85f" />
 
+#### 3.6 启动 Celery Worker（可选，用于异步任务）
 
-### 2.前端web应用启动
+```bash
+# 记忆任务 Worker（线程池，支持高并发 asyncio）
+celery -A app.celery_worker.celery_app worker --loglevel=info --pool=threads --concurrency=100 --queues=memory_tasks
 
-#### 2.1安装依赖
+# 文档解析 Worker（进程池，CPU 密集型）
+celery -A app.celery_worker.celery_app worker --loglevel=info --pool=prefork --concurrency=4 --queues=document_tasks
 
-```python
-# 切换web目录下
+# 定时任务 Worker（反思引擎等）
+celery -A app.celery_worker.celery_app worker --loglevel=info --pool=prefork --concurrency=2 --queues=periodic_tasks
+
+# Beat 调度器
+celery -A app.celery_worker.celery_app beat --loglevel=info
+```
+
+### 四、前端 Web 应用启动
+
+#### 4.1 安装依赖
+
+```bash
 cd web
-
-# 下载依赖
 npm install
 ```
 
-#### 2.2 修改API代理配置
+#### 4.2 修改 API 代理配置
 
-编辑 web/vite.config.ts，将代理目标改为后端地址
+编辑 `web/vite.config.ts`：
 
-```python
+```typescript
 proxy: {
   '/api': {
-    target: 'http://127.0.0.1:8000',  // 改为后端地址，win用户127.0.0.1  mac用户0.0.0.0
+    target: 'http://127.0.0.1:8000',  // Windows 用 127.0.0.1，macOS 用 0.0.0.0
     changeOrigin: true,
   },
 }
-
 ```
 
-#### 2.3 启动服务
+#### 4.3 启动前端服务
 
-```python
-# 启动web服务
+```bash
 npm run dev
-
 ```
 
-服务启动会输出可访问的前端界面
+<img width="935" height="311" alt="Frontend Start" src="https://github.com/user-attachments/assets/8b08fc46-01d0-458b-ab4d-f5ac04bc2510" />
 
-<img width="935" height="311" alt="image-6" src="https://github.com/user-attachments/assets/cba1074a-440c-4866-8a94-7b6d1c911a93" />
+<img width="1280" height="652" alt="Frontend UI" src="https://github.com/user-attachments/assets/542dbee3-8cd4-4b16-a8e5-36f8d6153820" />
 
+### 五、初始化系统
 
-<img width="1280" height="652" alt="image-7" src="https://github.com/user-attachments/assets/a719dc0a-cbdd-4ba1-9b21-123d5eac32eb" />
+```bash
+# 初始化数据库，获取超级管理员账号
+curl -X POST http://127.0.0.1:8000/api/setup
+```
 
+**超级管理员账号：**
+- 账号：`admin@example.com`
+- 密码：`admin_password`
 
-## 四、用户操作
+### 六、完整启动流程
 
-step1：项目获取
+```
+Step 1  克隆项目
+Step 2  启动基础服务（PostgreSQL / Neo4j / Redis / Elasticsearch）
+Step 3  配置 .env 环境变量
+Step 4  执行 alembic upgrade head 初始化数据库
+Step 5  uv run -m app.main 启动后端 API
+Step 6  npm run dev 启动前端
+Step 7  curl -X POST http://127.0.0.1:8000/api/setup 初始化系统
+Step 8  使用管理员账号登录前端页面
+```
 
-step2：后端API服务启动
-
-step3：前端web应用启动
-
-step4： 终端输入 curl.exe -X POST http://127.0.0.1:8000/api/setup ，访问接口初始化数据库获得超级管理员账号
-
-step5：超级管理员&#x20;
-
-账号：admin@example.com
-
-密码：admin\_password
-
-step6：登陆前端页面
+---
 
+## 技术栈
 
+| 层级 | 技术 |
+|------|------|
+| 后端框架 | FastAPI + Uvicorn |
+| 异步任务 | Celery（三队列：memory / document / periodic） |
+| 主数据库 | PostgreSQL 13+ |
+| 图数据库 | Neo4j 4.4+ |
+| 搜索引擎 | Elasticsearch 8.x（关键词 + 语义向量混合） |
+| 缓存/队列 | Redis 6.0+ |
+| ORM | SQLAlchemy 2.0 + Alembic |
+| LLM 集成 | LangChain / OpenAI / DashScope / AWS Bedrock |
+| MCP 集成 | fastmcp + langchain-mcp-adapters |
+| 前端框架 | React 18 + TypeScript + Vite |
+| UI 组件库 | Ant Design 5.x |
+| 图可视化 | AntV X6 + ECharts + D3.js |
+| 包管理 | uv（后端）/ npm（前端） |
 
+---
 
 ## 许可证
 
-本项目采用 Apache License 2.0 开源协议，详情见 `LICENSE`。
+本项目采用 [Apache License 2.0](LICENSE) 开源协议。
+
+---
 
 ## 致谢与交流
 
-- 问题反馈与讨论：请提交 Issue 到代码仓库
-- 欢迎贡献：提交 PR 前请先创建功能分支并遵循常规提交信息格式
-- 如感兴趣需要联络：tianyou_hubm@redbearai.com
+- **问题反馈**：请提交 [Issue](https://github.com/SuanmoSuanyangTechnology/MemoryBear/issues)
+- **贡献代码**：请阅读 [贡献指南](CONTRIBUTING.md)，提交 [Pull Request](https://github.com/SuanmoSuanyangTechnology/MemoryBear/pulls) 前请先创建功能分支并遵循 Conventional Commits 格式
+- **社区讨论**：[GitHub Discussions](https://github.com/SuanmoSuanyangTechnology/MemoryBear/discussions)
+- **微信社群**：扫描下方二维码加入微信交流群
+
+![WeChat QR](https://github.com/user-attachments/assets/8c81885c-4134-40d5-96e2-7f78cc082dc6)
+
+- **Star 历史**：
+
+[![Star History Chart](https://api.star-history.com/svg?repos=SuanmoSuanyangTechnology/MemoryBear&type=Date)](https://star-history.com/#SuanmoSuanyangTechnology/MemoryBear&Date)
+
+- **联系我们**：tianyou_hubm@redbearai.com

api/Dockerfile

@@ -45,7 +45,8 @@ RUN --mount=type=cache,id=mem_apt,target=/var/cache/apt,sharing=locked \
     apt install -y libpython3-dev libgtk-4-1 libnss3 xdg-utils libgbm-dev && \
     apt install -y libjemalloc-dev && \
     apt install -y python3-pip pipx nginx unzip curl wget git vim less && \
-    apt install -y ghostscript
+    apt install -y ghostscript && \
+    apt install -y libmagic1
 
 RUN if [ "$NEED_MIRROR" == "1" ]; then \
         pip3 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple && \

api/alembic.ini

@@ -60,7 +60,12 @@ version_path_separator = os  # Use os.pathsep. Default configuration used for ne
 # are written from script.py.mako
 # output_encoding = utf-8
 
-sqlalchemy.url = postgresql://user:password@localhost/dbname
+# Database connection URL - DO NOT hardcode credentials here!
+# Connection string is set dynamically from environment variables in migrations/env.py
+# Required env vars: DB_USER, DB_PASSWORD, DB_HOST, DB_PORT, DB_NAME
+# Example: postgresql://user:password@localhost:5432/dbname
+; sqlalchemy.url = postgresql://user:password@host:port/dbname
+sqlalchemy.url = driver://user:password@host:port/dbname
 
 
 [post_write_hooks]

api/app/aioRedis.py

@@ -1,16 +1,18 @@
-import os
 import asyncio
 import json
 import logging
+import os
+import threading
 from typing import Dict, Any, Optional
+
 import redis.asyncio as redis
 from redis.asyncio import ConnectionPool
+
 from app.core.config import settings
 
 # 设置日志记录器
 logger = logging.getLogger(__name__)
 
-
 # 创建连接池
 pool = ConnectionPool.from_url(
     f"redis://{settings.REDIS_HOST}:{settings.REDIS_PORT}",
@@ -21,6 +23,51 @@ pool = ConnectionPool.from_url(
 )
 aio_redis = redis.StrictRedis(connection_pool=pool)
 
+_REDIS_URL = f"redis://{settings.REDIS_HOST}:{settings.REDIS_PORT}"
+
+# Thread-local storage for connection pools.
+# Each thread (and each forked process) gets its own pool to avoid
+# "Future attached to a different loop" errors in Celery --pool=threads
+# and stale connections after fork in --pool=prefork.
+_thread_local = threading.local()
+
+
+def get_thread_safe_redis() -> redis.StrictRedis:
+    """Return a Redis client whose connection pool is bound to the current
+    thread, process **and** event loop.
+
+    The pool is recreated when:
+    - The PID changes (fork, Celery --pool=prefork)
+    - The thread has no pool yet (Celery --pool=threads)
+    - The previously-cached event loop has been closed (Celery tasks call
+      ``_shutdown_loop_gracefully`` which closes the loop after each run)
+    """
+    current_pid = os.getpid()
+    cached_loop = getattr(_thread_local, "loop", None)
+    loop_stale = cached_loop is not None and cached_loop.is_closed()
+
+    if not hasattr(_thread_local, "pool") \
+            or getattr(_thread_local, "pid", None) != current_pid \
+            or loop_stale:
+        _thread_local.pid = current_pid
+        # Python 3.10+: get_event_loop() raises RuntimeError in threads
+        # where no loop has been set yet (e.g. Celery --pool=threads).
+        try:
+            _thread_local.loop = asyncio.get_event_loop()
+        except RuntimeError:
+            _thread_local.loop = None
+        _thread_local.pool = ConnectionPool.from_url(
+            _REDIS_URL,
+            db=settings.REDIS_DB,
+            password=settings.REDIS_PASSWORD,
+            decode_responses=True,
+            max_connections=5,
+            health_check_interval=30,
+        )
+
+    return redis.StrictRedis(connection_pool=_thread_local.pool)
+
+
 async def get_redis_connection():
     """获取Redis连接"""
     try:
@@ -29,7 +76,8 @@ async def get_redis_connection():
         logger.error(f"Redis连接失败: {str(e)}")
         return None
 
-async def aio_redis_set(key: str, val: str|dict, expire: int = None):
+
+async def aio_redis_set(key: str, val: str | dict, expire: int = None):
     """设置Redis键值
     
     Args:
@@ -40,16 +88,15 @@ async def aio_redis_set(key: str, val: str|dict, expire: int = None):
     try:
         if isinstance(val, dict):
             val = json.dumps(val, ensure_ascii=False)
-        
+
         if expire is not None:
-            # 设置带过期时间的键值
             await aio_redis.set(key, val, ex=expire)
         else:
-            # 设置永久键值
             await aio_redis.set(key, val)
     except Exception as e:
         logger.error(f"Redis set错误: {str(e)}")
 
+
 async def aio_redis_get(key: str):
     """获取Redis键值"""
     try:
@@ -58,6 +105,7 @@ async def aio_redis_get(key: str):
         logger.error(f"Redis get错误: {str(e)}")
         return None
 
+
 async def aio_redis_delete(key: str):
     """删除Redis键"""
     try:
@@ -66,6 +114,7 @@ async def aio_redis_delete(key: str):
         logger.error(f"Redis delete错误: {str(e)}")
         return None
 
+
 async def aio_redis_publish(channel: str, message: Dict[str, Any]) -> bool:
     """发布消息到Redis频道"""
     try:
@@ -78,9 +127,10 @@ async def aio_redis_publish(channel: str, message: Dict[str, Any]) -> bool:
         logger.error(f"Redis发布错误: {str(e)}")
         return False
 
+
 class RedisSubscriber:
     """Redis订阅器"""
-    
+
     def __init__(self, channel: str):
         self.channel = channel
         self.conn = None
@@ -88,25 +138,25 @@ class RedisSubscriber:
         self.is_closed = False
         self._queue = asyncio.Queue()
         self._task = None
-    
+
     async def start(self):
         """开始订阅"""
         if self.is_closed or self._task:
             return
-            
+
         self._task = asyncio.create_task(self._receive_messages())
         logger.info(f"开始订阅: {self.channel}")
-    
+
     async def _receive_messages(self):
         """接收消息"""
         try:
             self.conn = await get_redis_connection()
             if not self.conn:
                 return
-                
+
             self.pubsub = self.conn.pubsub()
             await self.pubsub.subscribe(self.channel)
-            
+
             while not self.is_closed:
                 try:
                     message = await self.pubsub.get_message(ignore_subscribe_messages=True, timeout=0.01)
@@ -127,7 +177,7 @@ class RedisSubscriber:
         finally:
             await self._queue.put(None)
             await self._cleanup()
-    
+
     async def _cleanup(self):
         """清理资源"""
         if self.pubsub:
@@ -141,7 +191,7 @@ class RedisSubscriber:
                 await self.conn.close()
             except Exception:
                 pass
-    
+
     async def get_message(self) -> Optional[Dict[str, Any]]:
         """获取消息"""
         if self.is_closed:
@@ -153,7 +203,7 @@ class RedisSubscriber:
         except Exception as e:
             logger.error(f"获取消息错误: {str(e)}")
             return None
-    
+
     async def close(self):
         """关闭订阅器"""
         if self.is_closed:
@@ -163,32 +213,33 @@ class RedisSubscriber:
             self._task.cancel()
         await self._cleanup()
 
+
 class RedisPubSubManager:
     """Redis发布订阅管理器"""
-    
+
     def __init__(self):
         self.subscribers = {}
-    
+
     async def publish(self, channel: str, message: Dict[str, Any]) -> bool:
         return await aio_redis_publish(channel, message)
-    
+
     def get_subscriber(self, channel: str) -> RedisSubscriber:
         if channel in self.subscribers:
             subscriber = self.subscribers[channel]
             if not subscriber.is_closed:
                 return subscriber
-        
+
         subscriber = RedisSubscriber(channel)
         self.subscribers[channel] = subscriber
         return subscriber
-    
+
     def cancel_subscription(self, channel: str) -> bool:
         if channel in self.subscribers:
             asyncio.create_task(self.subscribers[channel].close())
             del self.subscribers[channel]
             return True
         return False
-    
+
     def cancel_all_subscriptions(self) -> int:
         count = len(self.subscribers)
         for subscriber in self.subscribers.values():
@@ -196,6 +247,6 @@ class RedisPubSubManager:
         self.subscribers.clear()
         return count
 
+
 # 全局实例
 pubsub_manager = RedisPubSubManager()
-

api/app/cache/__init__.py

@@ -3,9 +3,8 @@ Cache 缓存模块
 
 提供各种缓存功能的统一入口
 """
-from .memory import EmotionMemoryCache, ImplicitMemoryCache
+from .memory import InterestMemoryCache
 
 __all__ = [
-    "EmotionMemoryCache",
-    "ImplicitMemoryCache",
+    "InterestMemoryCache",
 ]

api/app/cache/memory/__init__.py

@@ -3,10 +3,10 @@ Memory 缓存模块
 
 提供记忆系统相关的缓存功能
 """
-from .emotion_memory import EmotionMemoryCache
-from .implicit_memory import ImplicitMemoryCache
+from .interest_memory import InterestMemoryCache
+from .activity_stats_cache import ActivityStatsCache
 
 __all__ = [
-    "EmotionMemoryCache",
-    "ImplicitMemoryCache",
+    "InterestMemoryCache",
+    "ActivityStatsCache",
 ]

api/app/cache/memory/activity_stats_cache.py

@@ -0,0 +1,124 @@
+"""
+Recent Activity Stats Cache
+
+记忆提取活动统计缓存模块
+用于缓存每次记忆提取流程的统计数据，按 workspace_id 存储，24小时后释放
+查询命令：cache:memory:activity_stats:by_workspace:7de31a97-40a6-4fc0-b8d3-15c89f523843
+"""
+import json
+import logging
+from typing import Optional, Dict, Any
+from datetime import datetime
+
+from app.aioRedis import get_thread_safe_redis
+
+logger = logging.getLogger(__name__)
+
+# 缓存过期时间：24小时
+ACTIVITY_STATS_CACHE_EXPIRE = 86400
+
+
+class ActivityStatsCache:
+    """记忆提取活动统计缓存类"""
+
+    PREFIX = "cache:memory:activity_stats"
+
+    @classmethod
+    def _get_key(cls, workspace_id: str) -> str:
+        """生成 Redis key
+
+        Args:
+            workspace_id: 工作空间ID
+
+        Returns:
+            完整的 Redis key
+        """
+        return f"{cls.PREFIX}:by_workspace:{workspace_id}"
+
+    @classmethod
+    async def set_activity_stats(
+        cls,
+        workspace_id: str,
+        stats: Dict[str, Any],
+        expire: int = ACTIVITY_STATS_CACHE_EXPIRE,
+    ) -> bool:
+        """设置记忆提取活动统计缓存
+
+        Args:
+            workspace_id: 工作空间ID
+            stats: 统计数据，格式：
+                {
+                    "chunk_count": int,
+                    "statements_count": int,
+                    "triplet_entities_count": int,
+                    "triplet_relations_count": int,
+                    "temporal_count": int,
+                }
+            expire: 过期时间（秒），默认24小时
+
+        Returns:
+            是否设置成功
+        """
+        try:
+            key = cls._get_key(workspace_id)
+            payload = {
+                "stats": stats,
+                "generated_at": datetime.now().isoformat(),
+                "workspace_id": workspace_id,
+                "cached": True,
+            }
+            value = json.dumps(payload, ensure_ascii=False)
+            await get_thread_safe_redis().set(key, value, ex=expire)
+            logger.info(f"设置活动统计缓存成功: {key}, 过期时间: {expire}秒")
+            return True
+        except Exception as e:
+            logger.error(f"设置活动统计缓存失败: {e}", exc_info=True)
+            return False
+
+    @classmethod
+    async def get_activity_stats(
+        cls,
+        workspace_id: str,
+    ) -> Optional[Dict[str, Any]]:
+        """获取记忆提取活动统计缓存
+
+        Args:
+            workspace_id: 工作空间ID
+
+        Returns:
+            统计数据字典，缓存不存在或已过期返回 None
+        """
+        try:
+            key = cls._get_key(workspace_id)
+            value = await get_thread_safe_redis().get(key)
+            if value:
+                payload = json.loads(value)
+                logger.info(f"命中活动统计缓存: {key}")
+                return payload
+            logger.info(f"活动统计缓存不存在或已过期: {key}")
+            return None
+        except Exception as e:
+            logger.error(f"获取活动统计缓存失败: {e}", exc_info=True)
+            return None
+
+    @classmethod
+    async def delete_activity_stats(
+        cls,
+        workspace_id: str,
+    ) -> bool:
+        """删除记忆提取活动统计缓存
+
+        Args:
+            workspace_id: 工作空间ID
+
+        Returns:
+            是否删除成功
+        """
+        try:
+            key = cls._get_key(workspace_id)
+            result = await get_thread_safe_redis().delete(key)
+            logger.info(f"删除活动统计缓存: {key}, 结果: {result}")
+            return result > 0
+        except Exception as e:
+            logger.error(f"删除活动统计缓存失败: {e}", exc_info=True)
+            return False

api/app/cache/memory/emotion_memory.py

@@ -1,134 +0,0 @@
-"""
-Emotion Suggestions Cache
-
-情绪个性化建议缓存模块
-用于缓存用户的情绪个性化建议数据
-"""
-import json
-import logging
-from typing import Optional, Dict, Any
-from datetime import datetime
-
-from app.aioRedis import aio_redis
-
-logger = logging.getLogger(__name__)
-
-
-class EmotionMemoryCache:
-    """情绪建议缓存类"""
-    
-    # Key 前缀
-    PREFIX = "cache:memory:emotion_memory"
-    
-    @classmethod
-    def _get_key(cls, *parts: str) -> str:
-        """生成 Redis key
-        
-        Args:
-            *parts: key 的各个部分
-            
-        Returns:
-            完整的 Redis key
-        """
-        return ":".join([cls.PREFIX] + list(parts))
-    
-    @classmethod
-    async def set_emotion_suggestions(
-        cls,
-        user_id: str,
-        suggestions_data: Dict[str, Any],
-        expire: int = 86400
-    ) -> bool:
-        """设置用户情绪建议缓存
-        
-        Args:
-            user_id: 用户ID（end_user_id）
-            suggestions_data: 建议数据字典，包含：
-                - health_summary: 健康状态摘要
-                - suggestions: 建议列表
-                - generated_at: 生成时间（可选）
-            expire: 过期时间（秒），默认24小时（86400秒）
-            
-        Returns:
-            是否设置成功
-        """
-        try:
-            key = cls._get_key("suggestions", user_id)
-            
-            # 添加生成时间戳
-            if "generated_at" not in suggestions_data:
-                suggestions_data["generated_at"] = datetime.now().isoformat()
-            
-            # 添加缓存标记
-            suggestions_data["cached"] = True
-            
-            value = json.dumps(suggestions_data, ensure_ascii=False)
-            await aio_redis.set(key, value, ex=expire)
-            logger.info(f"设置情绪建议缓存成功: {key}, 过期时间: {expire}秒")
-            return True
-        except Exception as e:
-            logger.error(f"设置情绪建议缓存失败: {e}", exc_info=True)
-            return False
-    
-    @classmethod
-    async def get_emotion_suggestions(cls, user_id: str) -> Optional[Dict[str, Any]]:
-        """获取用户情绪建议缓存
-        
-        Args:
-            user_id: 用户ID（end_user_id）
-            
-        Returns:
-            建议数据字典，如果不存在或已过期返回 None
-        """
-        try:
-            key = cls._get_key("suggestions", user_id)
-            value = await aio_redis.get(key)
-            
-            if value:
-                data = json.loads(value)
-                logger.info(f"成功获取情绪建议缓存: {key}")
-                return data
-            
-            logger.info(f"情绪建议缓存不存在或已过期: {key}")
-            return None
-        except Exception as e:
-            logger.error(f"获取情绪建议缓存失败: {e}", exc_info=True)
-            return None
-    
-    @classmethod
-    async def delete_emotion_suggestions(cls, user_id: str) -> bool:
-        """删除用户情绪建议缓存
-        
-        Args:
-            user_id: 用户ID（end_user_id）
-            
-        Returns:
-            是否删除成功
-        """
-        try:
-            key = cls._get_key("suggestions", user_id)
-            result = await aio_redis.delete(key)
-            logger.info(f"删除情绪建议缓存: {key}, 结果: {result}")
-            return result > 0
-        except Exception as e:
-            logger.error(f"删除情绪建议缓存失败: {e}", exc_info=True)
-            return False
-    
-    @classmethod
-    async def get_suggestions_ttl(cls, user_id: str) -> int:
-        """获取情绪建议缓存的剩余过期时间
-        
-        Args:
-            user_id: 用户ID（end_user_id）
-            
-        Returns:
-            剩余秒数，-1表示永不过期，-2表示key不存在
-        """
-        try:
-            key = cls._get_key("suggestions", user_id)
-            ttl = await aio_redis.ttl(key)
-            logger.debug(f"情绪建议缓存TTL: {key} = {ttl}秒")
-            return ttl
-        except Exception as e:
-            logger.error(f"获取情绪建议缓存TTL失败: {e}")
-            return -2

api/app/cache/memory/implicit_memory.py

@@ -1,136 +0,0 @@
-"""
-Implicit Memory Profile Cache
-
-隐式记忆用户画像缓存模块
-用于缓存用户的完整画像数据（偏好标签、四维画像、兴趣领域、行为习惯）
-"""
-import json
-import logging
-from typing import Optional, Dict, Any
-from datetime import datetime
-
-from app.aioRedis import aio_redis
-
-logger = logging.getLogger(__name__)
-
-
-class ImplicitMemoryCache:
-    """隐式记忆用户画像缓存类"""
-    
-    # Key 前缀
-    PREFIX = "cache:memory:implicit_memory"
-    
-    @classmethod
-    def _get_key(cls, *parts: str) -> str:
-        """生成 Redis key
-        
-        Args:
-            *parts: key 的各个部分
-            
-        Returns:
-            完整的 Redis key
-        """
-        return ":".join([cls.PREFIX] + list(parts))
-    
-    @classmethod
-    async def set_user_profile(
-        cls,
-        user_id: str,
-        profile_data: Dict[str, Any],
-        expire: int = 86400
-    ) -> bool:
-        """设置用户完整画像缓存
-        
-        Args:
-            user_id: 用户ID（end_user_id）
-            profile_data: 画像数据字典，包含：
-                - preferences: 偏好标签列表
-                - portrait: 四维画像对象
-                - interest_areas: 兴趣领域分布对象
-                - habits: 行为习惯列表
-                - generated_at: 生成时间（可选）
-            expire: 过期时间（秒），默认24小时（86400秒）
-            
-        Returns:
-            是否设置成功
-        """
-        try:
-            key = cls._get_key("profile", user_id)
-            
-            # 添加生成时间戳
-            if "generated_at" not in profile_data:
-                profile_data["generated_at"] = datetime.now().isoformat()
-            
-            # 添加缓存标记
-            profile_data["cached"] = True
-            
-            value = json.dumps(profile_data, ensure_ascii=False)
-            await aio_redis.set(key, value, ex=expire)
-            logger.info(f"设置用户画像缓存成功: {key}, 过期时间: {expire}秒")
-            return True
-        except Exception as e:
-            logger.error(f"设置用户画像缓存失败: {e}", exc_info=True)
-            return False
-    
-    @classmethod
-    async def get_user_profile(cls, user_id: str) -> Optional[Dict[str, Any]]:
-        """获取用户完整画像缓存
-        
-        Args:
-            user_id: 用户ID（end_user_id）
-            
-        Returns:
-            画像数据字典，如果不存在或已过期返回 None
-        """
-        try:
-            key = cls._get_key("profile", user_id)
-            value = await aio_redis.get(key)
-            
-            if value:
-                data = json.loads(value)
-                logger.info(f"成功获取用户画像缓存: {key}")
-                return data
-            
-            logger.info(f"用户画像缓存不存在或已过期: {key}")
-            return None
-        except Exception as e:
-            logger.error(f"获取用户画像缓存失败: {e}", exc_info=True)
-            return None
-    
-    @classmethod
-    async def delete_user_profile(cls, user_id: str) -> bool:
-        """删除用户完整画像缓存
-        
-        Args:
-            user_id: 用户ID（end_user_id）
-            
-        Returns:
-            是否删除成功
-        """
-        try:
-            key = cls._get_key("profile", user_id)
-            result = await aio_redis.delete(key)
-            logger.info(f"删除用户画像缓存: {key}, 结果: {result}")
-            return result > 0
-        except Exception as e:
-            logger.error(f"删除用户画像缓存失败: {e}", exc_info=True)
-            return False
-    
-    @classmethod
-    async def get_profile_ttl(cls, user_id: str) -> int:
-        """获取用户画像缓存的剩余过期时间
-        
-        Args:
-            user_id: 用户ID（end_user_id）
-            
-        Returns:
-            剩余秒数，-1表示永不过期，-2表示key不存在
-        """
-        try:
-            key = cls._get_key("profile", user_id)
-            ttl = await aio_redis.ttl(key)
-            logger.debug(f"用户画像缓存TTL: {key} = {ttl}秒")
-            return ttl
-        except Exception as e:
-            logger.error(f"获取用户画像缓存TTL失败: {e}")
-            return -2

api/app/cache/memory/interest_memory.py

@@ -0,0 +1,122 @@
+"""
+Interest Distribution Cache
+
+兴趣分布缓存模块
+用于缓存用户的兴趣分布标签数据，避免重复调用模型生成
+"""
+import json
+import logging
+from typing import Optional, List, Dict, Any
+from datetime import datetime
+
+from app.aioRedis import get_thread_safe_redis
+
+logger = logging.getLogger(__name__)
+
+# 缓存过期时间：24小时
+INTEREST_CACHE_EXPIRE = 86400
+
+
+class InterestMemoryCache:
+    """兴趣分布缓存类"""
+
+    PREFIX = "cache:memory:interest_distribution"
+
+    @classmethod
+    def _get_key(cls, end_user_id: str, language: str) -> str:
+        """生成 Redis key
+
+        Args:
+            end_user_id: 用户ID
+            language: 语言类型
+
+        Returns:
+            完整的 Redis key
+        """
+        return f"{cls.PREFIX}:by_user:{end_user_id}:{language}"
+
+    @classmethod
+    async def set_interest_distribution(
+        cls,
+        end_user_id: str,
+        language: str,
+        data: List[Dict[str, Any]],
+        expire: int = INTEREST_CACHE_EXPIRE,
+    ) -> bool:
+        """设置用户兴趣分布缓存
+
+        Args:
+            end_user_id: 用户ID
+            language: 语言类型
+            data: 兴趣分布列表，格式 [{"name": "...", "frequency": ...}, ...]
+            expire: 过期时间（秒），默认24小时
+
+        Returns:
+            是否设置成功
+        """
+        try:
+            key = cls._get_key(end_user_id, language)
+            payload = {
+                "data": data,
+                "generated_at": datetime.now().isoformat(),
+                "cached": True,
+            }
+            value = json.dumps(payload, ensure_ascii=False)
+            await get_thread_safe_redis().set(key, value, ex=expire)
+            logger.info(f"设置兴趣分布缓存成功: {key}, 过期时间: {expire}秒")
+            return True
+        except Exception as e:
+            logger.error(f"设置兴趣分布缓存失败: {e}", exc_info=True)
+            return False
+
+    @classmethod
+    async def get_interest_distribution(
+        cls,
+        end_user_id: str,
+        language: str,
+    ) -> Optional[List[Dict[str, Any]]]:
+        """获取用户兴趣分布缓存
+
+        Args:
+            end_user_id: 用户ID
+            language: 语言类型
+
+        Returns:
+            兴趣分布列表，缓存不存在或已过期返回 None
+        """
+        try:
+            key = cls._get_key(end_user_id, language)
+            value = await get_thread_safe_redis().get(key)
+            if value:
+                payload = json.loads(value)
+                logger.info(f"命中兴趣分布缓存: {key}")
+                return payload.get("data")
+            logger.info(f"兴趣分布缓存不存在或已过期: {key}")
+            return None
+        except Exception as e:
+            logger.error(f"获取兴趣分布缓存失败: {e}", exc_info=True)
+            return None
+
+    @classmethod
+    async def delete_interest_distribution(
+        cls,
+        end_user_id: str,
+        language: str,
+    ) -> bool:
+        """删除用户兴趣分布缓存
+
+        Args:
+            end_user_id: 用户ID
+            language: 语言类型
+
+        Returns:
+            是否删除成功
+        """
+        try:
+            key = cls._get_key(end_user_id, language)
+            result = await get_thread_safe_redis().delete(key)
+            logger.info(f"删除兴趣分布缓存: {key}, 结果: {result}")
+            return result > 0
+        except Exception as e:
+            logger.error(f"删除兴趣分布缓存失败: {e}", exc_info=True)
+            return False

api/app/celery_app.py

@@ -1,25 +1,59 @@
 import os
 import platform
+import re
 from datetime import timedelta
 from urllib.parse import quote
 
 from celery import Celery
+from celery.schedules import crontab
 
 from app.core.config import settings
+from app.core.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+
+def _mask_url(url: str) -> str:
+    """隐藏 URL 中的密码部分，适用于 redis:// 和 amqp:// 等协议"""
+    return re.sub(r'(://[^:]*:)[^@]+(@)', r'\1***\2', url)
+
 
 # macOS fork() safety - must be set before any Celery initialization
 if platform.system() == 'Darwin':
     os.environ.setdefault('OBJC_DISABLE_INITIALIZE_FORK_SAFETY', 'YES')
 
 # 创建 Celery 应用实例
-# broker: 任务队列（使用 Redis DB 0）
-# backend: 结果存储（使用 Redis DB 10）
+# broker: 优先使用环境变量 CELERY_BROKER_URL（支持 amqp:// 等任意协议），
+#         未配置则回退到 Redis 方案
+# backend: 结果存储（使用 Redis）
+# NOTE: 不要在 .env 中设置 BROKER_URL / RESULT_BACKEND / CELERY_BROKER / CELERY_BACKEND，
+#       这些名称会被 Celery CLI 的 Click 框架劫持，详见 docs/celery-env-bug-report.md
+
+_broker_url = os.getenv("CELERY_BROKER_URL") or \
+              f"redis://:{quote(settings.REDIS_PASSWORD)}@{settings.REDIS_HOST}:{settings.REDIS_PORT}/{settings.REDIS_DB_CELERY_BROKER}"
+_backend_url = f"redis://:{quote(settings.REDIS_PASSWORD)}@{settings.REDIS_HOST}:{settings.REDIS_PORT}/{settings.REDIS_DB_CELERY_BACKEND}"
+os.environ["CELERY_BROKER_URL"] = _broker_url
+os.environ["CELERY_RESULT_BACKEND"] = _backend_url
+# Neutralize legacy Celery env vars that can be hijacked by Celery's CLI/Click
+# integration and accidentally override our canonical URLs.
+os.environ.pop("BROKER_URL", None)
+os.environ.pop("RESULT_BACKEND", None)
+os.environ.pop("CELERY_BROKER", None)
+os.environ.pop("CELERY_BACKEND", None)
+
 celery_app = Celery(
     "redbear_tasks",
-    broker=f"redis://:{quote(settings.REDIS_PASSWORD)}@{settings.REDIS_HOST}:{settings.REDIS_PORT}/{settings.CELERY_BROKER}",
-    backend=f"redis://:{quote(settings.REDIS_PASSWORD)}@{settings.REDIS_HOST}:{settings.REDIS_PORT}/{settings.CELERY_BACKEND}",
+    broker=_broker_url,
+    backend=_backend_url,
 )
 
+logger.info(
+    "Celery app initialized",
+    extra={
+        "broker": _mask_url(_broker_url),
+        "backend": _mask_url(_backend_url),
+    },
+)
 # Default queue for unrouted tasks
 celery_app.conf.task_default_queue = 'memory_tasks'
 
@@ -33,56 +67,70 @@ celery_app.conf.update(
     task_serializer='json',
     accept_content=['json'],
     result_serializer='json',
-    
-    # 时区
-    timezone='Asia/Shanghai',
-    enable_utc=True,
-    
+
+    # # 时区
+    # timezone='Asia/Shanghai',
+    # enable_utc=False,
+
     # 任务追踪
     task_track_started=True,
     task_ignore_result=False,
-    
+
     # 超时设置
-    task_time_limit=1800,  # 30分钟硬超时
-    task_soft_time_limit=1500,  # 25分钟软超时
-    
+    task_time_limit=3600,  # 60分钟硬超时
+    task_soft_time_limit=3000,  # 50分钟软超时
+
     # Worker 设置 (per-worker settings are in docker-compose command line)
     worker_prefetch_multiplier=1,  # Don't hoard tasks, fairer distribution
-    
+    worker_redirect_stdouts_level='INFO',  # stdout/print → INFO instead of WARNING
+
     # 结果过期时间
     result_expires=3600,  # 结果保存1小时
-    
+
     # 任务确认设置
     task_acks_late=True,
     task_reject_on_worker_lost=True,
     worker_disable_rate_limits=True,
-    
+
     # FLower setting 
     worker_send_task_events=True,
     task_send_sent_event=True,
-    
+
     # task routing
     task_routes={
         # Memory tasks → memory_tasks queue (threads worker)
         'app.core.memory.agent.read_message_priority': {'queue': 'memory_tasks'},
         'app.core.memory.agent.read_message': {'queue': 'memory_tasks'},
         'app.core.memory.agent.write_message': {'queue': 'memory_tasks'},
-        
+
         # Long-term storage tasks → memory_tasks queue (batched write strategies)
         'app.core.memory.agent.long_term_storage.window': {'queue': 'memory_tasks'},
         'app.core.memory.agent.long_term_storage.time': {'queue': 'memory_tasks'},
         'app.core.memory.agent.long_term_storage.aggregate': {'queue': 'memory_tasks'},
-        
+
+        # Clustering tasks → memory_tasks queue (使用相同的 worker，避免 macOS fork 问题)
+        'app.tasks.run_incremental_clustering': {'queue': 'memory_tasks'},
+
+        # Metadata extraction → memory_tasks queue
+        'app.tasks.extract_user_metadata': {'queue': 'memory_tasks'},
+
         # Document tasks → document_tasks queue (prefork worker)
         'app.core.rag.tasks.parse_document': {'queue': 'document_tasks'},
-        'app.core.rag.tasks.build_graphrag_for_kb': {'queue': 'document_tasks'},
         'app.core.rag.tasks.sync_knowledge_for_kb': {'queue': 'document_tasks'},
-        
+
+        # GraphRAG tasks → graphrag_tasks queue (独立队列，避免阻塞文档解析)
+        'app.core.rag.tasks.build_graphrag_for_kb': {'queue': 'graphrag_tasks'},
+        'app.core.rag.tasks.build_graphrag_for_document': {'queue': 'graphrag_tasks'},
+
         # Beat/periodic tasks → periodic_tasks queue (dedicated periodic worker)
         'app.tasks.workspace_reflection_task': {'queue': 'periodic_tasks'},
         'app.tasks.regenerate_memory_cache': {'queue': 'periodic_tasks'},
         'app.tasks.run_forgetting_cycle_task': {'queue': 'periodic_tasks'},
-        'app.controllers.memory_storage_controller.search_all': {'queue': 'periodic_tasks'},
+        'app.tasks.write_all_workspaces_memory_task': {'queue': 'periodic_tasks'},
+        'app.tasks.update_implicit_emotions_storage': {'queue': 'periodic_tasks'},
+        'app.tasks.init_implicit_emotions_for_users': {'queue': 'periodic_tasks'},
+        'app.tasks.init_interest_distribution_for_users': {'queue': 'periodic_tasks'},
+        'app.tasks.init_community_clustering_for_users': {'queue': 'periodic_tasks'},
     },
 )
 
@@ -90,13 +138,16 @@ celery_app.conf.update(
 celery_app.autodiscover_tasks(['app'])
 
 # Celery Beat schedule for periodic tasks
-memory_increment_schedule = timedelta(hours=settings.MEMORY_INCREMENT_INTERVAL_HOURS)
+memory_increment_schedule = crontab(hour=settings.MEMORY_INCREMENT_HOUR, minute=settings.MEMORY_INCREMENT_MINUTE)
 memory_cache_regeneration_schedule = timedelta(hours=settings.MEMORY_CACHE_REGENERATION_HOURS)
-# 这个30秒的设计不合理
-workspace_reflection_schedule = timedelta(seconds=30)  # 每30秒运行一次settings.REFLECTION_INTERVAL_TIME
-forgetting_cycle_schedule = timedelta(hours=24)  # 每24小时运行一次遗忘周期
+workspace_reflection_schedule = timedelta(seconds=settings.WORKSPACE_REFLECTION_INTERVAL_SECONDS)
+forgetting_cycle_schedule = timedelta(hours=settings.FORGETTING_CYCLE_INTERVAL_HOURS)
+implicit_emotions_update_schedule = crontab(
+    hour=settings.IMPLICIT_EMOTIONS_UPDATE_HOUR,
+    minute=settings.IMPLICIT_EMOTIONS_UPDATE_MINUTE,
+)
 
-#构建定时任务配置
+# 构建定时任务配置
 beat_schedule_config = {
     "run-workspace-reflection": {
         "task": "app.tasks.workspace_reflection_task",
@@ -115,16 +166,16 @@ beat_schedule_config = {
             "config_id": None,  # 使用默认配置，可以通过环境变量配置
         },
     },
+    "write-all-workspaces-memory": {
+        "task": "app.tasks.write_all_workspaces_memory_task",
+        "schedule": memory_increment_schedule,
+        "args": (),
+    },
+    "update-implicit-emotions-storage": {
+        "task": "app.tasks.update_implicit_emotions_storage",
+        "schedule": implicit_emotions_update_schedule,
+        "args": (),
+    },
 }
 
-#如果配置了默认工作空间ID，则添加记忆总量统计任务
-if settings.DEFAULT_WORKSPACE_ID:
-    beat_schedule_config["write-total-memory"] = {
-        "task": "app.controllers.memory_storage_controller.search_all",
-        "schedule": memory_increment_schedule,
-        "kwargs": {
-            "workspace_id": settings.DEFAULT_WORKSPACE_ID,
-        },
-    }
-
 celery_app.conf.beat_schedule = beat_schedule_config

api/app/celery_task_scheduler.py

@@ -0,0 +1,500 @@
+import hashlib
+import json
+import os
+import socket
+import threading
+import time
+import uuid
+
+import redis
+
+from app.core.config import settings
+from app.core.logging_config import get_named_logger
+from app.celery_app import celery_app
+
+logger = get_named_logger("task_scheduler")
+
+# per-user queue scheduler:uq:{user_id}
+USER_QUEUE_PREFIX = "scheduler:uq:"
+# User Collection of Pending Messages
+ACTIVE_USERS = "scheduler:active_users"
+# Set of users that can dispatch (ready signal)
+READY_SET = "scheduler:ready_users"
+# Metadata of tasks that have been dispatched and are pending completion
+PENDING_HASH = "scheduler:pending_tasks"
+# Dynamic Sharding: Instance Registry
+REGISTRY_KEY = "scheduler:instances"
+
+TASK_TIMEOUT = 7800  # Task timeout (seconds), considered lost if exceeded
+HEARTBEAT_INTERVAL = 10  # Heartbeat interval (seconds)
+INSTANCE_TTL = 30  # Instance timeout (seconds)
+
+LUA_ATOMIC_LOCK = """
+local dispatch_lock = KEYS[1]
+local lock_key = KEYS[2]
+local instance_id = ARGV[1]
+local dispatch_ttl = tonumber(ARGV[2])
+local lock_ttl = tonumber(ARGV[3])
+
+if redis.call('SET', dispatch_lock, instance_id, 'NX', 'EX', dispatch_ttl) == false then
+    return 0
+end
+
+if redis.call('EXISTS', lock_key) == 1 then
+    redis.call('DEL', dispatch_lock)
+    return -1
+end
+
+redis.call('SET', lock_key, 'dispatching', 'EX', lock_ttl)
+return 1
+"""
+
+LUA_SAFE_DELETE = """
+if redis.call('GET', KEYS[1]) == ARGV[1] then
+    return redis.call('DEL', KEYS[1])
+end
+return 0
+"""
+
+
+def stable_hash(value: str) -> int:
+    return int.from_bytes(
+        hashlib.md5(value.encode("utf-8")).digest(),
+        "big"
+    )
+
+
+def health_check_server(scheduler_ref):
+    import uvicorn
+    from fastapi import FastAPI
+
+    health_app = FastAPI()
+
+    @health_app.get("/")
+    def health():
+        return scheduler_ref.health()
+
+    port = int(os.environ.get("SCHEDULER_HEALTH_PORT", "8001"))
+    threading.Thread(
+        target=uvicorn.run,
+        kwargs={
+            "app": health_app,
+            "host": "0.0.0.0",
+            "port": port,
+            "log_config": None,
+        },
+        daemon=True,
+    ).start()
+    logger.info("[Health] Server started at http://0.0.0.0:%s", port)
+
+
+class RedisTaskScheduler:
+    def __init__(self):
+        self.redis = redis.Redis(
+            host=settings.REDIS_HOST,
+            port=settings.REDIS_PORT,
+            db=settings.REDIS_DB_CELERY_BACKEND,
+            password=settings.REDIS_PASSWORD,
+            decode_responses=True,
+        )
+        self.running = False
+        self.dispatched = 0
+        self.errors = 0
+
+        self.instance_id = f"{socket.gethostname()}-{os.getpid()}"
+        self._shard_index = 0
+        self._shard_count = 1
+        self._last_heartbeat = 0.0
+
+    def push_task(self, task_name, user_id, params):
+        try:
+            msg_id = str(uuid.uuid4())
+            msg = json.dumps({
+                "msg_id": msg_id,
+                "task_name": task_name,
+                "user_id": user_id,
+                "params": json.dumps(params),
+            })
+
+            lock_key = f"{task_name}:{user_id}"
+            queue_key = f"{USER_QUEUE_PREFIX}{user_id}"
+
+            pipe = self.redis.pipeline()
+            pipe.rpush(queue_key, msg)
+            pipe.sadd(ACTIVE_USERS, user_id)
+            pipe.set(
+                f"task_tracker:{msg_id}",
+                json.dumps({"status": "QUEUED", "task_id": None}),
+                ex=86400,
+            )
+            pipe.execute()
+
+            if not self.redis.exists(lock_key):
+                self.redis.sadd(READY_SET, user_id)
+
+            logger.info("Task pushed: msg_id=%s task=%s user=%s", msg_id, task_name, user_id)
+            return msg_id
+        except Exception as e:
+            logger.error("Push task exception %s", e, exc_info=True)
+            raise
+
+    def get_task_status(self, msg_id: str) -> dict:
+        raw = self.redis.get(f"task_tracker:{msg_id}")
+        if raw is None:
+            return {"status": "NOT_FOUND"}
+
+        tracker = json.loads(raw)
+        status = tracker["status"]
+        task_id = tracker.get("task_id")
+        result_content = tracker.get("result") or {}
+
+        if status == "DISPATCHED" and task_id:
+            result_raw = self.redis.get(f"celery-task-meta-{task_id}")
+            if result_raw:
+                result_data = json.loads(result_raw)
+                status = result_data.get("status", status)
+                result_content = result_data.get("result")
+
+        return {"status": status, "task_id": task_id, "result": result_content}
+
+    def _cleanup_finished(self):
+        pending = self.redis.hgetall(PENDING_HASH)
+        if not pending:
+            return
+
+        now = time.time()
+        task_ids = list(pending.keys())
+
+        pipe = self.redis.pipeline()
+        for task_id in task_ids:
+            pipe.get(f"celery-task-meta-{task_id}")
+        results = pipe.execute()
+
+        cleanup_pipe = self.redis.pipeline()
+        has_cleanup = False
+        ready_user_ids = set()
+
+        for task_id, raw_result in zip(task_ids, results):
+            try:
+                meta = json.loads(pending[task_id])
+                lock_key = meta["lock_key"]
+                dispatched_at = meta.get("dispatched_at", 0)
+                age = now - dispatched_at
+
+                should_cleanup = False
+                result_data = {}
+
+                if raw_result is not None:
+                    result_data = json.loads(raw_result)
+                    if result_data.get("status") in ("SUCCESS", "FAILURE", "REVOKED"):
+                        should_cleanup = True
+                        logger.info(
+                            "Task finished: %s state=%s", task_id,
+                            result_data.get("status"),
+                        )
+                elif age > TASK_TIMEOUT:
+                    should_cleanup = True
+                    logger.warning(
+                        "Task expired or lost: %s age=%.0fs, force cleanup",
+                        task_id, age,
+                    )
+
+                if should_cleanup:
+                    final_status = (
+                        result_data.get("status", "UNKNOWN") if result_data else "EXPIRED"
+                    )
+
+                    self.redis.eval(LUA_SAFE_DELETE, 1, lock_key, task_id)
+
+                    cleanup_pipe.hdel(PENDING_HASH, task_id)
+
+                    tracker_msg_id = meta.get("msg_id")
+                    if tracker_msg_id:
+                        cleanup_pipe.set(
+                            f"task_tracker:{tracker_msg_id}",
+                            json.dumps({
+                                "status": final_status,
+                                "task_id": task_id,
+                                "result": result_data.get("result") or {},
+                            }),
+                            ex=86400,
+                        )
+                    has_cleanup = True
+
+                    parts = lock_key.split(":", 1)
+                    if len(parts) == 2:
+                        ready_user_ids.add(parts[1])
+
+            except Exception as e:
+                logger.error("Cleanup error for %s: %s", task_id, e, exc_info=True)
+                self.errors += 1
+
+        if has_cleanup:
+            cleanup_pipe.execute()
+
+        if ready_user_ids:
+            self.redis.sadd(READY_SET, *ready_user_ids)
+
+    def _heartbeat(self):
+        now = time.time()
+        if now - self._last_heartbeat < HEARTBEAT_INTERVAL:
+            return
+        self._last_heartbeat = now
+
+        self.redis.hset(REGISTRY_KEY, self.instance_id, str(now))
+
+        all_instances = self.redis.hgetall(REGISTRY_KEY)
+
+        alive = []
+        dead = []
+        for iid, ts in all_instances.items():
+            if now - float(ts) < INSTANCE_TTL:
+                alive.append(iid)
+            else:
+                dead.append(iid)
+
+        if dead:
+            pipe = self.redis.pipeline()
+            for iid in dead:
+                pipe.hdel(REGISTRY_KEY, iid)
+            pipe.execute()
+            logger.info("Cleaned dead instances: %s", dead)
+
+        alive.sort()
+        self._shard_count = max(len(alive), 1)
+        self._shard_index = (
+            alive.index(self.instance_id) if self.instance_id in alive else 0
+        )
+        logger.debug(
+            "Shard: %s/%s (instance=%s, alive=%d)",
+            self._shard_index, self._shard_count,
+            self.instance_id, len(alive),
+        )
+
+    def _is_mine(self, user_id: str) -> bool:
+        if self._shard_count <= 1:
+            return True
+        return stable_hash(user_id) % self._shard_count == self._shard_index
+
+    def _dispatch(self, msg_id, msg_data) -> bool:
+        user_id = msg_data["user_id"]
+        task_name = msg_data["task_name"]
+        params = json.loads(msg_data.get("params", "{}"))
+
+        lock_key = f"{task_name}:{user_id}"
+        dispatch_lock = f"dispatch:{msg_id}"
+
+        result = self.redis.eval(
+            LUA_ATOMIC_LOCK, 2,
+            dispatch_lock, lock_key,
+            self.instance_id, str(300), str(3600),
+        )
+
+        if result == 0:
+            return False
+        if result == -1:
+            return False
+
+        try:
+            task = celery_app.send_task(task_name, kwargs=params)
+        except Exception as e:
+            pipe = self.redis.pipeline()
+            pipe.delete(dispatch_lock)
+            pipe.delete(lock_key)
+            pipe.execute()
+            self.errors += 1
+            logger.error(
+                "send_task failed for %s:%s msg=%s: %s",
+                task_name, user_id, msg_id, e, exc_info=True,
+            )
+            return False
+
+        try:
+            pipe = self.redis.pipeline()
+            pipe.set(lock_key, task.id, ex=3600)
+            pipe.hset(PENDING_HASH, task.id, json.dumps({
+                "lock_key": lock_key,
+                "dispatched_at": time.time(),
+                "msg_id": msg_id,
+            }))
+            pipe.delete(dispatch_lock)
+            pipe.set(
+                f"task_tracker:{msg_id}",
+                json.dumps({"status": "DISPATCHED", "task_id": task.id}),
+                ex=86400,
+            )
+            pipe.execute()
+        except Exception as e:
+            logger.error(
+                "Post-dispatch state update failed for %s: %s",
+                task.id, e, exc_info=True,
+            )
+            self.errors += 1
+
+        self.dispatched += 1
+        logger.info("Task dispatched: %s (msg=%s)", task.id, msg_id)
+        return True
+
+    def _process_batch(self, user_ids):
+        if not user_ids:
+            return
+
+        pipe = self.redis.pipeline()
+        for uid in user_ids:
+            pipe.lindex(f"{USER_QUEUE_PREFIX}{uid}", 0)
+        heads = pipe.execute()
+
+        candidates = []  # (user_id, msg_dict)
+        empty_users = []
+
+        for uid, head in zip(user_ids, heads):
+            if head is None:
+                empty_users.append(uid)
+            else:
+                try:
+                    candidates.append((uid, json.loads(head)))
+                except (json.JSONDecodeError, TypeError) as e:
+                    logger.error("Bad message in queue for user %s: %s", uid, e)
+                    self.redis.lpop(f"{USER_QUEUE_PREFIX}{uid}")
+
+        if empty_users:
+            pipe = self.redis.pipeline()
+            for uid in empty_users:
+                pipe.srem(ACTIVE_USERS, uid)
+            pipe.execute()
+
+        if not candidates:
+            return
+
+        for uid, msg in candidates:
+            if self._dispatch(msg["msg_id"], msg):
+                self.redis.lpop(f"{USER_QUEUE_PREFIX}{uid}")
+
+    def schedule_loop(self):
+        self._heartbeat()
+        self._cleanup_finished()
+
+        pipe = self.redis.pipeline()
+        pipe.smembers(READY_SET)
+        pipe.delete(READY_SET)
+        results = pipe.execute()
+        ready_users = results[0] or set()
+
+        my_users = [uid for uid in ready_users if self._is_mine(uid)]
+
+        if not my_users:
+            time.sleep(0.5)
+            return
+
+        self._process_batch(my_users)
+        time.sleep(0.1)
+
+    def _full_scan(self):
+        cursor = 0
+        ready_batch = []
+        while True:
+            cursor, user_ids = self.redis.sscan(
+                ACTIVE_USERS, cursor=cursor, count=1000,
+            )
+            if user_ids:
+                my_users = [uid for uid in user_ids if self._is_mine(uid)]
+                if my_users:
+                    pipe = self.redis.pipeline()
+                    for uid in my_users:
+                        pipe.lindex(f"{USER_QUEUE_PREFIX}{uid}", 0)
+                    heads = pipe.execute()
+
+                    for uid, head in zip(my_users, heads):
+                        if head is None:
+                            continue
+                        try:
+                            msg = json.loads(head)
+                            lock_key = f"{msg['task_name']}:{uid}"
+                            ready_batch.append((uid, lock_key))
+                        except (json.JSONDecodeError, TypeError):
+                            continue
+
+            if cursor == 0:
+                break
+
+        if not ready_batch:
+            return
+
+        pipe = self.redis.pipeline()
+        for _, lock_key in ready_batch:
+            pipe.exists(lock_key)
+        lock_exists = pipe.execute()
+
+        ready_uids = [
+            uid for (uid, _), locked in zip(ready_batch, lock_exists)
+            if not locked
+        ]
+
+        if ready_uids:
+            self.redis.sadd(READY_SET, *ready_uids)
+            logger.info("Full scan found %d ready users", len(ready_uids))
+
+    def run_server(self):
+        health_check_server(self)
+        self.running = True
+
+        last_full_scan = 0.0
+        full_scan_interval = 30.0
+
+        logger.info(
+            "Scheduler started: instance=%s", self.instance_id,
+        )
+
+        while True:
+            try:
+                self.schedule_loop()
+
+                now = time.time()
+                if now - last_full_scan > full_scan_interval:
+                    self._full_scan()
+                    last_full_scan = now
+
+            except Exception as e:
+                logger.error("Scheduler exception %s", e, exc_info=True)
+                self.errors += 1
+                time.sleep(5)
+
+    def health(self) -> dict:
+        return {
+            "running": self.running,
+            "active_users": self.redis.scard(ACTIVE_USERS),
+            "ready_users": self.redis.scard(READY_SET),
+            "pending_tasks": self.redis.hlen(PENDING_HASH),
+            "dispatched": self.dispatched,
+            "errors": self.errors,
+            "shard": f"{self._shard_index}/{self._shard_count}",
+            "instance": self.instance_id,
+        }
+
+    def shutdown(self):
+        logger.info("Scheduler shutting down: instance=%s", self.instance_id)
+        self.running = False
+        try:
+            self.redis.hdel(REGISTRY_KEY, self.instance_id)
+        except Exception as e:
+            logger.error("Shutdown cleanup error: %s", e)
+
+
+scheduler: RedisTaskScheduler | None = None
+if scheduler is None:
+    scheduler = RedisTaskScheduler()
+
+if __name__ == "__main__":
+    import signal
+    import sys
+
+
+    def _signal_handler(signum, frame):
+        scheduler.shutdown()
+        sys.exit(0)
+
+
+    signal.signal(signal.SIGTERM, _signal_handler)
+    signal.signal(signal.SIGINT, _signal_handler)
+
+    scheduler.run_server()

api/app/celery_worker.py

@@ -2,6 +2,8 @@
 Celery Worker 入口点
 用于启动 Celery Worker: celery -A app.celery_worker worker --loglevel=info
 """
+from celery.signals import worker_process_init
+
 from app.celery_app import celery_app
 from app.core.logging_config import LoggingConfig, get_logger
 
@@ -13,4 +15,39 @@ logger.info("Celery worker logging initialized")
 # 导入任务模块以注册任务
 import app.tasks
 
-__all__ = ['celery_app']
+
+@worker_process_init.connect
+def _reinit_db_pool(**kwargs):
+    """
+    prefork 子进程启动时重建被 fork 污染的资源。
+    
+    fork() 后子进程继承了父进程的：
+    1. SQLAlchemy 连接池 — 多进程共享 TCP socket 导致 DB 连接损坏
+    2. ThreadPoolExecutor — fork 后线程状态不确定，第二个任务会死锁
+    """
+    # 重建 DB 连接池
+    from app.db import engine
+    engine.dispose()
+    logger.info("DB connection pool disposed for forked worker process")
+
+    # 重建模块级 ThreadPoolExecutor（fork 后线程池不可用）
+    try:
+        from app.core.rag.deepdoc.parser import figure_parser
+        from concurrent.futures import ThreadPoolExecutor
+        figure_parser.shared_executor = ThreadPoolExecutor(max_workers=10)
+        logger.info("figure_parser.shared_executor recreated")
+    except Exception as e:
+        logger.warning(f"Failed to recreate figure_parser.shared_executor: {e}")
+
+    try:
+        from app.core.rag.utils import libre_office
+        from concurrent.futures import ThreadPoolExecutor
+        import os
+        max_workers = os.cpu_count() * 2 if os.cpu_count() else 4
+        libre_office.executor = ThreadPoolExecutor(max_workers=max_workers)
+        logger.info("libre_office.executor recreated")
+    except Exception as e:
+        logger.warning(f"Failed to recreate libre_office.executor: {e}")
+
+
+__all__ = ['celery_app']

api/app/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration module for application settings."""

api/app/config/default_free_plan.py

@@ -0,0 +1,77 @@
+"""
+社区版默认免费套餐配置
+当无法从 SaaS 版获取 premium 模块时，使用此配置作为兜底
+
+可通过环境变量覆盖配额配置，格式：QUOTA_<QUOTA_NAME>
+例如：QUOTA_END_USER_QUOTA=100
+"""
+
+import os
+
+
+def _get_quota_from_env():
+    """从环境变量获取配额配置"""
+    quota_keys = [
+        "workspace_quota",
+        "skill_quota",
+        "app_quota",
+        "knowledge_capacity_quota",
+        "memory_engine_quota",
+        "end_user_quota",
+        "ontology_project_quota",
+        "model_quota",
+        "api_ops_rate_limit",
+    ]
+    quotas = {}
+    for key in quota_keys:
+        env_key = f"QUOTA_{key.upper()}"
+        env_value = os.getenv(env_key)
+        if env_value is not None:
+            try:
+                quotas[key] = float(env_value) if '.' in env_value else int(env_value)
+            except ValueError:
+                pass
+    return quotas
+
+
+def _build_default_free_plan():
+    """构建默认免费套餐配置"""
+    base = {
+        "name": "记忆体验版",
+        "name_en": "Memory Experience",
+        "category": "saas_personal",
+        "tier_level": 0,
+        "version": "1.0",
+        "status": True,
+        "price": 0,
+        "billing_cycle": "permanent_free",
+        "core_value": "感受永久记忆",
+        "core_value_en": "Experience Permanent Memory",
+        "tech_support": "社群交流",
+        "tech_support_en": "Community Support",
+        "sla_compliance": "无",
+        "sla_compliance_en": "None",
+        "page_customization": "无",
+        "page_customization_en": "None",
+        "theme_color": "#64748B",
+        "quotas": {
+            "workspace_quota": 1,
+            "skill_quota": 5,
+            "app_quota": 2,
+            "knowledge_capacity_quota": 0.3,
+            "memory_engine_quota": 1,
+            "end_user_quota": 10,
+            "ontology_project_quota": 3,
+            "model_quota": 1,
+            "api_ops_rate_limit": 50,
+        },
+    }
+
+    env_quotas = _get_quota_from_env()
+    if env_quotas:
+        base["quotas"].update(env_quotas)
+
+    return base
+
+
+DEFAULT_FREE_PLAN = _build_default_free_plan()

api/app/config/default_ontology_config.py

@@ -0,0 +1,239 @@
+"""默认本体场景配置
+
+本模块定义系统预设的本体场景和实体类型配置。
+这些配置用于在工作空间创建时自动初始化默认场景。
+支持中英文双语配置，根据用户语言偏好创建对应语言的场景。
+"""
+
+# 在线教育场景配置
+ONLINE_EDUCATION_SCENE = {
+    "name_chinese": "在线教育",
+    "name_english": "Online Education",
+    "description_chinese": "适用于在线教育平台的本体建模，包含学生、教师、课程等核心实体类型",
+    "description_english": "Ontology modeling for online education platforms, including core entity types such as students, teachers, and courses",
+    "types": [
+        {
+            "name_chinese": "学生",
+            "name_english": "Student",
+            "description_chinese": "在教育系统中接受教育的个体，包含姓名、学号、年级、班级等属性",
+            "description_english": "Individuals receiving education in the education system, including attributes such as name, student ID, grade, and class"
+        },
+        {
+            "name_chinese": "教师",
+            "name_english": "Teacher",
+            "description_chinese": "在教育系统中提供教学服务的个体，包含姓名、工号、任教学科、职称等属性",
+            "description_english": "Individuals providing teaching services in the education system, including attributes such as name, employee ID, teaching subject, and title"
+        },
+        {
+            "name_chinese": "课程",
+            "name_english": "Course",
+            "description_chinese": "教育系统中的教学内容单元，包含课程名称、课程代码、学分、学时等属性",
+            "description_english": "Teaching content units in the education system, including attributes such as course name, course code, credits, and class hours"
+        },
+        {
+            "name_chinese": "作业",
+            "name_english": "Assignment",
+            "description_chinese": "课程中布置的学习任务，包含作业标题、截止日期、所属课程、提交状态等属性",
+            "description_english": "Learning tasks assigned in courses, including attributes such as assignment title, deadline, course, and submission status"
+        },
+        {
+            "name_chinese": "成绩",
+            "name_english": "Grade",
+            "description_chinese": "学生学习成果的评价结果，包含分数、评级、考试类型、所属课程等属性",
+            "description_english": "Evaluation results of student learning outcomes, including attributes such as score, rating, exam type, and course"
+        },
+        {
+            "name_chinese": "考试",
+            "name_english": "Exam",
+            "description_chinese": "评估学生学习成果的测试活动，包含考试名称、时间、地点、科目等属性",
+            "description_english": "Test activities to assess student learning outcomes, including attributes such as exam name, time, location, and subject"
+        },
+        {
+            "name_chinese": "教室",
+            "name_english": "Classroom",
+            "description_chinese": "进行教学活动的物理或虚拟空间，包含教室编号、容量、设备等属性",
+            "description_english": "Physical or virtual spaces for teaching activities, including attributes such as classroom number, capacity, and equipment"
+        },
+        {
+            "name_chinese": "学科",
+            "name_english": "Subject",
+            "description_chinese": "知识的分类领域，包含学科名称、代码、所属院系等属性",
+            "description_english": "Classification domains of knowledge, including attributes such as subject name, code, and department"
+        },
+        {
+            "name_chinese": "教材",
+            "name_english": "Textbook",
+            "description_chinese": "教学使用的书籍或资料，包含书名、作者、出版社、ISBN等属性",
+            "description_english": "Books or materials used for teaching, including attributes such as title, author, publisher, and ISBN"
+        },
+        {
+            "name_chinese": "班级",
+            "name_english": "Class",
+            "description_chinese": "学生的组织单位，包含班级名称、年级、人数、班主任等属性",
+            "description_english": "Organizational units of students, including attributes such as class name, grade, number of students, and class teacher"
+        },
+        {
+            "name_chinese": "学期",
+            "name_english": "Semester",
+            "description_chinese": "教学时间的划分单位，包含学期名称、开始时间、结束时间等属性",
+            "description_english": "Time division units for teaching, including attributes such as semester name, start time, and end time"
+        },
+        {
+            "name_chinese": "课时",
+            "name_english": "Class Hour",
+            "description_chinese": "课程的时间单位，包含上课时间、地点、教师、课程等属性",
+            "description_english": "Time units of courses, including attributes such as class time, location, teacher, and course"
+        },
+        {
+            "name_chinese": "教学计划",
+            "name_english": "Teaching Plan",
+            "description_chinese": "课程的教学安排，包含教学目标、内容安排、进度计划等属性",
+            "description_english": "Teaching arrangements for courses, including attributes such as teaching objectives, content arrangement, and progress plan"
+        }
+    ]
+}
+
+# 情感陪伴场景配置
+EMOTIONAL_COMPANION_SCENE = {
+    "name_chinese": "情感陪伴",
+    "name_english": "Emotional Companion",
+    "description_chinese": "适用于情感陪伴应用的本体建模，包含用户、情绪、活动等核心实体类型",
+    "description_english": "Ontology modeling for emotional companion applications, including core entity types such as users, emotions, and activities",
+    "types": [
+        {
+            "name_chinese": "用户",
+            "name_english": "User",
+            "description_chinese": "使用情感陪伴服务的个体，包含姓名、昵称、性格特征、偏好等属性",
+            "description_english": "Individuals using emotional companion services, including attributes such as name, nickname, personality traits, and preferences"
+        },
+        {
+            "name_chinese": "情绪",
+            "name_english": "Emotion",
+            "description_chinese": "用户的情感状态，包含情绪类型、强度、触发原因、持续时间等属性",
+            "description_english": "Emotional states of users, including attributes such as emotion type, intensity, trigger cause, and duration"
+        },
+        {
+            "name_chinese": "活动",
+            "name_english": "Activity",
+            "description_chinese": "用户参与的各类活动，包含活动名称、类型、参与者、时间地点等属性",
+            "description_english": "Various activities users participate in, including attributes such as activity name, type, participants, time, and location"
+        },
+        {
+            "name_chinese": "对话",
+            "name_english": "Conversation",
+            "description_chinese": "用户之间的交流记录，包含对话主题、参与者、时间、关键内容等属性",
+            "description_english": "Communication records between users, including attributes such as conversation topic, participants, time, and key content"
+        },
+        {
+            "name_chinese": "兴趣爱好",
+            "name_english": "Hobby",
+            "description_chinese": "用户的兴趣和爱好，包含爱好名称、类别、熟练程度、相关活动等属性",
+            "description_english": "User interests and hobbies, including attributes such as hobby name, category, proficiency level, and related activities"
+        },
+        {
+            "name_chinese": "日常事件",
+            "name_english": "Daily Event",
+            "description_chinese": "用户日常生活中的事件，包含事件描述、时间、地点、相关人物等属性",
+            "description_english": "Events in users' daily lives, including attributes such as event description, time, location, and related people"
+        },
+        {
+            "name_chinese": "关系",
+            "name_english": "Relationship",
+            "description_chinese": "用户之间的社会关系，包含关系类型、亲密度、建立时间等属性",
+            "description_english": "Social relationships between users, including attributes such as relationship type, intimacy, and establishment time"
+        },
+        {
+            "name_chinese": "回忆",
+            "name_english": "Memory",
+            "description_chinese": "用户的重要记忆片段，包含回忆内容、时间、地点、相关人物等属性",
+            "description_english": "Important memory fragments of users, including attributes such as memory content, time, location, and related people"
+        },
+        {
+            "name_chinese": "地点",
+            "name_english": "Location",
+            "description_chinese": "用户活动的地理位置，包含地点名称、地址、类型、相关事件等属性",
+            "description_english": "Geographic locations of user activities, including attributes such as location name, address, type, and related events"
+        },
+        {
+            "name_chinese": "时间节点",
+            "name_english": "Time Point",
+            "description_chinese": "重要的时间标记，包含日期、事件、意义等属性",
+            "description_english": "Important time markers, including attributes such as date, event, and significance"
+        },
+        {
+            "name_chinese": "目标",
+            "name_english": "Goal",
+            "description_chinese": "用户设定的目标，包含目标描述、截止时间、完成状态、相关活动等属性",
+            "description_english": "Goals set by users, including attributes such as goal description, deadline, completion status, and related activities"
+        },
+        {
+            "name_chinese": "成就",
+            "name_english": "Achievement",
+            "description_chinese": "用户获得的成就，包含成就名称、获得时间、描述、相关目标等属性",
+            "description_english": "Achievements obtained by users, including attributes such as achievement name, acquisition time, description, and related goals"
+        }
+    ]
+}
+
+# 导出默认场景列表
+DEFAULT_SCENES = [ONLINE_EDUCATION_SCENE, EMOTIONAL_COMPANION_SCENE]
+
+
+def get_scene_name(scene_config: dict, language: str = "zh") -> str:
+    """获取场景名称（根据语言）
+    
+    Args:
+        scene_config: 场景配置字典
+        language: 语言类型 ("zh" 或 "en")
+        
+    Returns:
+        对应语言的场景名称
+    """
+    if language == "en":
+        return scene_config.get("name_english", scene_config.get("name_chinese"))
+    return scene_config.get("name_chinese")
+
+
+def get_scene_description(scene_config: dict, language: str = "zh") -> str:
+    """获取场景描述（根据语言）
+    
+    Args:
+        scene_config: 场景配置字典
+        language: 语言类型 ("zh" 或 "en")
+        
+    Returns:
+        对应语言的场景描述
+    """
+    if language == "en":
+        return scene_config.get("description_english", scene_config.get("description_chinese"))
+    return scene_config.get("description_chinese")
+
+
+def get_type_name(type_config: dict, language: str = "zh") -> str:
+    """获取类型名称（根据语言）
+    
+    Args:
+        type_config: 类型配置字典
+        language: 语言类型 ("zh" 或 "en")
+        
+    Returns:
+        对应语言的类型名称
+    """
+    if language == "en":
+        return type_config.get("name_english", type_config.get("name_chinese"))
+    return type_config.get("name_chinese")
+
+
+def get_type_description(type_config: dict, language: str = "zh") -> str:
+    """获取类型描述（根据语言）
+    
+    Args:
+        type_config: 类型配置字典
+        language: 语言类型 ("zh" 或 "en")
+        
+    Returns:
+        对应语言的类型描述
+    """
+    if language == "en":
+        return type_config.get("description_english", type_config.get("description_chinese"))
+    return type_config.get("description_chinese")

api/app/config/default_ontology_initializer.py

@@ -0,0 +1,249 @@
+# -*- coding: utf-8 -*-
+"""默认本体场景初始化器
+
+本模块提供默认本体场景和类型的自动初始化功能。
+在工作空间创建时，自动添加预设的本体场景和实体类型。
+
+Classes:
+    DefaultOntologyInitializer: 默认本体场景初始化器
+"""
+
+import logging
+from typing import List, Optional, Tuple
+from uuid import UUID
+
+from sqlalchemy.orm import Session
+
+from app.config.default_ontology_config import (
+    DEFAULT_SCENES,
+    get_scene_name,
+    get_scene_description,
+    get_type_name,
+    get_type_description,
+)
+from app.core.logging_config import get_business_logger
+from app.repositories.ontology_scene_repository import OntologySceneRepository
+from app.repositories.ontology_class_repository import OntologyClassRepository
+
+
+class DefaultOntologyInitializer:
+    """默认本体场景初始化器
+    
+    负责在工作空间创建时自动初始化默认的本体场景和类型。
+    遵循最小侵入原则，确保初始化失败不阻止工作空间创建。
+    
+    Attributes:
+        db: 数据库会话
+        scene_repo: 场景Repository
+        class_repo: 类型Repository
+        logger: 业务日志记录器
+    """
+    
+    def __init__(self, db: Session):
+        """初始化
+        
+        Args:
+            db: 数据库会话
+        """
+        self.db = db
+        self.scene_repo = OntologySceneRepository(db)
+        self.class_repo = OntologyClassRepository(db)
+        self.logger = get_business_logger()
+    
+    def initialize_default_scenes(
+        self,
+        workspace_id: UUID,
+        language: str = "zh"
+    ) -> Tuple[bool, str]:
+        """为工作空间初始化默认场景
+        
+        创建两个默认场景（在线教育、情感陪伴）及其对应的实体类型。
+        如果创建失败，记录错误日志但不抛出异常。
+        
+        Args:
+            workspace_id: 工作空间ID
+            language: 语言类型 ("zh" 或 "en")，默认为 "zh"
+            
+        Returns:
+            Tuple[bool, str]: (是否成功, 错误信息)
+        """
+        try:
+            self.logger.info(
+                f"开始初始化默认本体场景 - workspace_id={workspace_id}, language={language}"
+            )
+            
+            scenes_created = 0
+            total_types_created = 0
+            
+            # 遍历默认场景配置
+            for scene_config in DEFAULT_SCENES:
+                scene_name = get_scene_name(scene_config, language)
+                
+                # 创建场景及其类型
+                scene_id = self._create_scene_with_types(workspace_id, scene_config, language)
+                
+                if scene_id:
+                    scenes_created += 1
+                    # 统计类型数量
+                    types_count = len(scene_config.get("types", []))
+                    total_types_created += types_count
+                    
+                    self.logger.info(
+                        f"场景创建成功 - scene_name={scene_name}, "
+                        f"scene_id={scene_id}, types_count={types_count}, language={language}"
+                    )
+                else:
+                    self.logger.warning(
+                        f"场景创建失败 - scene_name={scene_name}, "
+                        f"workspace_id={workspace_id}, language={language}"
+                    )
+            
+            # 记录总体结果
+            self.logger.info(
+                f"默认场景初始化完成 - workspace_id={workspace_id}, "
+                f"language={language}, scenes_created={scenes_created}, "
+                f"total_types_created={total_types_created}"
+            )
+            
+            # 如果至少创建了一个场景，视为成功
+            if scenes_created > 0:
+                return True, ""
+            else:
+                error_msg = "所有默认场景创建失败"
+                self.logger.error(
+                    f"默认场景初始化失败 - workspace_id={workspace_id}, "
+                    f"language={language}, error={error_msg}"
+                )
+                return False, error_msg
+                
+        except Exception as e:
+            error_msg = f"默认场景初始化异常: {str(e)}"
+            self.logger.error(
+                f"默认场景初始化异常 - workspace_id={workspace_id}, "
+                f"language={language}, error={str(e)}",
+                exc_info=True
+            )
+            return False, error_msg
+    
+    def _create_scene_with_types(
+        self,
+        workspace_id: UUID,
+        scene_config: dict,
+        language: str = "zh"
+    ) -> Optional[UUID]:
+        """创建场景及其类型
+        
+        Args:
+            workspace_id: 工作空间ID
+            scene_config: 场景配置字典
+            language: 语言类型 ("zh" 或 "en")
+            
+        Returns:
+            Optional[UUID]: 创建的场景ID，失败返回None
+        """
+        try:
+            scene_name = get_scene_name(scene_config, language)
+            scene_description = get_scene_description(scene_config, language)
+            
+            # 检查是否已存在同名场景（支持向后兼容）
+            existing_scene = self.scene_repo.get_by_name(scene_name, workspace_id)
+            if existing_scene:
+                self.logger.info(
+                    f"场景已存在，跳过创建 - scene_name={scene_name}, "
+                    f"workspace_id={workspace_id}, scene_id={existing_scene.scene_id}, "
+                    f"language={language}"
+                )
+                return None
+            
+            # 创建场景记录，设置 is_system_default=true
+            scene_data = {
+                "scene_name": scene_name,
+                "scene_description": scene_description
+            }
+            
+            scene = self.scene_repo.create(scene_data, workspace_id)
+            
+            # 设置系统默认标识
+            scene.is_system_default = True
+            self.db.flush()
+            
+            self.logger.info(
+                f"场景创建成功 - scene_name={scene_name}, "
+                f"scene_id={scene.scene_id}, is_system_default=True, language={language}"
+            )
+            
+            # 批量创建类型
+            types_config = scene_config.get("types", [])
+            types_created = self._batch_create_types(scene.scene_id, types_config, language)
+            
+            self.logger.info(
+                f"场景类型创建完成 - scene_id={scene.scene_id}, "
+                f"types_created={types_created}/{len(types_config)}, language={language}"
+            )
+            
+            return scene.scene_id
+            
+        except Exception as e:
+            scene_name = get_scene_name(scene_config, language)
+            self.logger.error(
+                f"场景创建失败 - scene_name={scene_name}, "
+                f"workspace_id={workspace_id}, language={language}, error={str(e)}",
+                exc_info=True
+            )
+            return None
+    
+    def _batch_create_types(
+        self,
+        scene_id: UUID,
+        types_config: List[dict],
+        language: str = "zh"
+    ) -> int:
+        """批量创建实体类型
+        
+        Args:
+            scene_id: 场景ID
+            types_config: 类型配置列表
+            language: 语言类型 ("zh" 或 "en")
+            
+        Returns:
+            int: 成功创建的类型数量
+        """
+        created_count = 0
+        
+        for type_config in types_config:
+            try:
+                type_name = get_type_name(type_config, language)
+                type_description = get_type_description(type_config, language)
+                
+                # 创建类型数据
+                class_data = {
+                    "class_name": type_name,
+                    "class_description": type_description
+                }
+                
+                # 创建类型
+                ontology_class = self.class_repo.create(class_data, scene_id)
+                
+                # 设置系统默认标识
+                ontology_class.is_system_default = True
+                self.db.flush()
+                
+                created_count += 1
+                
+                self.logger.debug(
+                    f"类型创建成功 - class_name={type_name}, "
+                    f"class_id={ontology_class.class_id}, "
+                    f"scene_id={scene_id}, is_system_default=True, language={language}"
+                )
+                
+            except Exception as e:
+                type_name = get_type_name(type_config, language)
+                self.logger.warning(
+                    f"单个类型创建失败，继续创建其他类型 - "
+                    f"class_name={type_name}, scene_id={scene_id}, "
+                    f"language={language}, error={str(e)}"
+                )
+                # 继续创建其他类型
+                continue
+        
+        return created_count

api/app/controllers/__init__.py

@@ -8,6 +8,7 @@ from fastapi import APIRouter
 from . import (
     api_key_controller,
     app_controller,
+    app_log_controller,
     auth_controller,
     chunk_controller,
     document_controller,
@@ -16,6 +17,7 @@ from . import (
     file_controller,
     file_storage_controller,
     home_page_controller,
+    i18n_controller,
     implicit_memory_controller,
     knowledge_controller,
     knowledgeshare_controller,
@@ -45,7 +47,8 @@ from . import (
     user_memory_controllers,
     workspace_controller,
     ontology_controller,
-    skill_controller
+    skill_controller,
+    tenant_subscription_controller,
 )
 
 # 创建管理端 API 路由器
@@ -68,6 +71,7 @@ manager_router.include_router(chunk_controller.router)
 manager_router.include_router(test_controller.router)
 manager_router.include_router(knowledgeshare_controller.router)
 manager_router.include_router(app_controller.router)
+manager_router.include_router(app_log_controller.router)
 manager_router.include_router(upload_controller.router)
 manager_router.include_router(memory_agent_controller.router)
 manager_router.include_router(memory_dashboard_controller.router)
@@ -94,5 +98,8 @@ manager_router.include_router(memory_working_controller.router)
 manager_router.include_router(file_storage_controller.router)
 manager_router.include_router(ontology_controller.router)
 manager_router.include_router(skill_controller.router)
+manager_router.include_router(i18n_controller.router)
+manager_router.include_router(tenant_subscription_controller.router)
+manager_router.include_router(tenant_subscription_controller.public_router)
 
 __all__ = ["manager_router"]

api/app/controllers/api_key_controller.py

@@ -167,6 +167,8 @@ def update_api_key(
 
         return success(data=api_key_schema.ApiKey.model_validate(api_key), msg="API Key 更新成功")
 
+    except BusinessException:
+        raise
     except Exception as e:
         logger.error(f"未知错误: {str(e)}", extra={
             "api_key_id": str(api_key_id),

api/app/controllers/app_controller.py

@@ -1,9 +1,13 @@
 import uuid
+import io
+import json
 from typing import Optional, Annotated
 
-from fastapi import APIRouter, Depends, Path
+import yaml
+from fastapi import APIRouter, Depends, Path, Form, UploadFile, File
 from fastapi.responses import StreamingResponse
 from sqlalchemy.orm import Session
+from urllib.parse import quote
 
 from app.core.error_codes import BizCode
 from app.core.logging_config import get_business_logger
@@ -17,12 +21,15 @@ from app.repositories.end_user_repository import EndUserRepository
 from app.schemas import app_schema
 from app.schemas.response_schema import PageData, PageMeta
 from app.schemas.workflow_schema import WorkflowConfig as WorkflowConfigSchema
-from app.schemas.workflow_schema import WorkflowConfigUpdate
+from app.schemas.workflow_schema import WorkflowConfigUpdate, WorkflowImportSave
 from app.services import app_service, workspace_service
 from app.services.agent_config_helper import enrich_agent_config
 from app.services.app_service import AppService
-from app.services.workflow_service import WorkflowService, get_workflow_service
 from app.services.app_statistics_service import AppStatisticsService
+from app.services.workflow_import_service import WorkflowImportService
+from app.services.workflow_service import WorkflowService, get_workflow_service
+from app.services.app_dsl_service import AppDslService
+from app.core.quota_stub import check_app_quota
 
 router = APIRouter(prefix="/apps", tags=["Apps"])
 logger = get_business_logger()
@@ -30,6 +37,7 @@ logger = get_business_logger()
 
 @router.post("", summary="创建应用（可选创建 Agent 配置）")
 @cur_workspace_access_guard()
+@check_app_quota
 def create_app(
         payload: app_schema.AppCreate,
         db: Session = Depends(get_db),
@@ -48,6 +56,7 @@ def list_apps(
         status: str | None = None,
         search: str | None = None,
         include_shared: bool = True,
+        shared_only: bool = False,
         page: int = 1,
         pagesize: int = 10,
         ids: Optional[str] = None,
@@ -59,16 +68,42 @@ def list_apps(
     - 默认包含本工作空间的应用和分享给本工作空间的应用
     - 设置 include_shared=false 可以只查看本工作空间的应用
     - 当提供 ids 参数时，按逗号分割获取指定应用，不分页
+    - search 参数支持：应用名称模糊搜索、API Key 精确搜索
     """
+    from sqlalchemy import select as sa_select
+    from app.models.api_key_model import ApiKey
+
     workspace_id = current_user.current_workspace_id
     service = app_service.AppService(db)
 
-    # 当 ids 存在且不为 None 时，根据 ids 获取应用
+    # 通过 search 参数搜索：支持应用名称模糊搜索和 API Key 精确搜索
+    if search:
+        search = search.strip()
+        # 尝试作为 API Key 精确匹配（API Key 通常较长）
+        if len(search) >= 10:
+            matched_id = db.execute(
+                sa_select(ApiKey.resource_id).where(
+                    ApiKey.workspace_id == workspace_id,
+                    ApiKey.api_key == search,
+                    ApiKey.resource_id.isnot(None),
+                )
+            ).scalar_one_or_none()
+            if matched_id:
+                # 找到 API Key，直接返回关联的应用
+                ids = str(matched_id)
+
+    # 当 ids 存在时，根据 ids 获取应用（不分页）
     if ids is not None:
-        app_ids = [id.strip() for id in ids.split(',') if id.strip()]
-        items_orm = app_service.get_apps_by_ids(db, app_ids, workspace_id)
-        items = [service._convert_to_schema(app, workspace_id) for app in items_orm]
-        return success(data=items)
+        app_ids = [app_id.strip() for app_id in ids.split(',') if app_id.strip()]
+        if app_ids:
+            items_orm = app_service.get_apps_by_ids(db, app_ids, workspace_id)
+            items = [service._convert_to_schema(app, workspace_id) for app in items_orm]
+            # 返回标准分页格式
+            meta = PageMeta(page=1, pagesize=len(items), total=len(items), hasnext=False)
+            return success(data=PageData(page=meta, items=items))
+        # ids 为空时，返回空列表
+        meta = PageMeta(page=1, pagesize=0, total=0, hasnext=False)
+        return success(data=PageData(page=meta, items=[]))
 
     # 正常分页查询
     items_orm, total = app_service.list_apps(
@@ -79,6 +114,7 @@ def list_apps(
         status=status,
         search=search,
         include_shared=include_shared,
+        shared_only=shared_only,
         page=page,
         pagesize=pagesize,
     )
@@ -88,6 +124,37 @@ def list_apps(
     return success(data=PageData(page=meta, items=items))
 
 
+@router.get("/my-shared-out", summary="列出本工作空间主动分享出去的记录")
+@cur_workspace_access_guard()
+def list_my_shared_out(
+        db: Session = Depends(get_db),
+        current_user=Depends(get_current_user),
+):
+    """列出本工作空间主动分享给其他工作空间的所有记录（我的共享）"""
+    workspace_id = current_user.current_workspace_id
+    service = app_service.AppService(db)
+    shares = service.list_my_shared_out(workspace_id=workspace_id)
+    data = [app_schema.AppShare.model_validate(s) for s in shares]
+    return success(data=data)
+
+
+@router.delete("/share/{target_workspace_id}", summary="取消对某工作空间的所有应用分享")
+@cur_workspace_access_guard()
+def unshare_all_apps_to_workspace(
+        target_workspace_id: uuid.UUID,
+        db: Session = Depends(get_db),
+        current_user=Depends(get_current_user),
+):
+    """Cancel all app shares from current workspace to a target workspace."""
+    workspace_id = current_user.current_workspace_id
+    service = app_service.AppService(db)
+    count = service.unshare_all_apps_to_workspace(
+        target_workspace_id=target_workspace_id,
+        workspace_id=workspace_id
+    )
+    return success(msg=f"已取消 {count} 个应用的分享", data={"count": count})
+
+
 @router.get("/{app_id}", summary="获取应用详情")
 @cur_workspace_access_guard()
 def get_app(
@@ -153,9 +220,11 @@ def delete_app(
 
 @router.post("/{app_id}/copy", summary="复制应用")
 @cur_workspace_access_guard()
+@check_app_quota
 def copy_app(
         app_id: uuid.UUID,
         new_name: Optional[str] = None,
+        payload: app_schema.CopyAppRequest = None,
         db: Session = Depends(get_db),
         current_user=Depends(get_current_user),
 ):
@@ -167,6 +236,8 @@ def copy_app(
     - 不影响原应用
     """
     workspace_id = current_user.current_workspace_id
+    # body takes precedence over query param for backward compatibility
+    new_name = (payload.new_name if payload else None) or new_name
     logger.info(
         "用户请求复制应用",
         extra={
@@ -202,6 +273,19 @@ def update_agent_config(
     return success(data=app_schema.AgentConfig.model_validate(cfg))
 
 
+@router.get("/{app_id}/model/parameters/default", summary="获取 Agent 模型参数默认配置")
+@cur_workspace_access_guard()
+def get_agent_model_parameters(
+        app_id: uuid.UUID,
+        db: Session = Depends(get_db),
+        current_user=Depends(get_current_user),
+):
+    workspace_id = current_user.current_workspace_id
+    service = AppService(db)
+    model_parameters = service.get_default_model_parameters(app_id=app_id)
+    return success(data=model_parameters, msg="获取 Agent 模型参数默认配置")
+
+
 @router.get("/{app_id}/config", summary="获取 Agent 配置")
 @cur_workspace_access_guard()
 def get_agent_config(
@@ -216,6 +300,36 @@ def get_agent_config(
     return success(data=app_schema.AgentConfig.model_validate(cfg))
 
 
+@router.get("/{app_id}/opening", summary="获取应用开场白配置")
+@cur_workspace_access_guard()
+def get_opening(
+        app_id: uuid.UUID,
+        db: Session = Depends(get_db),
+        current_user=Depends(get_current_user),
+):
+    """返回开场白文本和预设问题，供前端对话界面初始化时展示"""
+    workspace_id = current_user.current_workspace_id
+
+    # 根据应用类型获取 features
+    from app.models.app_model import App as AppModel
+    app = db.get(AppModel, app_id)
+    if app and app.type == "workflow":
+        cfg = app_service.get_workflow_config(db=db, app_id=app_id, workspace_id=workspace_id)
+        features = cfg.features or {}
+    else:
+        cfg = app_service.get_agent_config(db, app_id=app_id, workspace_id=workspace_id)
+        features = cfg.features or {}
+        if hasattr(features, "model_dump"):
+            features = features.model_dump()
+
+    opening = features.get("opening_statement", {})
+    return success(data=app_schema.OpeningResponse(
+        enabled=opening.get("enabled", False),
+        statement=opening.get("statement"),
+        suggested_questions=opening.get("suggested_questions", []),
+    ))
+
+
 @router.post("/{app_id}/publish", summary="发布应用（生成不可变快照）")
 @cur_workspace_access_guard()
 def publish_app(
@@ -297,7 +411,8 @@ def share_app(
         app_id=app_id,
         target_workspace_ids=payload.target_workspace_ids,
         user_id=current_user.id,
-        workspace_id=workspace_id
+        workspace_id=workspace_id,
+        permission=payload.permission
     )
 
     data = [app_schema.AppShare.model_validate(s) for s in shares]
@@ -328,6 +443,32 @@ def unshare_app(
     return success(msg="应用分享已取消")
 
 
+@router.patch("/{app_id}/share/{target_workspace_id}", summary="更新共享权限")
+@cur_workspace_access_guard()
+def update_share_permission(
+        app_id: uuid.UUID,
+        target_workspace_id: uuid.UUID,
+        payload: app_schema.UpdateSharePermissionRequest,
+        db: Session = Depends(get_db),
+        current_user=Depends(get_current_user),
+):
+    """更新共享权限（readonly <-> editable）
+
+    - 只能修改自己工作空间应用的共享权限
+    """
+    workspace_id = current_user.current_workspace_id
+
+    service = app_service.AppService(db)
+    share = service.update_share_permission(
+        app_id=app_id,
+        target_workspace_id=target_workspace_id,
+        permission=payload.permission,
+        workspace_id=workspace_id
+    )
+
+    return success(data=app_schema.AppShare.model_validate(share))
+
+
 @router.get("/{app_id}/shares", summary="列出应用的分享记录")
 @cur_workspace_access_guard()
 def list_app_shares(
@@ -351,6 +492,46 @@ def list_app_shares(
     return success(data=data)
 
 
+@router.delete("/shared/{source_workspace_id}", summary="批量移除某来源工作空间的所有共享应用")
+@cur_workspace_access_guard()
+def remove_all_shared_apps_from_workspace(
+        source_workspace_id: uuid.UUID,
+        db: Session = Depends(get_db),
+        current_user=Depends(get_current_user),
+):
+    """Remove all shared apps from a specific source workspace (recipient operation)."""
+    workspace_id = current_user.current_workspace_id
+    service = app_service.AppService(db)
+    count = service.remove_all_shared_apps_from_workspace(
+        source_workspace_id=source_workspace_id,
+        workspace_id=workspace_id
+    )
+    return success(msg=f"已移除 {count} 个共享应用", data={"count": count})
+
+
+@router.delete("/{app_id}/shared", summary="移除共享给我的应用")
+@cur_workspace_access_guard()
+def remove_shared_app(
+        app_id: uuid.UUID,
+        db: Session = Depends(get_db),
+        current_user=Depends(get_current_user),
+):
+    """被共享者从自己的工作空间移除共享应用
+
+    - 不会删除源应用，只删除共享记录
+    - 只能移除共享给自己工作空间的应用
+    """
+    workspace_id = current_user.current_workspace_id
+
+    service = app_service.AppService(db)
+    service.remove_shared_app(
+        app_id=app_id,
+        workspace_id=workspace_id
+    )
+
+    return success(msg="已移除共享应用")
+
+
 @router.post("/{app_id}/draft/run", summary="试运行 Agent（使用当前草稿配置）")
 @cur_workspace_access_guard()
 async def draft_run(
@@ -391,13 +572,13 @@ async def draft_run(
     # 提前验证和准备（在流式响应开始前完成）
     from app.services.app_service import AppService
     from app.services.multi_agent_service import MultiAgentService
-    from app.models import AgentConfig, ModelConfig
+    from app.models import AgentConfig, ModelConfig, AppRelease
     from sqlalchemy import select
     from app.core.exceptions import BusinessException
-    from app.services.draft_run_service import DraftRunService
+    from app.services.draft_run_service import AgentRunService
 
     service = AppService(db)
-    draft_service = DraftRunService(db)
+    draft_service = AgentRunService(db)
 
     # 1. 验证应用
     app = service._get_app_or_404(app_id)
@@ -408,11 +589,12 @@ async def draft_run(
     service._validate_app_accessible(app, workspace_id)
 
     if payload.user_id is None:
+        # 先获取 app 的 workspace_id
         end_user_repo = EndUserRepository(db)
         new_end_user = end_user_repo.get_or_create_end_user(
             app_id=app_id,
+            workspace_id=app.workspace_id,
             other_id=str(current_user.id),
-            original_user_id=str(current_user.id)  # Save original user_id to other_id
         )
         payload.user_id = str(new_end_user.id)
 
@@ -429,18 +611,29 @@ async def draft_run(
         service._check_agent_config(app_id)
 
         # 2. 获取 Agent 配置
-        stmt = select(AgentConfig).where(AgentConfig.app_id == app_id)
-        agent_cfg = db.scalars(stmt).first()
-        if not agent_cfg:
-            raise BusinessException("Agent 配置不存在", BizCode.AGENT_CONFIG_MISSING)
+        # 共享应用：从最新发布版本读配置快照，而非草稿
+        is_shared = app.workspace_id != workspace_id
+        if is_shared:
+            if not app.current_release_id:
+                raise BusinessException("该应用尚未发布，无法使用", BizCode.AGENT_CONFIG_MISSING)
+            release = db.get(AppRelease, app.current_release_id)
+            if not release:
+                raise BusinessException("发布版本不存在", BizCode.AGENT_CONFIG_MISSING)
+            agent_cfg = service._agent_config_from_release(release)
+            model_config = db.get(ModelConfig, release.default_model_config_id) if release.default_model_config_id else None
+        else:
+            stmt = select(AgentConfig).where(AgentConfig.app_id == app_id)
+            agent_cfg = db.scalars(stmt).first()
+            if not agent_cfg:
+                raise BusinessException("Agent 配置不存在", BizCode.AGENT_CONFIG_MISSING)
 
-        # 3. 获取模型配置
-        model_config = None
-        if agent_cfg.default_model_config_id:
-            model_config = db.get(ModelConfig, agent_cfg.default_model_config_id)
-            if not model_config:
-                from app.core.exceptions import ResourceNotFoundException
-                raise ResourceNotFoundException("模型配置", str(agent_cfg.default_model_config_id))
+            # 3. 获取模型配置
+            model_config = None
+            if agent_cfg.default_model_config_id:
+                model_config = db.get(ModelConfig, agent_cfg.default_model_config_id)
+                if not model_config:
+                    from app.core.exceptions import ResourceNotFoundException
+                    raise ResourceNotFoundException("模型配置", str(agent_cfg.default_model_config_id))
 
         # 流式返回
         if payload.stream:
@@ -482,8 +675,8 @@ async def draft_run(
             }
         )
 
-        from app.services.draft_run_service import DraftRunService
-        draft_service = DraftRunService(db)
+        from app.services.draft_run_service import AgentRunService
+        draft_service = AgentRunService(db)
         result = await draft_service.run(
             agent_config=agent_cfg,
             model_config=model_config,
@@ -596,7 +789,17 @@ async def draft_run(
             msg="多 Agent 任务执行成功"
         )
     elif app.type == AppType.WORKFLOW:  # 工作流
-        config = workflow_service.check_config(app_id)
+        # 共享应用：从最新发布版本读配置快照，而非草稿
+        is_shared = app.workspace_id != workspace_id
+        if is_shared:
+            if not app.current_release_id:
+                raise BusinessException("该应用尚未发布，无法使用", BizCode.AGENT_CONFIG_MISSING)
+            release = db.get(AppRelease, app.current_release_id)
+            if not release:
+                raise BusinessException("发布版本不存在", BizCode.AGENT_CONFIG_MISSING)
+            config = service._workflow_config_from_release(release)
+        else:
+            config = workflow_service.check_config(app_id)
         # 3. 流式返回
         if payload.stream:
             logger.debug(
@@ -739,6 +942,16 @@ async def draft_run_compare(
         raise BusinessException("只有 Agent 类型应用支持试运行", BizCode.APP_TYPE_NOT_SUPPORTED)
     service._validate_app_accessible(app, workspace_id)
 
+    if payload.user_id is None:
+        # 先获取 app 的 workspace_id
+        end_user_repo = EndUserRepository(db)
+        new_end_user = end_user_repo.get_or_create_end_user(
+            app_id=app_id,
+            workspace_id=app.workspace_id,
+            other_id=str(current_user.id),
+        )
+        payload.user_id = str(new_end_user.id)
+
     # 2. 获取 Agent 配置
     from sqlalchemy import select
     from app.models import AgentConfig
@@ -784,22 +997,29 @@ async def draft_run_compare(
             "conversation_id": model_item.conversation_id  # 传递每个模型的 conversation_id
         })
 
+    # 从 features 中读取功能开关（与 draft_run 保持一致）
+    features_config: dict = agent_cfg.features or {}
+    if hasattr(features_config, 'model_dump'):
+        features_config = features_config.model_dump()
+    web_search_feature = features_config.get("web_search", {})
+    web_search = isinstance(web_search_feature, dict) and web_search_feature.get("enabled", False)
+
     # 流式返回
     if payload.stream:
         async def event_generator():
-            from app.services.draft_run_service import DraftRunService
-            draft_service = DraftRunService(db)
+            from app.services.draft_run_service import AgentRunService
+            draft_service = AgentRunService(db)
             async for event in draft_service.run_compare_stream(
                     agent_config=agent_cfg,
                     models=model_configs,
                     message=payload.message,
                     workspace_id=workspace_id,
                     conversation_id=payload.conversation_id,
-                    user_id=payload.user_id or str(current_user.id),
+                    user_id=payload.user_id,
                     variables=payload.variables,
                     storage_type=storage_type,
                     user_rag_memory_id=user_rag_memory_id,
-                    web_search=True,
+                    web_search=web_search,
                     memory=True,
                     parallel=payload.parallel,
                     timeout=payload.timeout or 60,
@@ -818,22 +1038,23 @@ async def draft_run_compare(
         )
 
     # 非流式返回
-    from app.services.draft_run_service import DraftRunService
-    draft_service = DraftRunService(db)
+    from app.services.draft_run_service import AgentRunService
+    draft_service = AgentRunService(db)
     result = await draft_service.run_compare(
         agent_config=agent_cfg,
         models=model_configs,
         message=payload.message,
         workspace_id=workspace_id,
         conversation_id=payload.conversation_id,
-        user_id=payload.user_id or str(current_user.id),
+        user_id=payload.user_id,
         variables=payload.variables,
         storage_type=storage_type,
         user_rag_memory_id=user_rag_memory_id,
-        web_search=True,
+        web_search=web_search,
         memory=True,
         parallel=payload.parallel,
-        timeout=payload.timeout or 60
+        timeout=payload.timeout or 60,
+        files=payload.files
     )
 
     logger.info(
@@ -848,6 +1069,62 @@ async def draft_run_compare(
     return success(data=app_schema.DraftRunCompareResponse(**result))
 
 
+@router.post("/{app_id}/workflow/nodes/{node_id}/run", summary="单节点试运行")
+@cur_workspace_access_guard()
+async def run_single_workflow_node(
+        app_id: uuid.UUID,
+        node_id: str,
+        payload: app_schema.NodeRunRequest,
+        db: Annotated[Session, Depends(get_db)],
+        current_user: Annotated[User, Depends(get_current_user)],
+        workflow_service: Annotated[WorkflowService, Depends(get_workflow_service)] = None,
+):
+    """单独执行工作流中的某个节点
+
+    inputs 支持以下 key 格式:
+    - 节点变量: "node_id.var_name"
+    - 系统变量: "sys.message"、"sys.files"
+    """
+    workspace_id = current_user.current_workspace_id
+    config = workflow_service.check_config(app_id)
+
+    raw_inputs = payload.inputs or {}
+    input_data = {
+        "message": raw_inputs.pop("sys.message", ""),
+        "files": raw_inputs.pop("sys.files", []),
+        "user_id": raw_inputs.pop("sys.user_id", str(current_user.id)),
+        "inputs": raw_inputs,
+        "conversation_id": "",
+        "conv_messages": [],
+    }
+
+    if payload.stream:
+        async def event_generator():
+            async for event in workflow_service.run_single_node_stream(
+                    app_id=app_id,
+                    node_id=node_id,
+                    config=config,
+                    workspace_id=workspace_id,
+                    input_data=input_data,
+            ):
+                yield f"event: {event['event']}\ndata: {json.dumps(event['data'], ensure_ascii=False)}\n\n"
+
+        return StreamingResponse(
+            event_generator(),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "Connection": "keep-alive", "X-Accel-Buffering": "no"}
+        )
+
+    result = await workflow_service.run_single_node(
+        app_id=app_id,
+        node_id=node_id,
+        config=config,
+        workspace_id=workspace_id,
+        input_data=input_data,
+    )
+    return success(data=result)
+
+
 @router.get("/{app_id}/workflow")
 @cur_workspace_access_guard()
 async def get_workflow_config(
@@ -875,10 +1152,73 @@ async def update_workflow_config(
         current_user: Annotated[User, Depends(get_current_user)]
 ):
     workspace_id = current_user.current_workspace_id
+    if payload.variables:
+        from app.services.workflow_service import WorkflowService
+        resolved = await WorkflowService(db)._resolve_variables_file_defaults(
+            [v.model_dump() for v in payload.variables]
+        )
+        # Patch default values back into VariableDefinition objects
+        for var_def, resolved_def in zip(payload.variables, resolved):
+            var_def.default = resolved_def.get("default", var_def.default)
     cfg = app_service.update_workflow_config(db, app_id=app_id, data=payload, workspace_id=workspace_id)
     return success(data=WorkflowConfigSchema.model_validate(cfg))
 
 
+@router.get("/{app_id}/workflow/export")
+@cur_workspace_access_guard()
+async def export_workflow_config(
+        app_id: uuid.UUID,
+        db: Annotated[Session, Depends(get_db)],
+        current_user: Annotated[User, Depends(get_current_user)]
+):
+    """导出工作流配置为YAML文件"""
+    workflow_service = WorkflowService(db)
+
+    return success(data={
+        "content": workflow_service.export_workflow_dsl(app_id=app_id),
+    })
+
+
+@router.post("/workflow/import")
+@cur_workspace_access_guard()
+async def import_workflow_config(
+        file: UploadFile = File(...),
+        platform: str = Form(...),
+        app_id: str = Form(None),
+        db: Session = Depends(get_db),
+        current_user: User = Depends(get_current_user)
+
+):
+    """从YAML内容导入工作流配置"""
+    if not file.filename.lower().endswith((".yaml", ".yml")):
+        return fail(msg="Only yaml file is allowed", code=BizCode.BAD_REQUEST)
+
+    raw_text = (await file.read()).decode("utf-8")
+    import_service = WorkflowImportService(db)
+    config = yaml.safe_load(raw_text)
+    result = await import_service.upload_config(platform, config)
+    return success(data=result)
+
+
+@router.post("/workflow/import/save")
+@cur_workspace_access_guard()
+@check_app_quota
+async def save_workflow_import(
+        data: WorkflowImportSave,
+        db: Session = Depends(get_db),
+        current_user: User = Depends(get_current_user)
+):
+    import_service = WorkflowImportService(db)
+    app = await import_service.save_workflow(
+        user_id=current_user.id,
+        workspace_id=current_user.current_workspace_id,
+        temp_id=data.temp_id,
+        name=data.name,
+        description=data.description,
+    )
+    return success(data=app_schema.App.model_validate(app))
+
+
 @router.get("/{app_id}/statistics", summary="应用统计数据")
 @cur_workspace_access_guard()
 def get_app_statistics(
@@ -889,12 +1229,14 @@ def get_app_statistics(
         current_user=Depends(get_current_user),
 ):
     """获取应用统计数据
-    
+
     Args:
         app_id: 应用ID
         start_date: 开始时间戳（毫秒）
         end_date: 结束时间戳（毫秒）
-    
+        db: 数据库连接
+        current_user: 当前用户
+
     Returns:
         - daily_conversations: 每日会话数统计
         - total_conversations: 总会话数
@@ -931,6 +1273,8 @@ def get_workspace_api_statistics(
     Args:
         start_date: 开始时间戳（毫秒）
         end_date: 结束时间戳（毫秒）
+        db: 数据库连接
+        current_user: 当前用户
     
     Returns:
         每日统计数据列表，每项包含：
@@ -949,3 +1293,108 @@ def get_workspace_api_statistics(
     )
 
     return success(data=result)
+
+
+@router.get("/{app_id}/export", summary="导出应用配置为 YAML 文件")
+@cur_workspace_access_guard()
+async def export_app(
+        app_id: uuid.UUID,
+        db: Annotated[Session, Depends(get_db)],
+        current_user: Annotated[User, Depends(get_current_user)],
+        release_id: Optional[uuid.UUID] = None
+):
+    """导出 agent / multi_agent / workflow 应用配置为 YAML 文件流。
+    release_id: 指定发布版本id，不传则导出当前草稿配置。
+    """
+    yaml_str, filename = AppDslService(db).export_dsl(app_id, release_id)
+    encoded = quote(filename, safe=".")
+    yaml_bytes = yaml_str.encode("utf-8")
+    file_stream = io.BytesIO(yaml_bytes)
+    file_stream.seek(0)
+    return StreamingResponse(
+        file_stream,
+        media_type="application/octet-stream; charset=utf-8",
+        headers={"Content-Disposition": f"attachment; filename={encoded}",
+                 "Content-Length": str(len(yaml_bytes))}
+    )
+
+
+@router.post("/import", summary="从 YAML 文件导入应用")
+@cur_workspace_access_guard()
+async def import_app(
+        file: UploadFile = File(...),
+        db: Session = Depends(get_db),
+        current_user: User = Depends(get_current_user),
+        app_id: Optional[str] = Form(None),
+):
+    """从 YAML 文件导入 agent / multi_agent / workflow 应用。
+    传入 app_id 时覆盖该应用的配置（类型必须一致），否则创建新应用。
+    跨空间/跨租户导入时，模型/工具/知识库会按名称匹配，匹配不到则置空并返回 warnings。
+    """
+    if not file.filename.lower().endswith((".yaml", ".yml")):
+        return fail(msg="仅支持 YAML 文件", code=BizCode.BAD_REQUEST)
+
+    raw = (await file.read()).decode("utf-8")
+    dsl = yaml.safe_load(raw)
+    if not dsl or "app" not in dsl:
+        return fail(msg="YAML 格式无效，缺少 app 字段", code=BizCode.BAD_REQUEST)
+
+    target_app_id = uuid.UUID(app_id) if app_id else None
+    # 仅新建应用时检查配额，覆盖已有应用时跳过
+    if target_app_id is None:
+        from app.core.quota_manager import _check_quota
+        _check_quota(db, current_user.tenant_id, "app_quota", "app", workspace_id=current_user.current_workspace_id)
+    result_app, warnings = AppDslService(db).import_dsl(
+        dsl=dsl,
+        workspace_id=current_user.current_workspace_id,
+        tenant_id=current_user.tenant_id,
+        user_id=current_user.id,
+        app_id=target_app_id,
+    )
+    return success(
+        data={"app": app_schema.App.model_validate(result_app), "warnings": warnings},
+        msg="应用导入成功" + ("，但部分资源需手动配置" if warnings else "")
+    )
+
+
+@router.get("/citations/{document_id}/download", summary="下载引用文档原始文件")
+async def download_citation_file(
+        document_id: uuid.UUID = Path(..., description="引用文档ID"),
+        db: Session = Depends(get_db),
+):
+    """
+    下载引用文档的原始文件。
+    仅当应用功能特性 citation.allow_download=true 时，前端才会展示此下载链接。
+    路由本身不做权限校验，由业务层通过 allow_download 开关控制入口。
+    """
+    import os
+    from fastapi import HTTPException, status as http_status
+    from fastapi.responses import FileResponse
+    from app.core.config import settings
+    from app.models.document_model import Document
+    from app.models.file_model import File as FileModel
+
+    doc = db.query(Document).filter(Document.id == document_id).first()
+    if not doc:
+        raise HTTPException(status_code=http_status.HTTP_404_NOT_FOUND, detail="文档不存在")
+
+    file_record = db.query(FileModel).filter(FileModel.id == doc.file_id).first()
+    if not file_record:
+        raise HTTPException(status_code=http_status.HTTP_404_NOT_FOUND, detail="原始文件不存在")
+
+    file_path = os.path.join(
+        settings.FILE_PATH,
+        str(file_record.kb_id),
+        str(file_record.parent_id),
+        f"{file_record.id}{file_record.file_ext}"
+    )
+    if not os.path.exists(file_path):
+        raise HTTPException(status_code=http_status.HTTP_404_NOT_FOUND, detail="文件未找到")
+
+    encoded_name = quote(doc.file_name)
+    return FileResponse(
+        path=file_path,
+        filename=doc.file_name,
+        media_type="application/octet-stream",
+        headers={"Content-Disposition": f"attachment; filename*=UTF-8''{encoded_name}"}
+    )

api/app/controllers/app_log_controller.py

@@ -0,0 +1,110 @@
+"""应用日志（消息记录）接口"""
+import uuid
+from typing import Optional
+
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.orm import Session
+
+from app.core.logging_config import get_business_logger
+from app.core.response_utils import success
+from app.db import get_db
+from app.dependencies import get_current_user, cur_workspace_access_guard
+from app.schemas.app_log_schema import AppLogConversation, AppLogConversationDetail, AppLogMessage
+from app.schemas.response_schema import PageData, PageMeta
+from app.services.app_service import AppService
+from app.services.app_log_service import AppLogService
+
+router = APIRouter(prefix="/apps", tags=["App Logs"])
+logger = get_business_logger()
+
+
+@router.get("/{app_id}/logs", summary="应用日志 - 会话列表")
+@cur_workspace_access_guard()
+def list_app_logs(
+        app_id: uuid.UUID,
+        page: int = Query(1, ge=1),
+        pagesize: int = Query(20, ge=1, le=100),
+        is_draft: Optional[bool] = Query(None, description="是否草稿会话（不传则返回全部）"),
+        keyword: Optional[str] = Query(None, description="搜索关键词（匹配消息内容）"),
+        db: Session = Depends(get_db),
+        current_user=Depends(get_current_user),
+):
+    """查看应用下所有会话记录（分页）
+
+    - is_draft 不传则返回所有会话（草稿 + 正式）
+    - is_draft=True 只返回草稿会话
+    - is_draft=False 只返回发布会话
+    - 支持按 keyword 搜索（匹配消息内容）
+    - 按最新更新时间倒序排列
+    """
+    workspace_id = current_user.current_workspace_id
+
+    # 验证应用访问权限
+    app_service = AppService(db)
+    app = app_service.get_app(app_id, workspace_id)
+
+    # 使用 Service 层查询
+    log_service = AppLogService(db)
+    conversations, total = log_service.list_conversations(
+        app_id=app_id,
+        workspace_id=workspace_id,
+        page=page,
+        pagesize=pagesize,
+        is_draft=is_draft,
+        keyword=keyword,
+        app_type=app.type,
+    )
+
+    items = [AppLogConversation.model_validate(c) for c in conversations]
+    meta = PageMeta(page=page, pagesize=pagesize, total=total, hasnext=(page * pagesize) < total)
+
+    return success(data=PageData(page=meta, items=items))
+
+
+@router.get("/{app_id}/logs/{conversation_id}", summary="应用日志 - 会话消息详情")
+@cur_workspace_access_guard()
+def get_app_log_detail(
+        app_id: uuid.UUID,
+        conversation_id: uuid.UUID,
+        db: Session = Depends(get_db),
+        current_user=Depends(get_current_user),
+):
+    """查看某会话的完整消息记录
+
+    - 返回会话基本信息 + 所有消息（按时间正序）
+    - 消息 meta_data 包含模型名、token 用量等信息
+    - 所有人（包括共享者和被共享者）都只能查看自己的会话详情
+    """
+    workspace_id = current_user.current_workspace_id
+
+    # 验证应用访问权限
+    app_service = AppService(db)
+    app = app_service.get_app(app_id, workspace_id)
+
+    # 使用 Service 层查询
+    log_service = AppLogService(db)
+    conversation, messages, node_executions_map = log_service.get_conversation_detail(
+        app_id=app_id,
+        conversation_id=conversation_id,
+        workspace_id=workspace_id,
+        app_type=app.type
+    )
+
+    # 构建基础会话信息（不经过 ORM relationship）
+    base = AppLogConversation.model_validate(conversation)
+
+    # 单独处理 messages，避免触发 SQLAlchemy relationship 校验
+    if messages and isinstance(messages[0], AppLogMessage):
+        # 工作流：已经是 AppLogMessage 实例
+        msg_list = messages
+    else:
+        # Agent：ORM Message 对象逐个转换
+        msg_list = [AppLogMessage.model_validate(m) for m in messages]
+
+    detail = AppLogConversationDetail(
+        **base.model_dump(),
+        messages=msg_list,
+        node_executions_map=node_executions_map,
+    )
+
+    return success(data=detail)

api/app/controllers/auth_controller.py

@@ -1,4 +1,5 @@
 from datetime import datetime, timedelta, timezone
+from typing import Callable
 from fastapi import APIRouter, Depends
 from sqlalchemy.orm import Session
 
@@ -16,6 +17,7 @@ from app.core.exceptions import BusinessException
 from app.core.error_codes import BizCode
 from app.dependencies import get_current_user, oauth2_scheme
 from app.models.user_model import User
+from app.i18n.dependencies import get_translator
 
 # 获取专用日志器
 auth_logger = get_auth_logger()
@@ -26,7 +28,8 @@ router = APIRouter(tags=["Authentication"])
 @router.post("/token", response_model=ApiResponse)
 async def login_for_access_token(
     form_data: TokenRequest,
-    db: Session = Depends(get_db)
+    db: Session = Depends(get_db),
+    t: Callable = Depends(get_translator)
 ):
     """用户登录获取token"""
     auth_logger.info(f"用户登录请求: {form_data.email}")
@@ -40,36 +43,38 @@ async def login_for_access_token(
         invite_info = workspace_service.validate_invite_token(db, form_data.invite)
         
         if not invite_info.is_valid:
-            raise BusinessException("邀请码无效或已过期", code=BizCode.BAD_REQUEST)
+            raise BusinessException(t("auth.invite.invalid"), code=BizCode.BAD_REQUEST)
         
         if invite_info.email != form_data.email:
-            raise BusinessException("邀请邮箱与登录邮箱不匹配", code=BizCode.BAD_REQUEST)        
+            raise BusinessException(t("auth.invite.email_mismatch"), code=BizCode.BAD_REQUEST)        
         auth_logger.info(f"邀请码验证成功: workspace={invite_info.workspace_name}")
         try:
             # 尝试认证用户
             user = auth_service.authenticate_user_or_raise(db, form_data.email, form_data.password)
             auth_logger.info(f"用户认证成功: {user.email} (ID: {user.id})")
             if form_data.invite:
-                auth_service.bind_workspace_with_invite(db=db,
-                user=user,        
-                invite_token=form_data.invite,
-                workspace_id=invite_info.workspace_id)
+                auth_service.bind_workspace_with_invite(
+                    db=db,
+                    user=user,
+                    invite_token=form_data.invite,
+                    workspace_id=invite_info.workspace_id
+                )
         except BusinessException as e:
         # 用户不存在且有邀请码，尝试注册
             if e.code == BizCode.USER_NOT_FOUND:
                 auth_logger.info(f"用户不存在，使用邀请码注册: {form_data.email}")
                 user = auth_service.register_user_with_invite(
-                db=db,
-                email=form_data.email,
-                username=form_data.username,
-                password=form_data.password,
-                invite_token=form_data.invite,
-                workspace_id=invite_info.workspace_id
-            )
+                    db=db,
+                    email=form_data.email,
+                    username=form_data.username,
+                    password=form_data.password,
+                    invite_token=form_data.invite,
+                    workspace_id=invite_info.workspace_id
+                )
             elif e.code == BizCode.PASSWORD_ERROR:
                 # 用户存在但密码错误
                 auth_logger.warning(f"接受邀请失败，密码验证错误: {form_data.email}")
-                raise BusinessException("接受邀请失败，密码验证错误", BizCode.LOGIN_FAILED)
+                raise BusinessException(t("auth.invite.password_verification_failed"), BizCode.LOGIN_FAILED)
             else:
                 # 其他认证失败情况，直接抛出
                 raise
@@ -82,7 +87,7 @@ async def login_for_access_token(
         except BusinessException as e:
             
             # 其他认证失败情况，直接抛出
-            raise BusinessException(e.message,BizCode.LOGIN_FAILED)
+            raise BusinessException(e.message, BizCode.LOGIN_FAILED)
 
     # 创建 tokens
     access_token, access_token_id = security.create_access_token(subject=user.id)
@@ -110,14 +115,15 @@ async def login_for_access_token(
             expires_at=access_expires_at,
             refresh_expires_at=refresh_expires_at
         ),
-        msg="登录成功"
+        msg=t("auth.login.success")
     )
 
 
 @router.post("/refresh", response_model=ApiResponse)
 async def refresh_token(
     refresh_request: RefreshTokenRequest,
-    db: Session = Depends(get_db)
+    db: Session = Depends(get_db),
+    t: Callable = Depends(get_translator)
 ):
     """刷新token"""
     auth_logger.info("收到token刷新请求")
@@ -125,18 +131,18 @@ async def refresh_token(
     # 验证 refresh token
     userId = security.verify_token(refresh_request.refresh_token, "refresh")
     if not userId:
-        raise BusinessException("无效的refresh token", code=BizCode.TOKEN_INVALID)
+        raise BusinessException(t("auth.token.invalid_refresh_token"), code=BizCode.TOKEN_INVALID)
     
     # 检查用户是否存在
     user = auth_service.get_user_by_id(db, userId)
     if not user:
-        raise BusinessException("用户不存在", code=BizCode.USER_NOT_FOUND)
+        raise BusinessException(t("auth.user.not_found"), code=BizCode.USER_NO_ACCESS)
     
     # 检查 refresh token 黑名单
     if settings.ENABLE_SINGLE_SESSION:
         refresh_token_id = security.get_token_id(refresh_request.refresh_token)
         if refresh_token_id and await SessionService.is_token_blacklisted(refresh_token_id):
-            raise BusinessException("Refresh token已失效", code=BizCode.TOKEN_BLACKLISTED)
+            raise BusinessException(t("auth.token.refresh_token_blacklisted"), code=BizCode.TOKEN_BLACKLISTED)
     
     # 生成新 tokens
     new_access_token, new_access_token_id = security.create_access_token(subject=user.id)
@@ -167,7 +173,7 @@ async def refresh_token(
             expires_at=access_expires_at,
             refresh_expires_at=refresh_expires_at
         ),
-        msg="token刷新成功"
+        msg=t("auth.token.refresh_success")
     )
 
 
@@ -175,14 +181,15 @@ async def refresh_token(
 async def logout(
     token: str = Depends(oauth2_scheme),
     current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db)
+    db: Session = Depends(get_db),
+    t: Callable = Depends(get_translator)
 ):
     """登出当前用户：加入token黑名单并清理会话"""
     auth_logger.info(f"用户 {current_user.username} 请求登出")
     
     token_id = security.get_token_id(token)
     if not token_id:
-        raise BusinessException("无效的access token", code=BizCode.TOKEN_INVALID)
+        raise BusinessException(t("auth.token.invalid"), code=BizCode.TOKEN_INVALID)
 
     # 加入黑名单
     await SessionService.blacklist_token(token_id)
@@ -192,5 +199,5 @@ async def logout(
         await SessionService.clear_user_session(current_user.username)
 
     auth_logger.info(f"用户 {current_user.username} 登出成功")
-    return success(msg="登出成功")
+    return success(msg=t("auth.logout.success"))
 

api/app/controllers/chunk_controller.py

@@ -1,8 +1,10 @@
 import os
+import csv
+import io
 from typing import Any, Optional
 import uuid
 
-from fastapi import APIRouter, Depends, HTTPException, status, Query
+from fastapi import APIRouter, Depends, HTTPException, status, Query, UploadFile, File
 from fastapi.encoders import jsonable_encoder
 from sqlalchemy.orm import Session
 
@@ -23,6 +25,8 @@ from app.models.user_model import User
 from app.schemas import chunk_schema
 from app.schemas.response_schema import ApiResponse
 from app.services import knowledge_service, document_service, file_service, knowledgeshare_service
+from app.services.file_storage_service import FileStorageService, get_file_storage_service, generate_kb_file_key
+from app.services.model_service import ModelApiKeyService
 
 # Obtain a dedicated API logger
 api_logger = get_api_logger()
@@ -81,19 +85,32 @@ async def get_preview_chunks(
             detail="The file does not exist or you do not have permission to access it"
         )
 
-    # 5. Construct file path：/files/{kb_id}/{parent_id}/{file.id}{file.file_ext}
-    file_path = os.path.join(
-        settings.FILE_PATH,
-        str(db_file.kb_id),
-        str(db_file.parent_id),
-        f"{db_file.id}{db_file.file_ext}"
-    )
-
-    # 6. Check if the file exists
-    if not os.path.exists(file_path):
+    # 5. Get file content from storage backend
+    if not db_file.file_key:
         raise HTTPException(
             status_code=status.HTTP_404_NOT_FOUND,
-            detail="File not found (possibly deleted)"
+            detail="File has no storage key (legacy data not migrated)"
+        )
+
+    from app.services.file_storage_service import FileStorageService
+    import asyncio
+    storage_service = FileStorageService()
+
+    async def _download():
+        return await storage_service.download_file(db_file.file_key)
+
+    try:
+        file_binary = asyncio.run(_download())
+    except RuntimeError:
+        loop = asyncio.new_event_loop()
+        try:
+            file_binary = loop.run_until_complete(_download())
+        finally:
+            loop.close()
+    except Exception as e:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"File not found in storage: {e}"
         )
 
     # 7. Document parsing & segmentation
@@ -103,11 +120,12 @@ async def get_preview_chunks(
     vision_model = QWenCV(
             key=db_knowledge.image2text.api_keys[0].api_key,
             model_name=db_knowledge.image2text.api_keys[0].model_name,
-            lang="Chinese",  # Default to Chinese
+            lang="Chinese",
             base_url=db_knowledge.image2text.api_keys[0].api_base
         )
     from app.core.rag.app.naive import chunk
-    res = chunk(filename=file_path,
+    res = chunk(filename=db_file.file_name,
+                binary=file_binary,
                 from_page=0,
                 to_page=5,
                 callback=progress_callback,
@@ -256,6 +274,9 @@ async def create_chunk(
         "sort_id": sort_id,
         "status": 1,
     }
+    # QA chunk: 注入 chunk_type/question/answer 到 metadata
+    if create_data.is_qa:
+        metadata.update(create_data.qa_metadata)
     chunk = DocumentChunk(page_content=content, metadata=metadata)
     # 3. Segmented vector storage
     vector_service.add_chunks([chunk])
@@ -267,6 +288,187 @@ async def create_chunk(
     return success(data=jsonable_encoder(chunk), msg="Document chunk creation successful")
 
 
+@router.post("/{kb_id}/{document_id}/chunk/batch", response_model=ApiResponse)
+async def create_chunks_batch(
+        kb_id: uuid.UUID,
+        document_id: uuid.UUID,
+        batch_data: chunk_schema.ChunkBatchCreate,
+        db: Session = Depends(get_db),
+        current_user: User = Depends(get_current_user)
+):
+    """
+    Batch create chunks (max 8)
+    """
+    api_logger.info(f"Batch create chunks: kb_id={kb_id}, document_id={document_id}, count={len(batch_data.items)}, username: {current_user.username}")
+
+    if len(batch_data.items) > settings.MAX_CHUNK_BATCH_SIZE:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Batch size exceeds limit: max {settings.MAX_CHUNK_BATCH_SIZE}, got {len(batch_data.items)}"
+        )
+
+    db_knowledge = knowledge_service.get_knowledge_by_id(db, knowledge_id=kb_id, current_user=current_user)
+    if not db_knowledge:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="The knowledge base does not exist or access is denied")
+
+    db_document = db.query(Document).filter(Document.id == document_id).first()
+    if not db_document:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="The document does not exist or you do not have permission to access it")
+
+    vector_service = ElasticSearchVectorFactory().init_vector(knowledge=db_knowledge)
+
+    # Get current max sort_id
+    sort_id = 0
+    total, items = vector_service.search_by_segment(document_id=str(document_id), pagesize=1, page=1, asc=False)
+    if items:
+        sort_id = items[0].metadata["sort_id"]
+
+    chunks = []
+    for create_data in batch_data.items:
+        sort_id += 1
+        doc_id = uuid.uuid4().hex
+        metadata = {
+            "doc_id": doc_id,
+            "file_id": str(db_document.file_id),
+            "file_name": db_document.file_name,
+            "file_created_at": int(db_document.created_at.timestamp() * 1000),
+            "document_id": str(document_id),
+            "knowledge_id": str(kb_id),
+            "sort_id": sort_id,
+            "status": 1,
+        }
+        if create_data.is_qa:
+            metadata.update(create_data.qa_metadata)
+        chunks.append(DocumentChunk(page_content=create_data.chunk_content, metadata=metadata))
+
+    vector_service.add_chunks(chunks)
+
+    db_document.chunk_num += len(chunks)
+    db.commit()
+
+    return success(data=jsonable_encoder(chunks), msg=f"Batch created {len(chunks)} chunks successfully")
+
+
+@router.post("/{kb_id}/import_qa", response_model=ApiResponse)
+async def import_qa_new_doc(
+        kb_id: uuid.UUID,
+        file: UploadFile = File(..., description="CSV 或 Excel 文件（第一行标题跳过，第一列问题，第二列答案）"),
+        db: Session = Depends(get_db),
+        current_user: User = Depends(get_current_user),
+        storage_service: FileStorageService = Depends(get_file_storage_service),
+):
+    """
+    导入 QA 问答对并新建文档（CSV/Excel），异步处理
+    """
+    from app.schemas import file_schema, document_schema
+
+    api_logger.info(f"Import QA (new doc): kb_id={kb_id}, file={file.filename}, username: {current_user.username}")
+
+    # 1. 校验文件格式
+    filename = file.filename or ""
+    if not (filename.endswith(".csv") or filename.endswith(".xlsx") or filename.endswith(".xls")):
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="仅支持 CSV (.csv) 或 Excel (.xlsx) 格式")
+
+    # 2. 校验知识库
+    db_knowledge = knowledge_service.get_knowledge_by_id(db, knowledge_id=kb_id, current_user=current_user)
+    if not db_knowledge:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="知识库不存在或无权访问")
+
+    # 3. 读取文件
+    contents = await file.read()
+    file_size = len(contents)
+    if file_size == 0:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="文件为空")
+
+    _, file_extension = os.path.splitext(filename)
+    file_ext = file_extension.lower()
+
+    # 4. 创建 File 记录
+    file_data = file_schema.FileCreate(
+        kb_id=kb_id, created_by=current_user.id,
+        parent_id=uuid.UUID("00000000-0000-0000-0000-000000000000"),
+        file_name=filename, file_ext=file_ext, file_size=file_size,
+    )
+    db_file = file_service.create_file(db=db, file=file_data, current_user=current_user)
+
+    # 5. 上传文件到存储后端
+    file_key = generate_kb_file_key(kb_id=kb_id, file_id=db_file.id, file_ext=file_ext)
+    try:
+        await storage_service.storage.upload(file_key=file_key, content=contents, content_type=file.content_type)
+    except Exception as e:
+        api_logger.error(f"Storage upload failed: {e}")
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"文件存储失败: {str(e)}")
+
+    db_file.file_key = file_key
+    db.commit()
+    db.refresh(db_file)
+
+    # 6. 创建 Document 记录（标记为 QA 类型）
+    doc_data = document_schema.DocumentCreate(
+        kb_id=kb_id, created_by=current_user.id, file_id=db_file.id,
+        file_name=filename, file_ext=file_ext, file_size=file_size,
+        file_meta={}, parser_id="qa",
+        parser_config={"doc_type": "qa", "auto_questions": 0}
+    )
+    db_document = document_service.create_document(db=db, document=doc_data, current_user=current_user)
+
+    api_logger.info(f"Created doc for QA import: file_id={db_file.id}, document_id={db_document.id}, file_key={file_key}")
+
+    # 7. 派发异步任务
+    from app.celery_app import celery_app
+    task = celery_app.send_task(
+        "app.core.rag.tasks.import_qa_chunks",
+        args=[str(kb_id), str(db_document.id), filename, contents],
+        queue="qa_import"
+    )
+
+    return success(data={
+        "task_id": task.id,
+        "document_id": str(db_document.id),
+        "file_id": str(db_file.id),
+    }, msg="QA 导入任务已提交，后台处理中")
+
+
+@router.post("/{kb_id}/{document_id}/import_qa", response_model=ApiResponse)
+async def import_qa_chunks(
+        kb_id: uuid.UUID,
+        document_id: uuid.UUID,
+        file: UploadFile = File(..., description="CSV 或 Excel 文件（第一行标题跳过，第一列问题，第二列答案）"),
+        db: Session = Depends(get_db),
+        current_user: User = Depends(get_current_user)
+):
+    """
+    导入 QA 问答对（CSV/Excel），异步处理
+    """
+    api_logger.info(f"Import QA chunks: kb_id={kb_id}, document_id={document_id}, file={file.filename}, username: {current_user.username}")
+
+    # 1. 校验文件格式
+    filename = file.filename or ""
+    if not (filename.endswith(".csv") or filename.endswith(".xlsx") or filename.endswith(".xls")):
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="仅支持 CSV (.csv) 或 Excel (.xlsx) 格式")
+
+    # 2. 校验知识库和文档
+    db_knowledge = knowledge_service.get_knowledge_by_id(db, knowledge_id=kb_id, current_user=current_user)
+    if not db_knowledge:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="知识库不存在或无权访问")
+
+    db_document = db.query(Document).filter(Document.id == document_id).first()
+    if not db_document:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="文档不存在或无权访问")
+
+    # 3. 读取文件内容，派发异步任务
+    contents = await file.read()
+
+    from app.celery_app import celery_app
+    task = celery_app.send_task(
+        "app.core.rag.tasks.import_qa_chunks",
+        args=[str(kb_id), str(document_id), filename, contents],
+        queue="qa_import"
+    )
+
+    return success(data={"task_id": task.id}, msg="QA 导入任务已提交，后台处理中")
+
+
 @router.get("/{kb_id}/{document_id}/{doc_id}", response_model=ApiResponse)
 async def get_chunk(
         kb_id: uuid.UUID,
@@ -327,6 +529,9 @@ async def update_chunk(
     if total:
         chunk = items[0]
         chunk.page_content = content
+        # QA chunk: 更新 metadata 中的 question/answer
+        if update_data.is_qa:
+            chunk.metadata.update(update_data.qa_metadata)
         vector_service.update_by_segment(chunk)
         return success(data=jsonable_encoder(chunk), msg="The document chunk has been successfully updated")
     else:
@@ -341,6 +546,7 @@ async def delete_chunk(
         kb_id: uuid.UUID,
         document_id: uuid.UUID,
         doc_id: str,
+        force_refresh: bool = Query(False, description="Force Elasticsearch refresh after deletion"),
         db: Session = Depends(get_db),
         current_user: User = Depends(get_current_user)
 ):
@@ -358,7 +564,7 @@ async def delete_chunk(
 
     vector_service = ElasticSearchVectorFactory().init_vector(knowledge=db_knowledge)
     if vector_service.text_exists(doc_id):
-        vector_service.delete_by_ids([doc_id])
+        vector_service.delete_by_ids([doc_id], refresh=force_refresh)
         # 更新 chunk_num
         db_document = db.query(Document).filter(Document.id == document_id).first()
         db_document.chunk_num -= 1
@@ -441,14 +647,14 @@ async def retrieve_chunks(
     # 1 participle search, 2 semantic search, 3 hybrid search
     match retrieve_data.retrieve_type:
         case chunk_schema.RetrieveType.PARTICIPLE:
-            rs = vector_service.search_by_full_text(query=retrieve_data.query, top_k=retrieve_data.top_k, indices=indices, score_threshold=retrieve_data.similarity_threshold)
-            return success(data=rs, msg="retrieval successful")
+            rs = vector_service.search_by_full_text(query=retrieve_data.query, top_k=retrieve_data.top_k, indices=indices, score_threshold=retrieve_data.similarity_threshold, file_names_filter=retrieve_data.file_names_filter)
+            return success(data=jsonable_encoder(rs), msg="retrieval successful")
         case chunk_schema.RetrieveType.SEMANTIC:
-            rs = vector_service.search_by_vector(query=retrieve_data.query, top_k=retrieve_data.top_k, indices=indices, score_threshold=retrieve_data.vector_similarity_weight)
-            return success(data=rs, msg="retrieval successful")
+            rs = vector_service.search_by_vector(query=retrieve_data.query, top_k=retrieve_data.top_k, indices=indices, score_threshold=retrieve_data.vector_similarity_weight, file_names_filter=retrieve_data.file_names_filter)
+            return success(data=jsonable_encoder(rs), msg="retrieval successful")
         case _:
-            rs1 = vector_service.search_by_vector(query=retrieve_data.query, top_k=retrieve_data.top_k, indices=indices, score_threshold=retrieve_data.vector_similarity_weight)
-            rs2 = vector_service.search_by_full_text(query=retrieve_data.query, top_k=retrieve_data.top_k, indices=indices, score_threshold=retrieve_data.similarity_threshold)
+            rs1 = vector_service.search_by_vector(query=retrieve_data.query, top_k=retrieve_data.top_k, indices=indices, score_threshold=retrieve_data.vector_similarity_weight, file_names_filter=retrieve_data.file_names_filter)
+            rs2 = vector_service.search_by_full_text(query=retrieve_data.query, top_k=retrieve_data.top_k, indices=indices, score_threshold=retrieve_data.similarity_threshold, file_names_filter=retrieve_data.file_names_filter)
             # Efficient deduplication
             seen_ids = set()
             unique_rs = []
@@ -456,22 +662,24 @@ async def retrieve_chunks(
                 if doc.metadata["doc_id"] not in seen_ids:
                     seen_ids.add(doc.metadata["doc_id"])
                     unique_rs.append(doc)
-            rs = vector_service.rerank(query=retrieve_data.query, docs=unique_rs, top_k=retrieve_data.top_k)
+            rs = vector_service.rerank(query=retrieve_data.query, docs=unique_rs, top_k=retrieve_data.top_k) if unique_rs else []
             if retrieve_data.retrieve_type == chunk_schema.RetrieveType.Graph:
                 kb_ids = [str(kb_id) for kb_id in private_kb_ids]
                 workspace_ids = [str(workspace_id) for workspace_id in private_workspace_ids]
+                llm_key = ModelApiKeyService.get_available_api_key(db, db_knowledge.llm_id)
+                emb_key = ModelApiKeyService.get_available_api_key(db, db_knowledge.embedding_id)
                 # Prepare to configure chat_mdl、embedding_model、vision_model information
                 chat_model = Base(
-                    key=db_knowledge.llm.api_keys[0].api_key,
-                    model_name=db_knowledge.llm.api_keys[0].model_name,
-                    base_url=db_knowledge.llm.api_keys[0].api_base
+                    key=llm_key.api_key,
+                    model_name=llm_key.model_name,
+                    base_url=llm_key.api_base
                 )
                 embedding_model = OpenAIEmbed(
-                    key=db_knowledge.embedding.api_keys[0].api_key,
-                    model_name=db_knowledge.embedding.api_keys[0].model_name,
-                    base_url=db_knowledge.embedding.api_keys[0].api_base
+                    key=emb_key.api_key,
+                    model_name=emb_key.model_name,
+                    base_url=emb_key.api_base
                 )
-                doc = kg_retriever.retrieval(question=retrieve_data.query, workspace_ids=workspace_ids, kb_ids= kb_ids, emb_mdl=embedding_model, llm=chat_model)
+                doc = kg_retriever.retrieval(question=retrieve_data.query, workspace_ids=workspace_ids, kb_ids=kb_ids, emb_mdl=embedding_model, llm=chat_model)
                 if doc:
                     rs.insert(0, doc)
             return success(data=jsonable_encoder(rs), msg="retrieval successful")

api/app/controllers/document_controller.py

@@ -20,6 +20,7 @@ from app.models.user_model import User
 from app.schemas import document_schema
 from app.schemas.response_schema import ApiResponse
 from app.services import document_service, file_service, knowledge_service
+from app.services.file_storage_service import FileStorageService, get_file_storage_service
 
 
 # Obtain a dedicated API logger
@@ -231,7 +232,8 @@ async def update_document(
 async def delete_document(
         document_id: uuid.UUID,
         db: Session = Depends(get_db),
-        current_user: User = Depends(get_current_user)
+        current_user: User = Depends(get_current_user),
+        storage_service: FileStorageService = Depends(get_file_storage_service),
 ):
     """
     Delete document
@@ -257,7 +259,7 @@ async def delete_document(
         db.commit()
 
         # 3. Delete file
-        await file_controller._delete_file(db=db, file_id=file_id, current_user=current_user)
+        await file_controller._delete_file(db=db, file_id=file_id, current_user=current_user, storage_service=storage_service)
 
         # 4. Delete vector index
         db_knowledge = knowledge_service.get_knowledge_by_id(db, knowledge_id=db_document.kb_id, current_user=current_user)
@@ -305,36 +307,25 @@ async def parse_documents(
                 detail="The file does not exist or you do not have permission to access it"
             )
 
-        # 3. Construct file path：/files/{kb_id}/{parent_id}/{file.id}{file.file_ext}
-        file_path = os.path.join(
-            settings.FILE_PATH,
-            str(db_file.kb_id),
-            str(db_file.parent_id),
-            f"{db_file.id}{db_file.file_ext}"
-        )
-
-        # 4. Check if the file exists
-        if not os.path.exists(file_path):
-            api_logger.warning(f"File not found (possibly deleted): file_path={file_path}")
+        # 3. Get file_key for storage backend
+        if not db_file.file_key:
+            api_logger.error(f"File has no storage key (legacy data not migrated): file_id={db_file.id}")
             raise HTTPException(
                 status_code=status.HTTP_404_NOT_FOUND,
-                detail="File not found (possibly deleted)"
+                detail="File has no storage key (legacy data not migrated)"
             )
 
-        # 5. Obtain knowledge base information
-        api_logger.info( f"Obtain details of the knowledge base: knowledge_id={db_document.kb_id}")
+        # 4. Obtain knowledge base information
+        api_logger.info(f"Obtain details of the knowledge base: knowledge_id={db_document.kb_id}")
         db_knowledge = knowledge_service.get_knowledge_by_id(db, knowledge_id=db_document.kb_id, current_user=current_user)
         if not db_knowledge:
-            api_logger.warning(f"The knowledge base does not exist or access is denied: knowledge_id={db_document.kb_id}")
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail="The knowledge base does not exist or access is denied"
-            )
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Knowledge base not found")
 
-        # 6. Task: Document parsing, vectorization, and storage
-        # from app.tasks import parse_document
-        # parse_document(file_path, document_id)
-        task = celery_app.send_task("app.core.rag.tasks.parse_document", args=[file_path, document_id])
+        # 5. Dispatch parse task with file_key (not file_path)
+        task = celery_app.send_task(
+            "app.core.rag.tasks.parse_document",
+            args=[db_file.file_key, document_id, db_file.file_name]
+        )
         result = {
             "task_id": task.id
         }

api/app/controllers/emotion_controller.py

@@ -208,14 +208,64 @@ async def get_emotion_health(
 
 
 
+# @router.post("/check-data", response_model=ApiResponse)
+# async def check_emotion_data_exists(
+#     request: EmotionSuggestionsRequest,
+#     db: Session = Depends(get_db),
+#     current_user: User = Depends(get_current_user),
+# ):
+#     """检查用户情绪建议数据是否存在
+
+#     Args:
+#         request: 包含 end_user_id
+#         db: 数据库会话
+#         current_user: 当前用户
+
+#     Returns:
+#         数据存在状态
+#     """
+#     try:
+#         api_logger.info(
+#             f"检查用户情绪建议数据是否存在: {request.end_user_id}",
+#             extra={"end_user_id": request.end_user_id}
+#         )
+
+#         # 从数据库获取建议
+#         data = await emotion_service.get_cached_suggestions(
+#             end_user_id=request.end_user_id,
+#             db=db
+#         )
+
+#         if data is None:
+#             api_logger.info(f"用户 {request.end_user_id} 的情绪建议数据不存在")
+#             return fail(
+#                 BizCode.NOT_FOUND,
+#                 "情绪建议数据不存在，请点击右上角刷新进行初始化",
+#                 {"exists": False}
+#             )
+
+#         api_logger.info(f"用户 {request.end_user_id} 的情绪建议数据存在")
+#         return success(data={"exists": True}, msg="情绪建议数据已存在")
+
+#     except Exception as e:
+#         api_logger.error(
+#             f"检查情绪建议数据失败: {str(e)}",
+#             extra={"end_user_id": request.end_user_id},
+#             exc_info=True
+#         )
+#         raise HTTPException(
+#             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+#             detail=f"检查情绪建议数据失败: {str(e)}"
+#         )
+
+
 @router.post("/suggestions", response_model=ApiResponse)
 async def get_emotion_suggestions(
     request: EmotionSuggestionsRequest,
-    language_type: str = Header(default=None, alias="X-Language-Type"),
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
 ):
-    """获取个性化情绪建议（从缓存读取）
+    """获取个性化情绪建议（从数据库读取）
 
     Args:
         request: 包含 end_user_id 和可选的 config_id
@@ -223,77 +273,42 @@ async def get_emotion_suggestions(
         current_user: 当前用户
 
     Returns:
-        缓存的个性化情绪建议响应
+        存储的个性化情绪建议响应
     """
     try:
-        # 使用集中化的语言校验
-        language = get_language_from_header(language_type)
-        
         api_logger.info(
-            f"用户 {current_user.username} 请求获取个性化情绪建议（缓存）",
+            f"用户 {current_user.username} 请求获取个性化情绪建议",
             extra={
                 "end_user_id": request.end_user_id,
                 "config_id": request.config_id
             }
         )
 
-        # 从缓存获取建议
+        # 从数据库获取建议
         data = await emotion_service.get_cached_suggestions(
             end_user_id=request.end_user_id,
             db=db
         )
 
         if data is None:
-            # 缓存不存在或已过期，自动触发生成
             api_logger.info(
-                f"用户 {request.end_user_id} 的建议缓存不存在或已过期，自动生成新建议",
+                f"用户 {request.end_user_id} 的建议数据不存在",
                 extra={"end_user_id": request.end_user_id}
             )
-            try:
-                data = await emotion_service.generate_emotion_suggestions(
-                    end_user_id=request.end_user_id,
-                    db=db,
-                    language=language
-                )
-                # 保存到缓存
-                await emotion_service.save_suggestions_cache(
-                    end_user_id=request.end_user_id,
-                    suggestions_data=data,
-                    db=db,
-                    expires_hours=24
-                )
-            except (ValueError, KeyError) as gen_e:
-                # 预期内的业务异常：配置缺失、数据格式问题等
-                api_logger.warning(
-                    f"自动生成建议失败（业务异常）: {str(gen_e)}",
-                    extra={"end_user_id": request.end_user_id}
-                )
-                return fail(
-                    BizCode.NOT_FOUND,
-                    f"自动生成建议失败: {str(gen_e)}",
-                    ""
-                )
-            except Exception as gen_e:
-                # 非预期异常：记录完整 traceback 便于排查
-                api_logger.error(
-                    f"自动生成建议时发生未预期异常: {str(gen_e)}",
-                    extra={"end_user_id": request.end_user_id},
-                    exc_info=True
-                )
-                raise HTTPException(
-                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-                    detail=f"生成建议时发生内部错误: {str(gen_e)}"
-                )
+            return success(
+                data={"exists": False},
+                msg="情绪建议数据不存在，请点击右上角刷新进行初始化"
+            )
 
         api_logger.info(
-            "个性化建议获取成功（缓存）",
+            "个性化建议获取成功",
             extra={
                 "end_user_id": request.end_user_id,
                 "suggestions_count": len(data.get("suggestions", []))
             }
         )
 
-        return success(data=data, msg="个性化建议获取成功（缓存）")
+        return success(data=data, msg="个性化建议获取成功")
 
     except Exception as e:
         api_logger.error(
@@ -314,7 +329,7 @@ async def generate_emotion_suggestions(
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
 ):
-    """生成个性化情绪建议（调用LLM并缓存）
+    """生成个性化情绪建议（调用LLM并保存到数据库）
 
     Args:
         request: 包含 end_user_id
@@ -342,12 +357,11 @@ async def generate_emotion_suggestions(
             language=language
         )
 
-        # 保存到缓存
+        # 保存到数据库
         await emotion_service.save_suggestions_cache(
             end_user_id=request.end_user_id,
             suggestions_data=data,
-            db=db,
-            expires_hours=24
+            db=db
         )
 
         api_logger.info(
@@ -369,4 +383,4 @@ async def generate_emotion_suggestions(
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             detail=f"生成个性化建议失败: {str(e)}"
-        )
+        )

api/app/controllers/file_controller.py

@@ -1,12 +1,10 @@
 import os
-from pathlib import Path
-import shutil
 from typing import Any, Optional
 import uuid
 
 from fastapi import APIRouter, Depends, HTTPException, status, File, UploadFile, Query
 from fastapi.encoders import jsonable_encoder
-from fastapi.responses import FileResponse
+from fastapi.responses import Response
 from sqlalchemy.orm import Session
 
 from app.core.config import settings
@@ -19,9 +17,14 @@ from app.models.user_model import User
 from app.schemas import file_schema, document_schema
 from app.schemas.response_schema import ApiResponse
 from app.services import file_service, document_service
+from app.services.knowledge_service import get_knowledge_by_id as get_kb_by_id
+from app.services.file_storage_service import (
+    FileStorageService,
+    generate_kb_file_key,
+    get_file_storage_service,
+)
+from app.core.quota_stub import check_knowledge_capacity_quota
 
-
-# Obtain a dedicated API logger
 api_logger = get_api_logger()
 
 router = APIRouter(
@@ -34,67 +37,37 @@ router = APIRouter(
 async def get_files(
         kb_id: uuid.UUID,
         parent_id: uuid.UUID,
-        page: int = Query(1, gt=0),  # Default: 1, which must be greater than 0
-        pagesize: int = Query(20, gt=0, le=100),  # Default: 20 items per page, maximum: 100 items
+        page: int = Query(1, gt=0),
+        pagesize: int = Query(20, gt=0, le=100),
         orderby: Optional[str] = Query(None, description="Sort fields, such as: created_at"),
         desc: Optional[bool] = Query(False, description="Is it descending order"),
         keywords: Optional[str] = Query(None, description="Search keywords (file name)"),
         db: Session = Depends(get_db),
         current_user: User = Depends(get_current_user)
 ):
-    """
-    Paged query file list
-    - Support filtering by kb_id and parent_id
-    - Support keyword search for file names
-    - Support dynamic sorting
-    - Return paging metadata + file list
-    """
-    api_logger.info(f"Query file list: kb_id={kb_id}, parent_id={parent_id}, page={page}, pagesize={pagesize}, keywords={keywords}, username: {current_user.username}")
-    # 1. parameter validation
-    if page < 1 or pagesize < 1:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="The paging parameter must be greater than 0"
-        )
+    """Paged query file list"""
+    api_logger.info(f"Query file list: kb_id={kb_id}, parent_id={parent_id}, page={page}, pagesize={pagesize}")
 
-    # 2. Construct query conditions
-    filters = [
-        file_model.File.kb_id == kb_id
-    ]
+    if page < 1 or pagesize < 1:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="The paging parameter must be greater than 0")
+
+    filters = [file_model.File.kb_id == kb_id]
     if parent_id:
         filters.append(file_model.File.parent_id == parent_id)
-    # Keyword search (fuzzy matching of file name)
     if keywords:
         filters.append(file_model.File.file_name.ilike(f"%{keywords}%"))
 
-    # 3. Execute paged query
     try:
-        api_logger.debug("Start executing file paging query")
         total, items = file_service.get_files_paginated(
-            db=db,
-            filters=filters,
-            page=page,
-            pagesize=pagesize,
-            orderby=orderby,
-            desc=desc,
-            current_user=current_user
+            db=db, filters=filters, page=page, pagesize=pagesize,
+            orderby=orderby, desc=desc, current_user=current_user
         )
-        api_logger.info(f"File query successful: total={total}, returned={len(items)} records")
     except Exception as e:
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Query failed: {str(e)}"
-        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"Query failed: {str(e)}")
 
-    # 4. Return structured response
     result = {
         "items": items,
-        "page": {
-            "page": page,
-            "pagesize": pagesize,
-            "total": total,
-            "has_next": True if page * pagesize < total else False
-        }
+        "page": {"page": page, "pagesize": pagesize, "total": total, "has_next": page * pagesize < total}
     }
     return success(data=jsonable_encoder(result), msg="Query of file list succeeded")
 
@@ -107,23 +80,14 @@ async def create_folder(
         db: Session = Depends(get_db),
         current_user: User = Depends(get_current_user),
 ):
-    """
-    Create a new folder
-    """
-    api_logger.info(f"Create folder request: kb_id={kb_id}, parent_id={parent_id}, folder_name={folder_name}, username: {current_user.username}")
-
+    """Create a new folder"""
+    api_logger.info(f"Create folder request: kb_id={kb_id}, parent_id={parent_id}, folder_name={folder_name}")
     try:
-        api_logger.debug(f"Start creating a folder: {folder_name}")
-        create_folder = file_schema.FileCreate(
-            kb_id=kb_id,
-            created_by=current_user.id,
-            parent_id=parent_id,
-            file_name=folder_name,
-            file_ext='folder',
-            file_size=0,
+        create_folder_data = file_schema.FileCreate(
+            kb_id=kb_id, created_by=current_user.id, parent_id=parent_id,
+            file_name=folder_name, file_ext='folder', file_size=0,
         )
-        db_file = file_service.create_file(db=db, file=create_folder, current_user=current_user)
-        api_logger.info(f"Folder created successfully: {db_file.file_name} (ID: {db_file.id})")
+        db_file = file_service.create_file(db=db, file=create_folder_data, current_user=current_user)
         return success(data=jsonable_encoder(file_schema.File.model_validate(db_file)), msg="Folder creation successful")
     except Exception as e:
         api_logger.error(f"Folder creation failed: {folder_name} - {str(e)}")
@@ -131,81 +95,64 @@ async def create_folder(
 
 
 @router.post("/file", response_model=ApiResponse)
+@check_knowledge_capacity_quota
 async def upload_file(
         kb_id: uuid.UUID,
         parent_id: uuid.UUID,
         file: UploadFile = File(...),
         db: Session = Depends(get_db),
-        current_user: User = Depends(get_current_user)
+        current_user: User = Depends(get_current_user),
+        storage_service: FileStorageService = Depends(get_file_storage_service),
 ):
-    """
-    upload file
-    """
-    api_logger.info(f"upload file request: kb_id={kb_id}, parent_id={parent_id}, filename={file.filename}, username: {current_user.username}")
+    """Upload file to storage backend"""
+    api_logger.info(f"upload file request: kb_id={kb_id}, parent_id={parent_id}, filename={file.filename}")
 
-    # Read the contents of the file
     contents = await file.read()
-    # Check file size
     file_size = len(contents)
-    print(f"file size: {file_size} byte")
     if file_size == 0:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="The file is empty."
-        )
-    # If the file size exceeds 50MB (50 * 1024 * 1024 bytes)
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="The file is empty.")
     if file_size > settings.MAX_FILE_SIZE:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"The file size exceeds the {settings.MAX_FILE_SIZE}byte limit"
-        )
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=f"File size exceeds {settings.MAX_FILE_SIZE} byte limit")
 
-    # Extract the extension using `os.path.splitext`
     _, file_extension = os.path.splitext(file.filename)
-    upload_file = file_schema.FileCreate(
-        kb_id=kb_id,
-        created_by=current_user.id,
-        parent_id=parent_id,
-        file_name=file.filename,
-        file_ext=file_extension.lower(),
-        file_size=file_size,
+    file_ext = file_extension.lower()
+
+    # Create File record
+    upload_file_data = file_schema.FileCreate(
+        kb_id=kb_id, created_by=current_user.id, parent_id=parent_id,
+        file_name=file.filename, file_ext=file_ext, file_size=file_size,
     )
-    db_file = file_service.create_file(db=db, file=upload_file, current_user=current_user)
+    db_file = file_service.create_file(db=db, file=upload_file_data, current_user=current_user)
 
-    # Construct a save path：/files/{kb_id}/{parent_id}/{file.id}{file_extension}
-    save_dir = os.path.join(settings.FILE_PATH, str(kb_id), str(parent_id))
-    Path(save_dir).mkdir(parents=True, exist_ok=True)  # Ensure that the directory exists
-    save_path = os.path.join(save_dir, f"{db_file.id}{db_file.file_ext}")
+    # Upload to storage backend
+    file_key = generate_kb_file_key(kb_id=kb_id, file_id=db_file.id, file_ext=file_ext)
+    try:
+        await storage_service.storage.upload(file_key=file_key, content=contents, content_type=file.content_type)
+    except Exception as e:
+        api_logger.error(f"Storage upload failed: {e}")
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"File storage failed: {str(e)}")
 
-    # Save file
-    with open(save_path, "wb") as f:
-        f.write(contents)
+    # Save file_key
+    db_file.file_key = file_key
+    db.commit()
+    db.refresh(db_file)
 
-    # Verify whether the file has been saved successfully
-    if not os.path.exists(save_path):
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail="File save failed"
-        )
+    # Create document (inherit parser_config from knowledge base)
+    default_parser_config = {
+        "layout_recognize": "DeepDOC", "chunk_token_num": 128, "delimiter": "\n",
+        "auto_keywords": 0, "auto_questions": 0, "html4excel": "false"
+    }
+    try:
+        db_knowledge = get_kb_by_id(db, knowledge_id=kb_id, current_user=current_user)
+        if db_knowledge and db_knowledge.parser_config:
+            default_parser_config.update(dict(db_knowledge.parser_config))
+    except Exception:
+        pass
 
-    # Create a document
     create_data = document_schema.DocumentCreate(
-        kb_id=kb_id,
-        created_by=current_user.id,
-        file_id=db_file.id,
-        file_name=db_file.file_name,
-        file_ext=db_file.file_ext,
-        file_size=db_file.file_size,
-        file_meta={},
-        parser_id="naive",
-        parser_config={
-            "layout_recognize": "DeepDOC",
-            "chunk_token_num": 128,
-            "delimiter": "\n",
-            "auto_keywords": 0,
-            "auto_questions": 0,
-            "html4excel": "false"
-        }
+        kb_id=kb_id, created_by=current_user.id, file_id=db_file.id,
+        file_name=db_file.file_name, file_ext=db_file.file_ext, file_size=db_file.file_size,
+        file_meta={}, parser_id="naive", parser_config=default_parser_config
     )
     db_document = document_service.create_document(db=db, document=create_data, current_user=current_user)
 
@@ -219,123 +166,73 @@ async def custom_text(
         parent_id: uuid.UUID,
         create_data: file_schema.CustomTextFileCreate,
         db: Session = Depends(get_db),
-        current_user: User = Depends(get_current_user)
+        current_user: User = Depends(get_current_user),
+        storage_service: FileStorageService = Depends(get_file_storage_service),
 ):
-    """
-    custom text
-    """
-    api_logger.info(f"custom text upload request: kb_id={kb_id}, parent_id={parent_id}, title={create_data.title}, content={create_data.content}, username: {current_user.username}")
-
-    # Check file content size
-    # 将内容编码为字节（UTF-8）
+    """Custom text upload"""
     content_bytes = create_data.content.encode('utf-8')
     file_size = len(content_bytes)
-    print(f"file size: {file_size} byte")
     if file_size == 0:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="The content is empty."
-        )
-    # If the file size exceeds 50MB (50 * 1024 * 1024 bytes)
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="The content is empty.")
     if file_size > settings.MAX_FILE_SIZE:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"The content size exceeds the {settings.MAX_FILE_SIZE}byte limit"
-        )
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=f"Content size exceeds {settings.MAX_FILE_SIZE} byte limit")
 
-    upload_file = file_schema.FileCreate(
-        kb_id=kb_id,
-        created_by=current_user.id,
-        parent_id=parent_id,
-        file_name=f"{create_data.title}.txt",
-        file_ext=".txt",
-        file_size=file_size,
+    upload_file_data = file_schema.FileCreate(
+        kb_id=kb_id, created_by=current_user.id, parent_id=parent_id,
+        file_name=f"{create_data.title}.txt", file_ext=".txt", file_size=file_size,
     )
-    db_file = file_service.create_file(db=db, file=upload_file, current_user=current_user)
+    db_file = file_service.create_file(db=db, file=upload_file_data, current_user=current_user)
 
-    # Construct a save path：/files/{kb_id}/{parent_id}/{file.id}{file_extension}
-    save_dir = os.path.join(settings.FILE_PATH, str(kb_id), str(parent_id))
-    Path(save_dir).mkdir(parents=True, exist_ok=True)  # Ensure that the directory exists
-    save_path = os.path.join(save_dir, f"{db_file.id}.txt")
+    # Upload to storage backend
+    file_key = generate_kb_file_key(kb_id=kb_id, file_id=db_file.id, file_ext=".txt")
+    try:
+        await storage_service.storage.upload(file_key=file_key, content=content_bytes, content_type="text/plain")
+    except Exception as e:
+        api_logger.error(f"Storage upload failed: {e}")
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"File storage failed: {str(e)}")
 
-    # Save file
-    with open(save_path, "wb") as f:
-        f.write(content_bytes)
+    db_file.file_key = file_key
+    db.commit()
+    db.refresh(db_file)
 
-    # Verify whether the file has been saved successfully
-    if not os.path.exists(save_path):
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail="File save failed"
-        )
-
-    # Create a document
     create_document_data = document_schema.DocumentCreate(
-        kb_id=kb_id,
-        created_by=current_user.id,
-        file_id=db_file.id,
-        file_name=db_file.file_name,
-        file_ext=db_file.file_ext,
-        file_size=db_file.file_size,
-        file_meta={},
-        parser_id="naive",
-        parser_config={
-            "layout_recognize": "DeepDOC",
-            "chunk_token_num": 128,
-            "delimiter": "\n",
-            "auto_keywords": 0,
-            "auto_questions": 0,
-            "html4excel": "false"
-        }
+        kb_id=kb_id, created_by=current_user.id, file_id=db_file.id,
+        file_name=db_file.file_name, file_ext=db_file.file_ext, file_size=db_file.file_size,
+        file_meta={}, parser_id="naive",
+        parser_config={"layout_recognize": "DeepDOC", "chunk_token_num": 128, "delimiter": "\n",
+                       "auto_keywords": 0, "auto_questions": 0, "html4excel": "false"}
     )
     db_document = document_service.create_document(db=db, document=create_document_data, current_user=current_user)
 
-    api_logger.info(f"custom text upload successfully: {create_data.title} (file_id: {db_file.id}, document_id: {db_document.id})")
     return success(data=jsonable_encoder(document_schema.Document.model_validate(db_document)), msg="custom text upload successful")
 
 
 @router.get("/{file_id}", response_model=Any)
 async def get_file(
         file_id: uuid.UUID,
-        db: Session = Depends(get_db)
+        db: Session = Depends(get_db),
+        storage_service: FileStorageService = Depends(get_file_storage_service),
 ) -> Any:
-    """
-    Download the file based on the file_id
-    - Query file information from the database
-    - Construct the file path and check if it exists
-    - Return a FileResponse to download the file
-    """
-    api_logger.info(f"Download the file based on the file_id: file_id={file_id}")
-
-    # 1. Query file information from the database
+    """Download file by file_id"""
     db_file = file_service.get_file_by_id(db, file_id=file_id)
     if not db_file:
-        api_logger.warning(f"The file does not exist or you do not have permission to access it: file_id={file_id}")
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail="The file does not exist or you do not have permission to access it"
-        )
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="File not found")
 
-    # 2. Construct file path：/files/{kb_id}/{parent_id}/{file.id}{file.file_ext}
-    file_path = os.path.join(
-        settings.FILE_PATH,
-        str(db_file.kb_id),
-        str(db_file.parent_id),
-        f"{db_file.id}{db_file.file_ext}"
-    )
+    if not db_file.file_key:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="File has no storage key (legacy data not migrated)")
 
-    # 3. Check if the file exists
-    if not os.path.exists(file_path):
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail="File not found (possibly deleted)"
-        )
+    try:
+        content = await storage_service.download_file(db_file.file_key)
+    except Exception as e:
+        api_logger.error(f"Storage download failed: {e}")
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="File not found in storage")
 
-    # 4.Return FileResponse (automatically handle download)
-    return FileResponse(
-        path=file_path,
-        filename=db_file.file_name,  # Use original file name
-        media_type="application/octet-stream"  # Universal binary stream type
+    import mimetypes
+    media_type = mimetypes.guess_type(db_file.file_name)[0] or "application/octet-stream"
+    return Response(
+        content=content,
+        media_type=media_type,
+        headers={"Content-Disposition": f'attachment; filename="{db_file.file_name}"'}
     )
 
 
@@ -346,50 +243,22 @@ async def update_file(
         db: Session = Depends(get_db),
         current_user: User = Depends(get_current_user)
 ):
-    """
-    Update file information (such as file name)
-    - Only specified fields such as file_name are allowed to be modified
-    """
-    api_logger.debug(f"Query the file to be updated: {file_id}")
-
-    # 1. Check if the file exists
+    """Update file information (such as file name)"""
     db_file = file_service.get_file_by_id(db, file_id=file_id)
-
     if not db_file:
-        api_logger.warning(f"The file does not exist or you do not have permission to access it: file_id={file_id}")
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail="The file does not exist or you do not have permission to access it"
-        )
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="File not found")
 
-    # 2. Update fields (only update non-null fields)
-    api_logger.debug(f"Start updating the file fields: {file_id}")
-    updated_fields = []
     for field, value in update_data.dict(exclude_unset=True).items():
         if hasattr(db_file, field):
-            old_value = getattr(db_file, field)
-            if old_value != value:
-                # update value
-                setattr(db_file, field, value)
-                updated_fields.append(f"{field}: {old_value} -> {value}")
+            setattr(db_file, field, value)
 
-    if updated_fields:
-        api_logger.debug(f"updated fields: {', '.join(updated_fields)}")
-
-    # 3. Save to database
     try:
         db.commit()
         db.refresh(db_file)
-        api_logger.info(f"The file has been successfully updated: {db_file.file_name} (ID: {db_file.id})")
     except Exception as e:
         db.rollback()
-        api_logger.error(f"File update failed: file_id={file_id} - {str(e)}")
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"File update failed: {str(e)}"
-        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"File update failed: {str(e)}")
 
-    # 4. Return the updated file
     return success(data=jsonable_encoder(file_schema.File.model_validate(db_file)), msg="File information updated successfully")
 
 
@@ -397,60 +266,43 @@ async def update_file(
 async def delete_file(
         file_id: uuid.UUID,
         db: Session = Depends(get_db),
-        current_user: User = Depends(get_current_user)
+        current_user: User = Depends(get_current_user),
+        storage_service: FileStorageService = Depends(get_file_storage_service),
 ):
-    """
-    Delete a file or folder
-    """
-    api_logger.info(f"Request to delete file: file_id={file_id}, username: {current_user.username}")
-    await _delete_file(db=db, file_id=file_id, current_user=current_user)
+    """Delete a file or folder"""
+    api_logger.info(f"Request to delete file: file_id={file_id}")
+    await _delete_file(db=db, file_id=file_id, current_user=current_user, storage_service=storage_service)
     return success(msg="File deleted successfully")
 
+
 async def _delete_file(
         file_id: uuid.UUID,
-        db: Session = Depends(get_db),
-        current_user: User = Depends(get_current_user)
+        db: Session,
+        current_user: User,
+        storage_service: FileStorageService,
 ) -> None:
-    """
-    Delete a file or folder
-    """
-    # 1. Check if the file exists
+    """Delete a file or folder from storage and database"""
     db_file = file_service.get_file_by_id(db, file_id=file_id)
-
     if not db_file:
-        api_logger.warning(f"The file does not exist or you do not have permission to access it: file_id={file_id}")
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail="The file does not exist or you do not have permission to access it"
-        )
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="File not found")
 
-    # 2. Construct physical path
-    file_path = Path(
-        settings.FILE_PATH,
-        str(db_file.kb_id),
-        str(db_file.id)
-    ) if db_file.file_ext == 'folder' else Path(
-        settings.FILE_PATH,
-        str(db_file.kb_id),
-        str(db_file.parent_id),
-        f"{db_file.id}{db_file.file_ext}"
-    )
-
-    # 3. Delete physical files/folders
-    try:
-        if file_path.exists():
-            if db_file.file_ext == 'folder':
-                shutil.rmtree(file_path)  # Recursively delete folders
-            else:
-                file_path.unlink()  # Delete a single file
-    except Exception as e:
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Failed to delete physical file/folder: {str(e)}"
-        )
-
-    # 4.Delete db_file
+    # Delete from storage backend
     if db_file.file_ext == 'folder':
+        # For folders, delete all child files from storage first
+        child_files = db.query(file_model.File).filter(file_model.File.parent_id == db_file.id).all()
+        for child in child_files:
+            if child.file_key:
+                try:
+                    await storage_service.delete_file(child.file_key)
+                except Exception as e:
+                    api_logger.warning(f"Failed to delete child file from storage: {child.file_key} - {e}")
         db.query(file_model.File).filter(file_model.File.parent_id == db_file.id).delete()
+    else:
+        if db_file.file_key:
+            try:
+                await storage_service.delete_file(db_file.file_key)
+            except Exception as e:
+                api_logger.warning(f"Failed to delete file from storage: {db_file.file_key} - {e}")
+
     db.delete(db_file)
     db.commit()

api/app/controllers/file_storage_controller.py

@@ -14,8 +14,11 @@ Routes:
 import os
 import uuid
 from typing import Any
+import httpx
+import mimetypes
+from urllib.parse import urlparse, unquote
 
-from fastapi import APIRouter, Depends, File, HTTPException, UploadFile, status
+from fastapi import APIRouter, Depends, File, HTTPException, Request, UploadFile, status
 from fastapi.responses import FileResponse, RedirectResponse
 from sqlalchemy.orm import Session
 
@@ -47,6 +50,19 @@ router = APIRouter(
 )
 
 
+def _match_scheme(request: Request, url: str) -> str:
+    """
+    将 presigned URL 的协议替换为与当前请求一致的协议（http/https）。
+    解决反向代理场景下 presigned URL 协议与请求协议不匹配的问题。
+    """
+    incoming_scheme = request.headers.get("x-forwarded-proto") or request.url.scheme
+    if url.startswith("http://") and incoming_scheme == "https":
+        return "https://" + url[7:]
+    if url.startswith("https://") and incoming_scheme == "http":
+        return "http://" + url[8:]
+    return url
+
+
 @router.post("/files", response_model=ApiResponse)
 async def upload_file(
     file: UploadFile = File(...),
@@ -78,7 +94,7 @@ async def upload_file(
 
     if file_size > settings.MAX_FILE_SIZE:
         raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
+            status_code=status.HTTP_413_CONTENT_TOO_LARGE,
             detail=f"The file size exceeds the {settings.MAX_FILE_SIZE} byte limit"
         )
 
@@ -159,7 +175,6 @@ async def upload_file_with_share_token(
     
     # Get share and release info from share_token
     service = ReleaseShareService(db)
-    share_info = service.get_shared_release_info(share_token=share_data.share_token)
     
     # Get share object to access app_id
     share = service.repo.get_by_share_token(share_data.share_token)
@@ -278,8 +293,104 @@ async def upload_file_with_share_token(
     )
 
 
+@router.get("/files/info-by-url", response_model=ApiResponse)
+async def get_file_info_by_url(
+        url: str,
+):
+    """
+    Get file information by network URL (no authentication required).
+
+    Fetches file metadata from a remote URL via HTTP HEAD request.
+    Falls back to GET request if HEAD is not supported.
+    Returns file type, name, and size.
+
+    Args:
+        url: The network URL of the file.
+
+    Returns:
+        ApiResponse with file information.
+    """
+    api_logger.info(f"File info by URL request: url={url}")
+
+    try:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            # Try HEAD request first
+            response = await client.head(url, follow_redirects=True)
+
+            # If HEAD fails, try GET request (some servers don't support HEAD)
+            if response.status_code != 200:
+                api_logger.info(f"HEAD request failed with {response.status_code}, trying GET request")
+                response = await client.get(url, follow_redirects=True)
+                
+                if response.status_code != 200:
+                    api_logger.error(f"Failed to fetch file info: HTTP {response.status_code}")
+                    raise HTTPException(
+                        status_code=status.HTTP_400_BAD_REQUEST,
+                        detail=f"Unable to access file: HTTP {response.status_code}"
+                    )
+
+            # Get file size from Content-Length header or actual content
+            file_size = response.headers.get("Content-Length")
+            if file_size:
+                file_size = int(file_size)
+            elif hasattr(response, 'content'):
+                file_size = len(response.content)
+            else:
+                file_size = None
+
+            # Get content type from Content-Type header
+            content_type = response.headers.get("Content-Type", "application/octet-stream")
+            # Remove charset and other parameters from content type
+            content_type = content_type.split(';')[0].strip()
+
+            # Extract filename from Content-Disposition or URL
+            file_name = None
+            content_disposition = response.headers.get("Content-Disposition")
+            if content_disposition and "filename=" in content_disposition:
+                parts = content_disposition.split("filename=")
+                if len(parts) > 1:
+                    file_name = parts[1].strip('"').strip("'")
+
+            if not file_name:
+                parsed_url = urlparse(url)
+                file_name = unquote(os.path.basename(parsed_url.path)) or "unknown"
+
+            # Extract file extension from filename
+            _, file_ext = os.path.splitext(file_name)
+            
+            # If no extension found, infer from content type
+            if not file_ext:
+                ext = mimetypes.guess_extension(content_type)
+                if ext:
+                    file_ext = ext
+                    file_name = f"{file_name}{file_ext}"
+
+            api_logger.info(f"File info retrieved: name={file_name}, size={file_size}, type={content_type}")
+
+            return success(
+                data={
+                    "url": url,
+                    "file_name": file_name,
+                    "file_ext": file_ext.lower() if file_ext else "",
+                    "file_size": file_size,
+                    "content_type": content_type,
+                },
+                msg="File information retrieved successfully"
+            )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        api_logger.error(f"Unexpected error: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to retrieve file information: {str(e)}"
+        )
+
+
 @router.get("/files/{file_id}", response_model=Any)
 async def download_file(
+    request: Request,
     file_id: uuid.UUID,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
@@ -327,6 +438,7 @@ async def download_file(
     else:
         try:
             presigned_url = await storage_service.get_file_url(file_key, expires=3600)
+            presigned_url = _match_scheme(request, presigned_url)
             api_logger.info(f"Redirecting to presigned URL: file_key={file_key}")
             return RedirectResponse(url=presigned_url, status_code=status.HTTP_302_FOUND)
         except FileNotFoundError:
@@ -400,6 +512,7 @@ async def delete_file(
 
 @router.get("/files/{file_id}/url", response_model=ApiResponse)
 async def get_file_url(
+    request: Request,
     file_id: uuid.UUID,
     expires: int = None,
     permanent: bool = False,
@@ -461,8 +574,13 @@ async def get_file_url(
             # For local storage, generate signed URL with expiration
             url = generate_signed_url(str(file_id), expires)
         else:
-            # For remote storage (OSS/S3), get presigned URL
-            url = await storage_service.get_file_url(file_key, expires=expires)
+            # For remote storage (OSS/S3), get presigned URL with forced download
+            url = await storage_service.get_file_url(
+                file_key,
+                expires=expires,
+                file_name=file_metadata.file_name,
+            )
+            url = _match_scheme(request, url)
 
         api_logger.info(f"Generated file URL: file_id={file_id}")
         return success(
@@ -482,8 +600,54 @@ async def get_file_url(
         )
 
 
+@router.get("/files/{file_id}/public-url", response_model=ApiResponse)
+async def get_permanent_file_url(
+    file_id: uuid.UUID,
+    db: Session = Depends(get_db),
+    storage_service: FileStorageService = Depends(get_file_storage_service),
+):
+    """
+    获取文件的永久公开 URL（无过期时间）。
+
+    - 本地存储：返回 API 永久访问地址（基于 FILE_LOCAL_SERVER_URL 配置）
+    - 远程存储（OSS/S3）：返回 bucket 公读地址（需 bucket 已配置公共读权限）
+    """
+    file_metadata = db.query(FileMetadata).filter(FileMetadata.id == file_id).first()
+    if not file_metadata:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="The file does not exist")
+
+    if file_metadata.status != "completed":
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST,
+                            detail=f"File upload not completed, status: {file_metadata.status}")
+
+    file_key = file_metadata.file_key
+    storage = storage_service.storage
+
+    try:
+        if isinstance(storage, LocalStorage):
+            url = f"{settings.FILE_LOCAL_SERVER_URL}/storage/permanent/{file_id}"
+        else:
+            url = await storage.get_permanent_url(file_key)
+            if not url:
+                raise HTTPException(status_code=status.HTTP_501_NOT_IMPLEMENTED,
+                                    detail="Permanent URL not supported for current storage backend")
+
+        api_logger.info(f"Generated permanent URL: file_id={file_id}")
+        return success(
+            data={"url": url, "expires_in": None, "permanent": True, "file_name": file_metadata.file_name},
+            msg="Permanent file URL generated successfully"
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        api_logger.error(f"Failed to generate permanent URL: {e}")
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                            detail=f"Failed to generate permanent URL: {str(e)}")
+
+
 @router.get("/public/{file_id}", response_model=Any)
 async def public_download_file(
+    request: Request,
     file_id: uuid.UUID,
     expires: int = 0,
     signature: str = "",
@@ -555,6 +719,7 @@ async def public_download_file(
         # For remote storage, redirect to presigned URL
         try:
             presigned_url = await storage_service.get_file_url(file_key, expires=3600)
+            presigned_url = _match_scheme(request, presigned_url)
             return RedirectResponse(url=presigned_url, status_code=status.HTTP_302_FOUND)
         except Exception as e:
             api_logger.error(f"Failed to get presigned URL: {e}")
@@ -566,6 +731,7 @@ async def public_download_file(
 
 @router.get("/permanent/{file_id}", response_model=Any)
 async def permanent_download_file(
+    request: Request,
     file_id: uuid.UUID,
     db: Session = Depends(get_db),
     storage_service: FileStorageService = Depends(get_file_storage_service),
@@ -624,7 +790,8 @@ async def permanent_download_file(
         # For remote storage, redirect to presigned URL with long expiration
         try:
             # Use a very long expiration (7 days max for most cloud providers)
-            presigned_url = await storage_service.get_file_url(file_key, expires=604800)
+            presigned_url = await storage_service.get_file_url(file_key, expires=604800, file_name=file_metadata.file_name)
+            presigned_url = _match_scheme(request, presigned_url)
             return RedirectResponse(url=presigned_url, status_code=status.HTTP_302_FOUND)
         except Exception as e:
             api_logger.error(f"Failed to get presigned URL: {e}")
@@ -632,3 +799,44 @@ async def permanent_download_file(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
                 detail=f"Failed to retrieve file: {str(e)}"
             )
+
+
+@router.get("/files/{file_id}/status", response_model=ApiResponse)
+async def get_file_status(
+    file_id: uuid.UUID,
+    db: Session = Depends(get_db),
+):
+    """
+    Get file upload/processing status (no authentication required).
+    
+    This endpoint is used to check if a file (e.g., TTS audio) is ready.
+    Returns status: pending, completed, or failed.
+    
+    Args:
+        file_id: The UUID of the file.
+        db: Database session.
+    
+    Returns:
+        ApiResponse with file status and metadata.
+    """
+    api_logger.info(f"File status request: file_id={file_id}")
+    
+    # Query file metadata from database
+    file_metadata = db.query(FileMetadata).filter(FileMetadata.id == file_id).first()
+    if not file_metadata:
+        api_logger.warning(f"File not found in database: file_id={file_id}")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="The file does not exist"
+        )
+    
+    return success(
+        data={
+            "file_id": str(file_id),
+            "status": file_metadata.status,
+            "file_name": file_metadata.file_name,
+            "file_size": file_metadata.file_size,
+            "content_type": file_metadata.content_type,
+        },
+        msg="File status retrieved successfully"
+    )

api/app/controllers/home_page_controller.py

@@ -3,9 +3,10 @@ from sqlalchemy.orm import Session
 
 from app.core.config import settings
 from app.core.response_utils import success
-from app.db import get_db
+from app.db import get_db, SessionLocal
 from app.dependencies import get_current_user
 from app.models.user_model import User
+from app.repositories.home_page_repository import HomePageRepository
 from app.schemas.response_schema import ApiResponse
 from app.services.home_page_service import HomePageService
 
@@ -31,9 +32,32 @@ def get_workspace_list(
 
 @router.get("/version", response_model=ApiResponse)
 def get_system_version():
-    """获取系统版本号+说明"""
-    current_version = settings.SYSTEM_VERSION
-    version_info = HomePageService.load_version_introduction(current_version)
+    """获取系统版本号 + 说明"""
+    current_version = None
+    version_info = None
+    
+    # 1️⃣ 优先从数据库获取最新已发布的版本
+    try:
+        db = SessionLocal()
+        try:
+            current_version, version_info = HomePageRepository.get_latest_version_introduction(db)
+        finally:
+            db.close()
+    except Exception as e:
+        pass
+    
+    # 2️⃣ 降级：使用环境变量中的版本号
+    if not current_version:
+        current_version = settings.SYSTEM_VERSION
+        version_info = HomePageService.load_version_introduction(current_version)
+    
+    # 3️⃣ 如果数据库和 JSON 都没有，返回基本信息
+    if not version_info:
+        version_info = {
+            "introduction": {"codeName": "", "releaseDate": "", "upgradePosition": "", "coreUpgrades": []},
+            "introduction_en": {"codeName": "", "releaseDate": "", "upgradePosition": "", "coreUpgrades": []}
+        }
+    
     return success(
         data={
             "version": current_version,

api/app/controllers/i18n_controller.py

@@ -0,0 +1,833 @@
+"""
+I18n Management API Controller
+
+This module provides management APIs for:
+- Language management (list, get, add, update languages)
+- Translation management (get, update, reload translations)
+"""
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+from typing import Callable, Optional
+
+from app.core.logging_config import get_api_logger
+from app.core.response_utils import success
+from app.db import get_db
+from app.dependencies import get_current_user, get_current_superuser
+from app.i18n.dependencies import get_translator
+from app.i18n.service import get_translation_service
+from app.models.user_model import User
+from app.schemas.i18n_schema import (
+    LanguageInfo,
+    LanguageListResponse,
+    LanguageCreateRequest,
+    LanguageUpdateRequest,
+    TranslationResponse,
+    TranslationUpdateRequest,
+    MissingTranslationsResponse,
+    ReloadResponse
+)
+from app.schemas.response_schema import ApiResponse
+
+api_logger = get_api_logger()
+
+router = APIRouter(
+    prefix="/i18n",
+    tags=["I18n Management"],
+)
+
+
+# ============================================================================
+# Language Management APIs
+# ============================================================================
+
+@router.get("/languages", response_model=ApiResponse)
+def get_languages(
+    t: Callable = Depends(get_translator),
+    current_user: User = Depends(get_current_user)
+):
+    """
+    Get list of all supported languages.
+    
+    Returns:
+        List of language information including code, name, and status
+    """
+    api_logger.info(f"Get languages request from user: {current_user.username}")
+    
+    from app.core.config import settings
+    translation_service = get_translation_service()
+    
+    # Get available locales from translation service
+    available_locales = translation_service.get_available_locales()
+    
+    # Build language info list
+    languages = []
+    for locale in available_locales:
+        is_default = locale == settings.I18N_DEFAULT_LANGUAGE
+        is_enabled = locale in settings.I18N_SUPPORTED_LANGUAGES
+        
+        # Get native names
+        native_names = {
+            "zh": "中文（简体）",
+            "en": "English",
+            "ja": "日本語",
+            "ko": "한국어",
+            "fr": "Français",
+            "de": "Deutsch",
+            "es": "Español"
+        }
+        
+        language_info = LanguageInfo(
+            code=locale,
+            name=f"{locale.upper()}",
+            native_name=native_names.get(locale, locale),
+            is_enabled=is_enabled,
+            is_default=is_default
+        )
+        languages.append(language_info)
+    
+    response = LanguageListResponse(languages=languages)
+    
+    api_logger.info(f"Returning {len(languages)} languages")
+    return success(data=response.dict(), msg=t("common.success.retrieved"))
+
+
+@router.get("/languages/{locale}", response_model=ApiResponse)
+def get_language(
+    locale: str,
+    t: Callable = Depends(get_translator),
+    current_user: User = Depends(get_current_user)
+):
+    """
+    Get information about a specific language.
+    
+    Args:
+        locale: Language code (e.g., 'zh', 'en')
+        
+    Returns:
+        Language information
+    """
+    api_logger.info(f"Get language info request: locale={locale}, user={current_user.username}")
+    
+    from app.core.config import settings
+    translation_service = get_translation_service()
+    
+    # Check if locale exists
+    available_locales = translation_service.get_available_locales()
+    if locale not in available_locales:
+        api_logger.warning(f"Language not found: {locale}")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=t("i18n.language.not_found", locale=locale)
+        )
+    
+    # Build language info
+    is_default = locale == settings.I18N_DEFAULT_LANGUAGE
+    is_enabled = locale in settings.I18N_SUPPORTED_LANGUAGES
+    
+    native_names = {
+        "zh": "中文（简体）",
+        "en": "English",
+        "ja": "日本語",
+        "ko": "한국어",
+        "fr": "Français",
+        "de": "Deutsch",
+        "es": "Español"
+    }
+    
+    language_info = LanguageInfo(
+        code=locale,
+        name=f"{locale.upper()}",
+        native_name=native_names.get(locale, locale),
+        is_enabled=is_enabled,
+        is_default=is_default
+    )
+    
+    api_logger.info(f"Returning language info for: {locale}")
+    return success(data=language_info.dict(), msg=t("common.success.retrieved"))
+
+
+@router.post("/languages", response_model=ApiResponse)
+def add_language(
+    request: LanguageCreateRequest,
+    t: Callable = Depends(get_translator),
+    current_user: User = Depends(get_current_superuser)
+):
+    """
+    Add a new language (admin only).
+    
+    Note: This endpoint validates the request but actual language addition
+    requires creating translation files in the locales directory.
+    
+    Args:
+        request: Language creation request
+        
+    Returns:
+        Success message
+    """
+    api_logger.info(
+        f"Add language request: code={request.code}, admin={current_user.username}"
+    )
+    
+    from app.core.config import settings
+    translation_service = get_translation_service()
+    
+    # Check if language already exists
+    available_locales = translation_service.get_available_locales()
+    if request.code in available_locales:
+        api_logger.warning(f"Language already exists: {request.code}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=t("i18n.language.already_exists", locale=request.code)
+        )
+    
+    # Note: Actual language addition requires creating translation files
+    # This endpoint serves as a validation and documentation point
+    
+    api_logger.info(
+        f"Language addition validated: {request.code}. "
+        "Translation files need to be created manually."
+    )
+    
+    return success(
+        msg=t(
+            "i18n.language.add_instructions",
+            locale=request.code,
+            dir=settings.I18N_CORE_LOCALES_DIR
+        )
+    )
+
+
+@router.put("/languages/{locale}", response_model=ApiResponse)
+def update_language(
+    locale: str,
+    request: LanguageUpdateRequest,
+    t: Callable = Depends(get_translator),
+    current_user: User = Depends(get_current_superuser)
+):
+    """
+    Update language configuration (admin only).
+    
+    Note: This endpoint validates the request but actual configuration
+    changes require updating environment variables or config files.
+    
+    Args:
+        locale: Language code
+        request: Language update request
+        
+    Returns:
+        Success message
+    """
+    api_logger.info(
+        f"Update language request: locale={locale}, admin={current_user.username}"
+    )
+    
+    translation_service = get_translation_service()
+    
+    # Check if language exists
+    available_locales = translation_service.get_available_locales()
+    if locale not in available_locales:
+        api_logger.warning(f"Language not found: {locale}")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=t("i18n.language.not_found", locale=locale)
+        )
+    
+    # Note: Actual configuration changes require updating settings
+    # This endpoint serves as a validation and documentation point
+    
+    api_logger.info(
+        f"Language update validated: {locale}. "
+        "Configuration changes require environment variable updates."
+    )
+    
+    return success(msg=t("i18n.language.update_instructions", locale=locale))
+
+
+# ============================================================================
+# Translation Management APIs
+# ============================================================================
+
+@router.get("/translations", response_model=ApiResponse)
+def get_all_translations(
+    locale: Optional[str] = None,
+    t: Callable = Depends(get_translator),
+    current_user: User = Depends(get_current_user)
+):
+    """
+    Get all translations for all or specific locale.
+    
+    Args:
+        locale: Optional locale filter
+        
+    Returns:
+        All translations organized by locale and namespace
+    """
+    api_logger.info(
+        f"Get all translations request: locale={locale}, user={current_user.username}"
+    )
+    
+    translation_service = get_translation_service()
+    
+    if locale:
+        # Get translations for specific locale
+        available_locales = translation_service.get_available_locales()
+        if locale not in available_locales:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=t("i18n.language.not_found", locale=locale)
+            )
+        
+        translations = {
+            locale: translation_service._cache.get(locale, {})
+        }
+    else:
+        # Get all translations
+        translations = translation_service._cache
+    
+    response = TranslationResponse(translations=translations)
+    
+    api_logger.info(f"Returning translations for: {locale or 'all locales'}")
+    return success(data=response.dict(), msg=t("common.success.retrieved"))
+
+
+@router.get("/translations/{locale}", response_model=ApiResponse)
+def get_locale_translations(
+    locale: str,
+    t: Callable = Depends(get_translator),
+    current_user: User = Depends(get_current_user)
+):
+    """
+    Get all translations for a specific locale.
+    
+    Args:
+        locale: Language code
+        
+    Returns:
+        All translations for the locale organized by namespace
+    """
+    api_logger.info(
+        f"Get locale translations request: locale={locale}, user={current_user.username}"
+    )
+    
+    translation_service = get_translation_service()
+    
+    # Check if locale exists
+    available_locales = translation_service.get_available_locales()
+    if locale not in available_locales:
+        api_logger.warning(f"Language not found: {locale}")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=t("i18n.language.not_found", locale=locale)
+        )
+    
+    translations = translation_service._cache.get(locale, {})
+    
+    api_logger.info(f"Returning {len(translations)} namespaces for locale: {locale}")
+    return success(data={"locale": locale, "translations": translations}, msg=t("common.success.retrieved"))
+
+
+@router.get("/translations/{locale}/{namespace}", response_model=ApiResponse)
+def get_namespace_translations(
+    locale: str,
+    namespace: str,
+    t: Callable = Depends(get_translator),
+    current_user: User = Depends(get_current_user)
+):
+    """
+    Get translations for a specific namespace in a locale.
+    
+    Args:
+        locale: Language code
+        namespace: Translation namespace (e.g., 'common', 'auth')
+        
+    Returns:
+        Translations for the specified namespace
+    """
+    api_logger.info(
+        f"Get namespace translations request: locale={locale}, "
+        f"namespace={namespace}, user={current_user.username}"
+    )
+    
+    translation_service = get_translation_service()
+    
+    # Check if locale exists
+    available_locales = translation_service.get_available_locales()
+    if locale not in available_locales:
+        api_logger.warning(f"Language not found: {locale}")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=t("i18n.language.not_found", locale=locale)
+        )
+    
+    # Get namespace translations
+    locale_translations = translation_service._cache.get(locale, {})
+    namespace_translations = locale_translations.get(namespace, {})
+    
+    if not namespace_translations:
+        api_logger.warning(f"Namespace not found: {namespace} in locale: {locale}")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=t("i18n.namespace.not_found", namespace=namespace, locale=locale)
+        )
+    
+    api_logger.info(
+        f"Returning translations for namespace: {namespace} in locale: {locale}"
+    )
+    return success(
+        data={
+            "locale": locale,
+            "namespace": namespace,
+            "translations": namespace_translations
+        },
+        msg=t("common.success.retrieved")
+    )
+
+
+@router.put("/translations/{locale}/{key:path}", response_model=ApiResponse)
+def update_translation(
+    locale: str,
+    key: str,
+    request: TranslationUpdateRequest,
+    t: Callable = Depends(get_translator),
+    current_user: User = Depends(get_current_superuser)
+):
+    """
+    Update a single translation (admin only).
+    
+    Note: This endpoint validates the request but actual translation updates
+    require modifying translation files in the locales directory.
+    
+    Args:
+        locale: Language code
+        key: Translation key (format: "namespace.key.subkey")
+        request: Translation update request
+        
+    Returns:
+        Success message
+    """
+    api_logger.info(
+        f"Update translation request: locale={locale}, key={key}, "
+        f"admin={current_user.username}"
+    )
+    
+    translation_service = get_translation_service()
+    
+    # Check if locale exists
+    available_locales = translation_service.get_available_locales()
+    if locale not in available_locales:
+        api_logger.warning(f"Language not found: {locale}")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=t("i18n.language.not_found", locale=locale)
+        )
+    
+    # Validate key format
+    if "." not in key:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=t("i18n.translation.invalid_key_format", key=key)
+        )
+    
+    # Note: Actual translation updates require modifying JSON files
+    # This endpoint serves as a validation and documentation point
+    
+    api_logger.info(
+        f"Translation update validated: {locale}/{key}. "
+        "Translation files need to be updated manually."
+    )
+    
+    return success(
+        msg=t("i18n.translation.update_instructions", locale=locale, key=key)
+    )
+
+
+@router.get("/translations/missing", response_model=ApiResponse)
+def get_missing_translations(
+    locale: Optional[str] = None,
+    t: Callable = Depends(get_translator),
+    current_user: User = Depends(get_current_user)
+):
+    """
+    Get list of missing translations.
+    
+    Compares translations across locales to find missing keys.
+    
+    Args:
+        locale: Optional locale to check (defaults to checking all non-default locales)
+        
+    Returns:
+        List of missing translation keys
+    """
+    api_logger.info(
+        f"Get missing translations request: locale={locale}, user={current_user.username}"
+    )
+    
+    from app.core.config import settings
+    translation_service = get_translation_service()
+    
+    default_locale = settings.I18N_DEFAULT_LANGUAGE
+    available_locales = translation_service.get_available_locales()
+    
+    # Get default locale translations as reference
+    default_translations = translation_service._cache.get(default_locale, {})
+    
+    # Collect all keys from default locale
+    def collect_keys(data, prefix=""):
+        keys = []
+        for key, value in data.items():
+            full_key = f"{prefix}.{key}" if prefix else key
+            if isinstance(value, dict):
+                keys.extend(collect_keys(value, full_key))
+            else:
+                keys.append(full_key)
+        return keys
+    
+    default_keys = set()
+    for namespace, translations in default_translations.items():
+        namespace_keys = collect_keys(translations, namespace)
+        default_keys.update(namespace_keys)
+    
+    # Find missing keys in target locale(s)
+    missing_by_locale = {}
+    
+    target_locales = [locale] if locale else [
+        loc for loc in available_locales if loc != default_locale
+    ]
+    
+    for target_locale in target_locales:
+        if target_locale not in available_locales:
+            continue
+        
+        target_translations = translation_service._cache.get(target_locale, {})
+        target_keys = set()
+        
+        for namespace, translations in target_translations.items():
+            namespace_keys = collect_keys(translations, namespace)
+            target_keys.update(namespace_keys)
+        
+        missing_keys = default_keys - target_keys
+        if missing_keys:
+            missing_by_locale[target_locale] = sorted(list(missing_keys))
+    
+    response = MissingTranslationsResponse(missing_translations=missing_by_locale)
+    
+    total_missing = sum(len(keys) for keys in missing_by_locale.values())
+    api_logger.info(f"Found {total_missing} missing translations across {len(missing_by_locale)} locales")
+    
+    return success(data=response.dict(), msg=t("common.success.retrieved"))
+
+
+@router.post("/reload", response_model=ApiResponse)
+def reload_translations(
+    locale: Optional[str] = None,
+    t: Callable = Depends(get_translator),
+    current_user: User = Depends(get_current_superuser)
+):
+    """
+    Trigger hot reload of translation files (admin only).
+    
+    Args:
+        locale: Optional locale to reload (defaults to reloading all locales)
+        
+    Returns:
+        Reload status and statistics
+    """
+    api_logger.info(
+        f"Reload translations request: locale={locale or 'all'}, "
+        f"admin={current_user.username}"
+    )
+    
+    from app.core.config import settings
+    
+    if not settings.I18N_ENABLE_HOT_RELOAD:
+        api_logger.warning("Hot reload is disabled in configuration")
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=t("i18n.reload.disabled")
+        )
+    
+    translation_service = get_translation_service()
+    
+    try:
+        # Reload translations
+        translation_service.reload(locale)
+        
+        # Get statistics
+        available_locales = translation_service.get_available_locales()
+        reloaded_locales = [locale] if locale else available_locales
+        
+        response = ReloadResponse(
+            success=True,
+            reloaded_locales=reloaded_locales,
+            total_locales=len(available_locales)
+        )
+        
+        api_logger.info(
+            f"Successfully reloaded translations for: {', '.join(reloaded_locales)}"
+        )
+        
+        return success(data=response.dict(), msg=t("i18n.reload.success"))
+        
+    except Exception as e:
+        api_logger.error(f"Failed to reload translations: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=t("i18n.reload.failed", error=str(e))
+        )
+
+
+# ============================================================================
+# Performance Monitoring APIs
+# ============================================================================
+
+@router.get("/metrics", response_model=ApiResponse)
+def get_metrics(
+    t: Callable = Depends(get_translator),
+    current_user: User = Depends(get_current_superuser)
+):
+    """
+    Get i18n performance metrics (admin only).
+    
+    Returns:
+        Performance metrics including:
+        - Request counts
+        - Missing translations
+        - Timing statistics
+        - Locale usage
+        - Error counts
+    """
+    api_logger.info(f"Get metrics request: admin={current_user.username}")
+    
+    translation_service = get_translation_service()
+    metrics = translation_service.get_metrics_summary()
+    
+    api_logger.info("Returning i18n metrics")
+    return success(data=metrics, msg=t("common.success.retrieved"))
+
+
+@router.get("/metrics/cache", response_model=ApiResponse)
+def get_cache_stats(
+    t: Callable = Depends(get_translator),
+    current_user: User = Depends(get_current_superuser)
+):
+    """
+    Get cache statistics (admin only).
+    
+    Returns:
+        Cache statistics including:
+        - Hit/miss rates
+        - LRU cache performance
+        - Loaded locales
+        - Memory usage
+    """
+    api_logger.info(f"Get cache stats request: admin={current_user.username}")
+    
+    translation_service = get_translation_service()
+    cache_stats = translation_service.get_cache_stats()
+    memory_usage = translation_service.get_memory_usage()
+    
+    data = {
+        "cache": cache_stats,
+        "memory": memory_usage
+    }
+    
+    api_logger.info("Returning cache statistics")
+    return success(data=data, msg=t("common.success.retrieved"))
+
+
+@router.get("/metrics/prometheus")
+def get_prometheus_metrics(
+    current_user: User = Depends(get_current_superuser)
+):
+    """
+    Get metrics in Prometheus format (admin only).
+    
+    Returns:
+        Prometheus-formatted metrics as plain text
+    """
+    api_logger.info(f"Get Prometheus metrics request: admin={current_user.username}")
+    
+    from app.i18n.metrics import get_metrics
+    metrics = get_metrics()
+    prometheus_output = metrics.export_prometheus()
+    
+    from fastapi.responses import PlainTextResponse
+    return PlainTextResponse(content=prometheus_output)
+
+
+@router.post("/metrics/reset", response_model=ApiResponse)
+def reset_metrics(
+    t: Callable = Depends(get_translator),
+    current_user: User = Depends(get_current_superuser)
+):
+    """
+    Reset all metrics (admin only).
+    
+    Returns:
+        Success message
+    """
+    api_logger.info(f"Reset metrics request: admin={current_user.username}")
+    
+    from app.i18n.metrics import get_metrics
+    metrics = get_metrics()
+    metrics.reset()
+    
+    translation_service = get_translation_service()
+    translation_service.cache.reset_stats()
+    
+    api_logger.info("Metrics reset completed")
+    return success(msg=t("i18n.metrics.reset_success"))
+
+
+# ============================================================================
+# Missing Translation Logging and Reporting APIs
+# ============================================================================
+
+@router.get("/logs/missing", response_model=ApiResponse)
+def get_missing_translation_logs(
+    locale: Optional[str] = None,
+    limit: Optional[int] = 100,
+    t: Callable = Depends(get_translator),
+    current_user: User = Depends(get_current_superuser)
+):
+    """
+    Get missing translation logs (admin only).
+    
+    Returns logged missing translations with context information.
+    
+    Args:
+        locale: Optional locale filter
+        limit: Maximum number of entries to return (default: 100)
+        
+    Returns:
+        Missing translation logs with context
+    """
+    api_logger.info(
+        f"Get missing translation logs request: locale={locale}, "
+        f"limit={limit}, admin={current_user.username}"
+    )
+    
+    translation_service = get_translation_service()
+    translation_logger = translation_service.translation_logger
+    
+    # Get missing translations
+    missing_translations = translation_logger.get_missing_translations(locale)
+    
+    # Get missing with context
+    missing_with_context = translation_logger.get_missing_with_context(locale, limit)
+    
+    # Get statistics
+    statistics = translation_logger.get_statistics()
+    
+    data = {
+        "missing_translations": missing_translations,
+        "recent_context": missing_with_context,
+        "statistics": statistics
+    }
+    
+    api_logger.info(
+        f"Returning {statistics['total_missing']} missing translations"
+    )
+    return success(data=data, msg=t("common.success.retrieved"))
+
+
+@router.get("/logs/missing/report", response_model=ApiResponse)
+def generate_missing_translation_report(
+    locale: Optional[str] = None,
+    t: Callable = Depends(get_translator),
+    current_user: User = Depends(get_current_superuser)
+):
+    """
+    Generate a comprehensive missing translation report (admin only).
+    
+    Args:
+        locale: Optional locale filter
+        
+    Returns:
+        Comprehensive report with missing translations and statistics
+    """
+    api_logger.info(
+        f"Generate missing translation report request: locale={locale}, "
+        f"admin={current_user.username}"
+    )
+    
+    translation_service = get_translation_service()
+    translation_logger = translation_service.translation_logger
+    
+    # Generate report
+    report = translation_logger.generate_report(locale)
+    
+    api_logger.info(
+        f"Generated report with {report['total_missing']} missing translations"
+    )
+    return success(data=report, msg=t("common.success.retrieved"))
+
+
+@router.post("/logs/missing/export", response_model=ApiResponse)
+def export_missing_translations(
+    locale: Optional[str] = None,
+    t: Callable = Depends(get_translator),
+    current_user: User = Depends(get_current_superuser)
+):
+    """
+    Export missing translations to JSON file (admin only).
+    
+    Args:
+        locale: Optional locale filter
+        
+    Returns:
+        Export status and file path
+    """
+    api_logger.info(
+        f"Export missing translations request: locale={locale}, "
+        f"admin={current_user.username}"
+    )
+    
+    from datetime import datetime
+    translation_service = get_translation_service()
+    translation_logger = translation_service.translation_logger
+    
+    # Generate filename with timestamp
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    locale_suffix = f"_{locale}" if locale else "_all"
+    output_file = f"logs/i18n/missing_translations{locale_suffix}_{timestamp}.json"
+    
+    # Export to file
+    translation_logger.export_to_json(output_file)
+    
+    api_logger.info(f"Missing translations exported to: {output_file}")
+    return success(
+        data={"file_path": output_file},
+        msg=t("i18n.logs.export_success", file=output_file)
+    )
+
+
+@router.delete("/logs/missing", response_model=ApiResponse)
+def clear_missing_translation_logs(
+    locale: Optional[str] = None,
+    t: Callable = Depends(get_translator),
+    current_user: User = Depends(get_current_superuser)
+):
+    """
+    Clear missing translation logs (admin only).
+    
+    Args:
+        locale: Optional locale to clear (clears all if not specified)
+        
+    Returns:
+        Success message
+    """
+    api_logger.info(
+        f"Clear missing translation logs request: locale={locale or 'all'}, "
+        f"admin={current_user.username}"
+    )
+    
+    translation_service = get_translation_service()
+    translation_logger = translation_service.translation_logger
+    
+    # Clear logs
+    translation_logger.clear(locale)
+    
+    api_logger.info(f"Cleared missing translation logs for: {locale or 'all locales'}")
+    return success(msg=t("i18n.logs.clear_success"))

api/app/controllers/implicit_memory_controller.py

@@ -122,6 +122,48 @@ def validate_confidence_threshold(threshold: float) -> None:
         raise ValueError("confidence_threshold must be between 0.0 and 1.0")
 
 
+@router.get("/check-data/{end_user_id}", response_model=ApiResponse)
+@cur_workspace_access_guard()
+async def check_user_data_exists(
+    end_user_id: str,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user)
+) -> ApiResponse:
+    """
+    检查用户画像数据是否存在
+    
+    Args:
+        end_user_id: 目标用户ID
+        
+    Returns:
+        数据存在状态
+    """
+    api_logger.info(f"检查用户画像数据是否存在: {end_user_id}")
+    
+    try:
+        # Validate inputs
+        validate_user_id(end_user_id)
+        
+        # Create service with user-specific config
+        service = ImplicitMemoryService(db=db, end_user_id=end_user_id)
+        
+        # Get cached profile
+        cached_profile = await service.get_cached_profile(end_user_id=end_user_id, db=db)
+        
+        if cached_profile is None:
+            api_logger.info(f"用户 {end_user_id} 的画像数据不存在")
+            return success(
+                data={"exists": False},
+                msg="画像数据不存在，请点击右上角刷新进行初始化"
+            )
+        
+        api_logger.info(f"用户 {end_user_id} 的画像数据存在")
+        return success(data={"exists": True}, msg="画像数据已存在")
+        
+    except Exception as e:
+        return handle_implicit_memory_error(e, "检查画像数据", end_user_id)
+
+
 @router.get("/preferences/{end_user_id}", response_model=ApiResponse)
 @cur_workspace_access_guard()
 async def get_preference_tags(
@@ -159,12 +201,8 @@ async def get_preference_tags(
         cached_profile = await service.get_cached_profile(end_user_id=end_user_id, db=db)
         
         if cached_profile is None:
-            api_logger.info(f"用户 {end_user_id} 的画像缓存不存在或已过期")
-            return fail(
-                BizCode.NOT_FOUND,
-                "画像缓存不存在或已过期，请右上角刷新生成新画像",
-                ""
-            )
+            api_logger.info(f"用户 {end_user_id} 的画像数据不存在")
+            return fail(BizCode.NOT_FOUND, "", "")
         
         # Extract preferences from cache
         preferences = cached_profile.get("preferences", [])
@@ -230,12 +268,8 @@ async def get_dimension_portrait(
         cached_profile = await service.get_cached_profile(end_user_id=end_user_id, db=db)
         
         if cached_profile is None:
-            api_logger.info(f"用户 {end_user_id} 的画像缓存不存在或已过期")
-            return fail(
-                BizCode.NOT_FOUND,
-                "画像缓存不存在或已过期，请右上角刷新生成新画像",
-                ""
-            )
+            api_logger.info(f"用户 {end_user_id} 的画像数据不存在")
+            return fail(BizCode.NOT_FOUND, "", "")
         
         # Extract portrait from cache
         portrait = cached_profile.get("portrait", {})
@@ -278,12 +312,8 @@ async def get_interest_area_distribution(
         cached_profile = await service.get_cached_profile(end_user_id=end_user_id, db=db)
         
         if cached_profile is None:
-            api_logger.info(f"用户 {end_user_id} 的画像缓存不存在或已过期")
-            return fail(
-                BizCode.NOT_FOUND,
-                "画像缓存不存在或已过期，请右上角刷新生成新画像",
-                ""
-            )
+            api_logger.info(f"用户 {end_user_id} 的画像数据不存在")
+            return fail(BizCode.NOT_FOUND, "", "")
         
         # Extract interest areas from cache
         interest_areas = cached_profile.get("interest_areas", {})
@@ -330,12 +360,8 @@ async def get_behavior_habits(
         cached_profile = await service.get_cached_profile(end_user_id=end_user_id, db=db)
         
         if cached_profile is None:
-            api_logger.info(f"用户 {end_user_id} 的画像缓存不存在或已过期")
-            return fail(
-                BizCode.NOT_FOUND,
-                "画像缓存不存在或已过期，请右上角刷新生成新画像",
-                ""
-            )
+            api_logger.info(f"用户 {end_user_id} 的画像数据不存在")
+            return fail(BizCode.NOT_FOUND, "", "")
         
         # Extract habits from cache
         habits = cached_profile.get("habits", [])

api/app/controllers/knowledge_controller.py

@@ -27,6 +27,7 @@ from app.schemas import knowledge_schema
 from app.schemas.response_schema import ApiResponse
 from app.services import knowledge_service, document_service
 from app.services.model_service import ModelConfigService
+from app.core.quota_stub import check_knowledge_capacity_quota
 
 # Obtain a dedicated API logger
 api_logger = get_api_logger()
@@ -179,6 +180,7 @@ async def get_knowledges(
 
 
 @router.post("/knowledge", response_model=ApiResponse)
+@check_knowledge_capacity_quota
 async def create_knowledge(
         create_data: knowledge_schema.KnowledgeCreate,
         db: Session = Depends(get_db),
@@ -352,6 +354,7 @@ async def delete_knowledge(
         # 2. Soft-delete knowledge base
         api_logger.debug(f"Perform a soft delete: {db_knowledge.name} (ID: {knowledge_id})")
         db_knowledge.status = 2
+        db_knowledge.updated_at = datetime.datetime.now()
         db.commit()
         api_logger.info(f"The knowledge base has been successfully deleted: {db_knowledge.name} (ID: {knowledge_id})")
         return success(msg="The knowledge base has been successfully deleted")

api/app/controllers/mcp_market_config_controller.py

@@ -19,7 +19,7 @@ from app.models import mcp_market_config_model
 from app.models.user_model import User
 from app.schemas import mcp_market_config_schema
 from app.schemas.response_schema import ApiResponse
-from app.services import mcp_market_config_service
+from app.services import mcp_market_config_service, mcp_market_service
 
 # Obtain a dedicated API logger
 api_logger = get_api_logger()
@@ -55,6 +55,12 @@ async def get_mcp_servers(
             status_code=status.HTTP_400_BAD_REQUEST,
             detail="The paging parameter must be greater than 0"
         )
+    if page * pagesize > 100:
+        api_logger.warning(f"Paging parameters exceed ModelScope limit: page={page}, pagesize={pagesize}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"The maximum number of MCP services can view is 100. Please visit the ModelScope MCP Plaza."
+        )
 
     # 2. Query mcp market config information from the database
     api_logger.debug(f"Query mcp market config: {mcp_market_config_id}")
@@ -64,14 +70,16 @@ async def get_mcp_servers(
     if not db_mcp_market_config:
         api_logger.warning(
             f"The mcp market config does not exist or access is denied: mcp_market_config_id={mcp_market_config_id}")
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail="The mcp market config does not exist or access is denied"
-        )
+        return success(msg='The mcp market config does not exist or access is denied')
 
     # 3. Execute paged query
-    api = MCPApi()
     token = db_mcp_market_config.token
+    if not token:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="MCP market config token is not configured"
+        )
+    api = MCPApi()
     api.login(token)
 
     body = {
@@ -83,14 +91,16 @@ async def get_mcp_servers(
 
     try:
         cookies = api.get_cookies(token)
+        headers=api.builder_headers(api.headers)
+        headers['Authorization'] = f'Bearer {token}'
         r = api.session.put(
             url=api.mcp_base_url,
-            headers=api.builder_headers(api.headers),
+            headers=headers,
             json=body,
             cookies=cookies)
         raise_for_http_status(r)
     except requests.exceptions.RequestException as e:
-        api_logger.error(f"mFailed to get MCP servers: {str(e)}")
+        api_logger.error(f"Failed to get MCP servers: {str(e)}")
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             detail=f"Failed to get MCP servers: {str(e)}"
@@ -115,9 +125,82 @@ async def get_mcp_servers(
             "has_next": True if page * pagesize < total else False
         }
     }
+    # 5. Update mck_market.mcp_count
+    db_mcp_market = mcp_market_service.get_mcp_market_by_id(db, mcp_market_id=db_mcp_market_config.mcp_market_id, current_user=current_user)
+    if not db_mcp_market:
+        api_logger.warning(f"The mcp market does not exist or access is denied: mcp_market_id={db_mcp_market_config.mcp_market_id}")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="The mcp market does not exist or access is denied"
+        )
+    db_mcp_market.mcp_count = total
+    db.commit()
+    db.refresh(db_mcp_market)
     return success(data=result, msg="Query of mcp servers list successful")
 
 
+@router.get("/operational_mcp_servers", response_model=ApiResponse)
+async def get_operational_mcp_servers(
+        mcp_market_config_id: uuid.UUID,
+        db: Session = Depends(get_db),
+        current_user: User = Depends(get_current_user)
+):
+    """
+    Query the operational mcp servers list in pages
+    - Support keyword search for name,author,owner
+    - Return paging metadata + operational mcp server list
+    """
+    api_logger.info(
+        f"Query operational mcp server list: tenant_id={current_user.tenant_id}, username: {current_user.username}")
+
+    # 1. Query mcp market config information from the database
+    api_logger.debug(f"Query mcp market config: {mcp_market_config_id}")
+    db_mcp_market_config = mcp_market_config_service.get_mcp_market_config_by_id(db,
+                                                                                 mcp_market_config_id=mcp_market_config_id,
+                                                                                 current_user=current_user)
+    if not db_mcp_market_config:
+        api_logger.warning(
+            f"The mcp market config does not exist or access is denied: mcp_market_config_id={mcp_market_config_id}")
+        return success(msg='The mcp market config does not exist or access is denied')
+
+    # 2. Execute paged query
+    token = db_mcp_market_config.token
+    if not token:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="MCP market config token is not configured"
+        )
+    api = MCPApi()
+    api.login(token)
+
+    url = f'{api.mcp_base_url}/operational'
+    headers = api.builder_headers(api.headers)
+    headers['Authorization'] = f'Bearer {token}'
+
+    try:
+        cookies = api.get_cookies(access_token=token, cookies_required=True)
+        r = api.session.get(url, headers=headers, cookies=cookies)
+        raise_for_http_status(r)
+    except requests.exceptions.RequestException as e:
+        api_logger.error(f"Failed to get operational MCP servers: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to get operational MCP servers: {str(e)}"
+        )
+
+    data = api._handle_response(r)
+    total = data.get('total_count', 0)
+    mcp_server_list = data.get('mcp_server_list', [])
+    # items = [{
+    #     'name': item.get('name', ''),
+    #     'id': item.get('id', ''),
+    #     'description': item.get('description', '')
+    # } for item in mcp_server_list]
+
+    # 3. Return structured response
+    return success(data=mcp_server_list, msg="Query of operational mcp servers list successful")
+
+
 @router.get("/mcp_server", response_model=ApiResponse)
 async def get_mcp_server(
         mcp_market_config_id: uuid.UUID,
@@ -139,14 +222,16 @@ async def get_mcp_server(
     if not db_mcp_market_config:
         api_logger.warning(
             f"The mcp market config does not exist or access is denied: mcp_market_config_id={mcp_market_config_id}")
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail="The mcp market config does not exist or access is denied"
-        )
+        return success(msg='The mcp market config does not exist or access is denied')
 
     # 2. Get detailed information for a specific MCP Server
-    api = MCPApi()
     token = db_mcp_market_config.token
+    if not token:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="MCP market config token is not configured"
+        )
+    api = MCPApi()
     api.login(token)
 
     result = api.get_mcp_server(server_id=server_id)
@@ -167,7 +252,28 @@ async def create_mcp_market_config(
 
     try:
         api_logger.debug(f"Start creating the mcp market config: {create_data.mcp_market_id}")
-        # 1. Check if the mcp market name already exists
+        # 1. Validate token can access ModelScope MCP market
+        if not create_data.token:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Token is required to access ModelScope MCP market"
+            )
+        try:
+            api = MCPApi()
+            api.login(create_data.token)
+            body = {'filter': {}, 'page_number': 1, 'page_size': 1, 'search': None}
+            cookies = api.get_cookies(create_data.token)
+            headers = api.builder_headers(api.headers)
+            headers['Authorization'] = f'Bearer {create_data.token}'
+            r = api.session.put(url=api.mcp_base_url, headers=headers, json=body, cookies=cookies)
+            raise_for_http_status(r)
+        except Exception as e:
+            api_logger.warning(f"Token validation failed for ModelScope MCP market: {str(e)}")
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Unable to access ModelScope MCP market with the provided token: {str(e)}"
+            )
+        # 2. Check if the mcp market name already exists
         db_mcp_market_config_exist = mcp_market_config_service.get_mcp_market_config_by_mcp_market_id(db, mcp_market_id=create_data.mcp_market_id, current_user=current_user)
         if db_mcp_market_config_exist:
             api_logger.warning(f"The mcp market id already exists: {create_data.mcp_market_id}")
@@ -175,6 +281,32 @@ async def create_mcp_market_config(
                 status_code=status.HTTP_400_BAD_REQUEST,
                 detail=f"The mcp market id already exists: {create_data.mcp_market_id}"
             )
+        # 2. verify token
+        create_data.status = 1
+        try:
+            api = MCPApi()
+            token = create_data.token
+            api.login(token)
+
+            body = {
+                'filter': {},
+                'page_number': 1,
+                'page_size': 20,
+                'search': ""
+            }
+            cookies = api.get_cookies(token)
+            headers = api.builder_headers(api.headers)
+            headers['Authorization'] = f'Bearer {token}'
+            r = api.session.put(
+                url=api.mcp_base_url,
+                headers=headers,
+                json=body,
+                cookies=cookies)
+            raise_for_http_status(r)
+        except requests.exceptions.RequestException as e:
+            api_logger.error(f"Failed to get MCP servers: {str(e)}")
+            create_data.status = 0
+        # 3. create mcp_market_config
         db_mcp_market_config = mcp_market_config_service.create_mcp_market_config(db=db, mcp_market_config=create_data, current_user=current_user)
         api_logger.info(
             f"The mcp market config has been successfully created: (ID: {db_mcp_market_config.id})")
@@ -203,10 +335,7 @@ async def get_mcp_market_config(
         db_mcp_market_config = mcp_market_config_service.get_mcp_market_config_by_id(db, mcp_market_config_id=mcp_market_config_id, current_user=current_user)
         if not db_mcp_market_config:
             api_logger.warning(f"The mcp market config does not exist or access is denied: mcp_market_config_id={mcp_market_config_id}")
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail="The mcp market config does not exist or access is denied"
-            )
+            return success(msg='The mcp market config does not exist or access is denied')
 
         api_logger.info(f"mcp market config query successful: (ID: {db_mcp_market_config.id})")
         return success(data=jsonable_encoder(mcp_market_config_schema.McpMarketConfig.model_validate(db_mcp_market_config)),
@@ -236,10 +365,7 @@ async def get_mcp_market_config_by_mcp_market_id(
         db_mcp_market_config = mcp_market_config_service.get_mcp_market_config_by_mcp_market_id(db, mcp_market_id=mcp_market_id, current_user=current_user)
         if not db_mcp_market_config:
             api_logger.warning(f"The mcp market config does not exist or access is denied: mcp_market_id={mcp_market_id}")
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail="The mcp market config does not exist or access is denied"
-            )
+            return success(msg='The mcp market config does not exist or access is denied')
 
         api_logger.info(f"mcp market config query successful: (ID: {db_mcp_market_config.id})")
         return success(data=jsonable_encoder(mcp_market_config_schema.McpMarketConfig.model_validate(db_mcp_market_config)),
@@ -265,12 +391,27 @@ async def update_mcp_market_config(
     if not db_mcp_market_config:
         api_logger.warning(
             f"The mcp market config does not exist or you do not have permission to access it: mcp_market_config_id={mcp_market_config_id}")
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail="The mcp market config does not exist or you do not have permission to access it"
-        )
+        return success(msg='The mcp market config does not exist or access is denied')
 
-    # 2. Update fields (only update non-null fields)
+    # 2. Validate new token if provided
+    if update_data.token is not None:
+        try:
+            api = MCPApi()
+            api.login(update_data.token)
+            body = {'filter': {}, 'page_number': 1, 'page_size': 1, 'search': None}
+            cookies = api.get_cookies(update_data.token)
+            headers = api.builder_headers(api.headers)
+            headers['Authorization'] = f'Bearer {update_data.token}'
+            r = api.session.put(url=api.mcp_base_url, headers=headers, json=body, cookies=cookies)
+            raise_for_http_status(r)
+        except Exception as e:
+            api_logger.warning(f"Token validation failed for ModelScope MCP market: {str(e)}")
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Unable to access ModelScope MCP market with the provided token: {str(e)}"
+            )
+
+    # 3. Update fields (only update non-null fields)
     api_logger.debug(f"Start updating the mcp market config fields: {mcp_market_config_id}")
     update_dict = update_data.dict(exclude_unset=True)
     updated_fields = []
@@ -285,7 +426,7 @@ async def update_mcp_market_config(
     if updated_fields:
         api_logger.debug(f"updated fields: {', '.join(updated_fields)}")
 
-    # 3. Save to database
+    # 4. Save to database
     try:
         db.commit()
         db.refresh(db_mcp_market_config)
@@ -298,7 +439,7 @@ async def update_mcp_market_config(
             detail=f"The mcp market config update failed: {str(e)}"
         )
 
-    # 4. Return the updated mcp market config
+    # 5. Return the updated mcp market config
     return success(data=jsonable_encoder(mcp_market_config_schema.McpMarketConfig.model_validate(db_mcp_market_config)),
                    msg="The mcp market config information updated successfully")
 
@@ -322,10 +463,7 @@ async def delete_mcp_market_config(
         if not db_mcp_market_config:
             api_logger.warning(
                 f"The mcp market config does not exist or you do not have permission to access it: mcp_market_config_id={mcp_market_config_id}")
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
-                detail="The mcp market config does not exist or you do not have permission to access it"
-            )
+            return success(msg='The mcp market config does not exist or access is denied')
 
         # 2. Deleting mcp market config
         mcp_market_config_service.delete_mcp_market_config_by_id(db, mcp_market_config_id=mcp_market_config_id, current_user=current_user)

api/app/controllers/memory_agent_controller.py

@@ -1,27 +1,32 @@
 from typing import List, Optional
 
+from dotenv import load_dotenv
+from fastapi import APIRouter, Depends, File, Form, Query, UploadFile, Header
+from sqlalchemy.orm import Session
+from starlette.responses import StreamingResponse
+
+from app.cache.memory.interest_memory import InterestMemoryCache
 from app.celery_app import celery_app
 from app.core.error_codes import BizCode
 from app.core.language_utils import get_language_from_header
 from app.core.logging_config import get_api_logger
+from app.core.memory.agent.utils.redis_tool import store
+from app.core.memory.agent.utils.session_tools import SessionService
+from app.core.memory.enums import SearchStrategy, Neo4jNodeType
+from app.core.memory.memory_service import MemoryService
 from app.core.rag.llm.cv_model import QWenCV
 from app.core.response_utils import fail, success
 from app.db import get_db
 from app.dependencies import cur_workspace_access_guard, get_current_user
 from app.models import ModelApiKey
 from app.models.user_model import User
-from app.core.memory.agent.utils.session_tools import SessionService
-from app.core.memory.agent.utils.redis_tool import store
-from app.repositories import knowledge_repository, WorkspaceRepository
+from app.repositories import knowledge_repository
 from app.schemas.memory_agent_schema import UserInput, Write_UserInput
 from app.schemas.response_schema import ApiResponse
 from app.services import task_service, workspace_service
 from app.services.memory_agent_service import MemoryAgentService
+from app.services.memory_agent_service import get_end_user_connected_config as get_config
 from app.services.model_service import ModelConfigService
-from dotenv import load_dotenv
-from fastapi import APIRouter, Depends, File, Form, Query, UploadFile,Header
-from sqlalchemy.orm import Session
-from starlette.responses import StreamingResponse
 
 load_dotenv()
 api_logger = get_api_logger()
@@ -36,7 +41,7 @@ router = APIRouter(
 
 @router.get("/health/status", response_model=ApiResponse)
 async def get_health_status(
-    current_user: User = Depends(get_current_user)
+        current_user: User = Depends(get_current_user)
 ):
     """
     Get latest health status written by Celery periodic task
@@ -54,8 +59,9 @@ async def get_health_status(
 
 @router.get("/download_log")
 async def download_log(
-    log_type: str = Query("file", regex="^(file|transmission)$", description="日志类型: file=完整文件, transmission=实时流式传输"),
-    current_user: User = Depends(get_current_user)
+        log_type: str = Query("file", regex="^(file|transmission)$",
+                              description="日志类型: file=完整文件, transmission=实时流式传输"),
+        current_user: User = Depends(get_current_user)
 ):
     """
     Download or stream agent service log file
@@ -74,16 +80,16 @@ async def download_log(
         - transmission mode: StreamingResponse with SSE
     """
     api_logger.info(f"Log download requested with log_type={log_type}")
-    
+
     # Validate log_type parameter (FastAPI Query regex already validates, but explicit check for clarity)
     if log_type not in ["file", "transmission"]:
         api_logger.warning(f"Invalid log_type parameter: {log_type}")
         return fail(
-            BizCode.BAD_REQUEST, 
-            "无效的log_type参数", 
+            BizCode.BAD_REQUEST,
+            "无效的log_type参数",
             "log_type必须是'file'或'transmission'"
         )
-    
+
     # Route to appropriate mode
     if log_type == "file":
         # File mode: Return complete log file content
@@ -115,147 +121,150 @@ async def download_log(
             return fail(BizCode.INTERNAL_ERROR, "启动日志流式传输失败", str(e))
 
 
-@router.post("/writer_service", response_model=ApiResponse)
-@cur_workspace_access_guard()
-async def write_server(
-    user_input: Write_UserInput,
-    language_type: str = Header(default=None, alias="X-Language-Type"),
-    db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
-):
-    """
-    Write service endpoint - processes write operations synchronously
-    
-    Args:
-        user_input: Write request containing message and end_user_id
-        language_type: 语言类型 ("zh" 中文, "en" 英文)，通过 X-Language-Type Header 传递
-    
-    Returns:
-        Response with write operation status
-    """
-    # 使用集中化的语言校验
-    language = get_language_from_header(language_type)
-    
-    config_id = user_input.config_id
-    workspace_id = current_user.current_workspace_id
-    api_logger.info(f"Write service: workspace_id={workspace_id}, config_id={config_id}, language_type={language}")
-    
-    # 获取 storage_type，如果为 None 则使用默认值
-    storage_type = workspace_service.get_workspace_storage_type(
-        db=db,
-        workspace_id=workspace_id,
-        user=current_user
-    )
-    if storage_type is None: storage_type = 'neo4j'
-    user_rag_memory_id = ''
-    
-    # 如果 storage_type 是 rag，必须确保有有效的 user_rag_memory_id
-    if storage_type == 'rag':
-        if workspace_id:
-            knowledge = knowledge_repository.get_knowledge_by_name(
-                db=db,
-                name="USER_RAG_MERORY",
-                workspace_id=workspace_id
-            )
-            if knowledge:
-                user_rag_memory_id = str(knowledge.id)
-            else:
-                api_logger.warning(f"未找到名为 'USER_RAG_MERORY' 的知识库，workspace_id: {workspace_id}，将使用 neo4j 存储")
-                storage_type = 'neo4j'
-        else:
-            api_logger.warning("workspace_id 为空，无法使用 rag 存储，将使用 neo4j 存储")
-            storage_type = 'neo4j'
-    
-    api_logger.info(f"Write service requested for group {user_input.end_user_id}, storage_type: {storage_type}, user_rag_memory_id: {user_rag_memory_id}")
-    try:
-        messages_list = memory_agent_service.get_messages_list(user_input)
-        result = await memory_agent_service.write_memory(
-            user_input.end_user_id,
-            messages_list,
-            config_id,
-            db,
-            storage_type, 
-            user_rag_memory_id,
-            language
-        )
-
-        return success(data=result, msg="写入成功")
-    except BaseException as e:
-        # Handle ExceptionGroup from TaskGroup (Python 3.11+) or BaseExceptionGroup
-        if hasattr(e, 'exceptions'):
-            error_messages = [f"{type(sub_e).__name__}: {str(sub_e)}" for sub_e in e.exceptions]
-            detailed_error = "; ".join(error_messages)
-            api_logger.error(f"Write operation error (TaskGroup): {detailed_error}", exc_info=True)
-            return fail(BizCode.INTERNAL_ERROR, "写入失败", detailed_error)
-        api_logger.error(f"Write operation error: {str(e)}", exc_info=True)
-        return fail(BizCode.INTERNAL_ERROR, "写入失败", str(e))
-
-
-@router.post("/writer_service_async", response_model=ApiResponse)
-@cur_workspace_access_guard()
-async def write_server_async(
-    user_input: Write_UserInput,
-    language_type: str = Header(default=None, alias="X-Language-Type"),
-    db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
-):
-    """
-    Async write service endpoint - enqueues write processing to Celery
-    
-    Args:
-        user_input: Write request containing message and end_user_id
-        language_type: 语言类型 ("zh" 中文, "en" 英文)，通过 X-Language-Type Header 传递
-    
-    Returns:
-        Task ID for tracking async operation
-        Use GET /memory/write_result/{task_id} to check task status and get result
-    """
-    # 使用集中化的语言校验
-    language = get_language_from_header(language_type)
-    
-    config_id = user_input.config_id
-    workspace_id = current_user.current_workspace_id
-    api_logger.info(f"Async write service: workspace_id={workspace_id}, config_id={config_id}, language_type={language}")
-
-    # 获取 storage_type，如果为 None 则使用默认值
-    storage_type = workspace_service.get_workspace_storage_type(
-        db=db,
-        workspace_id=workspace_id,
-        user=current_user
-    )
-    if storage_type is None: storage_type = 'neo4j'
-    user_rag_memory_id = ''
-    if workspace_id:
-
-        knowledge = knowledge_repository.get_knowledge_by_name(
-            db=db,
-            name="USER_RAG_MERORY",
-            workspace_id=workspace_id
-        )
-        if knowledge: user_rag_memory_id = str(knowledge.id)
-    api_logger.info(f"Async write: storage_type={storage_type}, user_rag_memory_id={user_rag_memory_id}")
-    try:
-        # 获取标准化的消息列表
-        messages_list = memory_agent_service.get_messages_list(user_input)
-
-        task = celery_app.send_task(
-            "app.core.memory.agent.write_message",
-            args=[user_input.end_user_id, messages_list, config_id, storage_type, user_rag_memory_id, language]
-        )
-        api_logger.info(f"Write task queued: {task.id}")
-        
-        return success(data={"task_id": task.id}, msg="写入任务已提交")
-    except Exception as e:
-        api_logger.error(f"Async write operation failed: {str(e)}")
-        return fail(BizCode.INTERNAL_ERROR, "写入失败", str(e))
+# @router.post("/writer_service", response_model=ApiResponse)
+# @cur_workspace_access_guard()
+# async def write_server(
+#         user_input: Write_UserInput,
+#         language_type: str = Header(default=None, alias="X-Language-Type"),
+#         db: Session = Depends(get_db),
+#         current_user: User = Depends(get_current_user)
+# ):
+#     """
+#     Write service endpoint - processes write operations synchronously
+#
+#     Args:
+#         user_input: Write request containing message and end_user_id
+#         language_type: 语言类型 ("zh" 中文, "en" 英文)，通过 X-Language-Type Header 传递
+#
+#     Returns:
+#         Response with write operation status
+#     """
+#     # 使用集中化的语言校验
+#     language = get_language_from_header(language_type)
+#
+#     config_id = user_input.config_id
+#     workspace_id = current_user.current_workspace_id
+#     api_logger.info(f"Write service: workspace_id={workspace_id}, config_id={config_id}, language_type={language}")
+#
+#     # 获取 storage_type，如果为 None 则使用默认值
+#     storage_type = workspace_service.get_workspace_storage_type(
+#         db=db,
+#         workspace_id=workspace_id,
+#         user=current_user
+#     )
+#     if storage_type is None: storage_type = 'neo4j'
+#     user_rag_memory_id = ''
+#
+#     # 如果 storage_type 是 rag，必须确保有有效的 user_rag_memory_id
+#     if storage_type == 'rag':
+#         if workspace_id:
+#             knowledge = knowledge_repository.get_knowledge_by_name(
+#                 db=db,
+#                 name="USER_RAG_MERORY",
+#                 workspace_id=workspace_id
+#             )
+#             if knowledge:
+#                 user_rag_memory_id = str(knowledge.id)
+#             else:
+#                 api_logger.warning(
+#                     f"未找到名为 'USER_RAG_MERORY' 的知识库，workspace_id: {workspace_id}，将使用 neo4j 存储")
+#                 storage_type = 'neo4j'
+#         else:
+#             api_logger.warning("workspace_id 为空，无法使用 rag 存储，将使用 neo4j 存储")
+#             storage_type = 'neo4j'
+#
+#     api_logger.info(
+#         f"Write service requested for group {user_input.end_user_id}, storage_type: {storage_type}, user_rag_memory_id: {user_rag_memory_id}")
+#     try:
+#         messages_list = memory_agent_service.get_messages_list(user_input)
+#         result = await memory_agent_service.write_memory(
+#             user_input.end_user_id,
+#             messages_list,
+#             config_id,
+#             db,
+#             storage_type,
+#             user_rag_memory_id,
+#             language
+#         )
+#
+#         return success(data=result, msg="写入成功")
+#     except BaseException as e:
+#         # Handle ExceptionGroup from TaskGroup (Python 3.11+) or BaseExceptionGroup
+#         if hasattr(e, 'exceptions'):
+#             error_messages = [f"{type(sub_e).__name__}: {str(sub_e)}" for sub_e in e.exceptions]
+#             detailed_error = "; ".join(error_messages)
+#             api_logger.error(f"Write operation error (TaskGroup): {detailed_error}", exc_info=True)
+#             return fail(BizCode.INTERNAL_ERROR, "写入失败", detailed_error)
+#         api_logger.error(f"Write operation error: {str(e)}", exc_info=True)
+#         return fail(BizCode.INTERNAL_ERROR, "写入失败", str(e))
+#
+#
+# @router.post("/writer_service_async", response_model=ApiResponse)
+# @cur_workspace_access_guard()
+# async def write_server_async(
+#         user_input: Write_UserInput,
+#         language_type: str = Header(default=None, alias="X-Language-Type"),
+#         db: Session = Depends(get_db),
+#         current_user: User = Depends(get_current_user)
+# ):
+#     """
+#     Async write service endpoint - enqueues write processing to Celery
+#
+#     Args:
+#         user_input: Write request containing message and end_user_id
+#         language_type: 语言类型 ("zh" 中文, "en" 英文)，通过 X-Language-Type Header 传递
+#
+#     Returns:
+#         Task ID for tracking async operation
+#         Use GET /memory/write_result/{task_id} to check task status and get result
+#     """
+#     # 使用集中化的语言校验
+#     language = get_language_from_header(language_type)
+#
+#     config_id = user_input.config_id
+#     workspace_id = current_user.current_workspace_id
+#     api_logger.info(
+#         f"Async write service: workspace_id={workspace_id}, config_id={config_id}, language_type={language}")
+#
+#     # 获取 storage_type，如果为 None 则使用默认值
+#     storage_type = workspace_service.get_workspace_storage_type(
+#         db=db,
+#         workspace_id=workspace_id,
+#         user=current_user
+#     )
+#     if storage_type is None: storage_type = 'neo4j'
+#     user_rag_memory_id = ''
+#     if workspace_id:
+#
+#         knowledge = knowledge_repository.get_knowledge_by_name(
+#             db=db,
+#             name="USER_RAG_MERORY",
+#             workspace_id=workspace_id
+#         )
+#         if knowledge: user_rag_memory_id = str(knowledge.id)
+#     api_logger.info(f"Async write: storage_type={storage_type}, user_rag_memory_id={user_rag_memory_id}")
+#     try:
+#         # 获取标准化的消息列表
+#         messages_list = memory_agent_service.get_messages_list(user_input)
+#
+#         task = celery_app.send_task(
+#             "app.core.memory.agent.write_message",
+#             args=[user_input.end_user_id, messages_list, config_id, storage_type, user_rag_memory_id, language]
+#         )
+#         api_logger.info(f"Write task queued: {task.id}")
+#
+#         return success(data={"task_id": task.id}, msg="写入任务已提交")
+#     except Exception as e:
+#         api_logger.error(f"Async write operation failed: {str(e)}")
+#         return fail(BizCode.INTERNAL_ERROR, "写入失败", str(e))
 
 
 @router.post("/read_service", response_model=ApiResponse)
 @cur_workspace_access_guard()
 async def read_server(
-    user_input: UserInput,
-    db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
+        user_input: UserInput,
+        db: Session = Depends(get_db),
+        current_user: User = Depends(get_current_user)
 ):
     """
     Read service endpoint - processes read operations synchronously
@@ -290,35 +299,94 @@ async def read_server(
         )
         if knowledge:
             user_rag_memory_id = str(knowledge.id)
-    
-    api_logger.info(f"Read service: group={user_input.end_user_id}, storage_type={storage_type}, user_rag_memory_id={user_rag_memory_id}, workspace_id={workspace_id}")
-    try:
-        result = await memory_agent_service.read_memory(
-            user_input.end_user_id,
-            user_input.message,
-            user_input.history,
-            user_input.search_switch,
-            config_id,
-            db,
-            storage_type,
-            user_rag_memory_id
-        )
-        if str(user_input.search_switch) == "2":
-            retrieve_info = result['answer']
-            history = await SessionService(store).get_history(user_input.end_user_id, user_input.end_user_id, user_input.end_user_id)
-            query = user_input.message
 
-            # 调用 memory_agent_service 的方法生成最终答案
-            result['answer'] = await memory_agent_service.generate_summary_from_retrieve(
+    api_logger.info(
+        f"Read service: group={user_input.end_user_id}, storage_type={storage_type}, user_rag_memory_id={user_rag_memory_id}, workspace_id={workspace_id}")
+    try:
+        # result = await memory_agent_service.read_memory(
+        #     user_input.end_user_id,
+        #     user_input.message,
+        #     user_input.history,
+        #     user_input.search_switch,
+        #     config_id,
+        #     db,
+        #     storage_type,
+        #     user_rag_memory_id
+        # )
+        # if str(user_input.search_switch) == "2":
+        #     retrieve_info = result['answer']
+        #     history = await SessionService(store).get_history(user_input.end_user_id, user_input.end_user_id,
+        #                                                       user_input.end_user_id)
+        #     query = user_input.message
+        #
+        #     # 调用 memory_agent_service 的方法生成最终答案
+        #     result['answer'] = await memory_agent_service.generate_summary_from_retrieve(
+        #         end_user_id=user_input.end_user_id,
+        #         retrieve_info=retrieve_info,
+        #         history=history,
+        #         query=query,
+        #         config_id=config_id,
+        #         db=db
+        #     )
+        #     if "信息不足，无法回答" in result['answer']:
+        #         result['answer'] = retrieve_info
+        memory_config = get_config(user_input.end_user_id, db)
+        service = MemoryService(
+            db,
+            memory_config["memory_config_id"],
+            end_user_id=user_input.end_user_id
+        )
+        search_result = await service.read(
+            user_input.message,
+            SearchStrategy(user_input.search_switch)
+        )
+        intermediate_outputs = []
+        sub_queries = set()
+        for memory in search_result.memories:
+            sub_queries.add(str(memory.query))
+        if user_input.search_switch in [SearchStrategy.DEEP, SearchStrategy.NORMAL]:
+            intermediate_outputs.append({
+                "type": "problem_split",
+                "title": "问题拆分",
+                "data": [
+                    {
+                        "id": f"Q{idx+1}",
+                        "question": question
+                    }
+                    for idx, question in enumerate(sub_queries)
+                ]
+            })
+        perceptual_data = [
+            memory.data
+            for memory in search_result.memories
+            if memory.source == Neo4jNodeType.PERCEPTUAL
+        ]
+
+        intermediate_outputs.append({
+            "type": "perceptual_retrieve",
+            "title": "感知记忆检索",
+            "data": perceptual_data,
+            "total": len(perceptual_data),
+        })
+        intermediate_outputs.append({
+            "type": "search_result",
+            "title": f"合并检索结果 (共{len(sub_queries)}个查询,{len(search_result.memories)}条结果)",
+            "result": search_result.content,
+            "raw_result": search_result.memories,
+            "total": len(search_result.memories),
+        })
+        result = {
+            'answer': await memory_agent_service.generate_summary_from_retrieve(
                 end_user_id=user_input.end_user_id,
-                retrieve_info=retrieve_info,
-                history=history,
-                query=query,
+                retrieve_info=search_result.content,
+                history=[],
+                query=user_input.message,
                 config_id=config_id,
                 db=db
-            )
-            if "信息不足，无法回答" in result['answer']:
-                result['answer']=retrieve_info
+            ),
+            "intermediate_outputs": intermediate_outputs
+        }
+
         return success(data=result, msg="回复对话消息成功")
     except BaseException as e:
         # Handle ExceptionGroup from TaskGroup (Python 3.11+) or BaseExceptionGroup
@@ -334,9 +402,10 @@ async def read_server(
 @router.post("/file", response_model=ApiResponse)
 async def file_update(
         files: List[UploadFile] = File(..., description="要上传的文件"),
-        model_id:str = Form(..., description="模型ID"),
+        model_id: str = Form(..., description="模型ID"),
         metadata: Optional[str] = Form(None, description="文件元数据 (JSON格式)"),
-        current_user: User = Depends(get_current_user)
+        current_user: User = Depends(get_current_user),
+        db: Session = Depends(get_db),
 ):
     """
     文件上传接口 - 支持图片识别
@@ -349,9 +418,6 @@ async def file_update(
     Returns:
         文件处理结果
     """
-
-    db_gen = get_db()             # get_db 通常是一个生成器
-    db = next(db_gen)
     api_logger.info(f"File upload requested, file count: {len(files)}")
     config = ModelConfigService.get_model_by_id(db=db, model_id=model_id)
     apiConfig: ModelApiKey = config.api_keys[0]
@@ -360,7 +426,7 @@ async def file_update(
         for file in files:
             api_logger.debug(f"Processing file: {file.filename}, content_type: {file.content_type}")
             content = await file.read()
-            
+
             if file.content_type and file.content_type.startswith("image/"):
                 vision_model = QWenCV(
                     key=apiConfig.api_key,
@@ -374,12 +440,12 @@ async def file_update(
             else:
                 api_logger.warning(f"Unsupported file type: {file.content_type}")
                 file_content.append(f"[不支持的文件类型: {file.content_type}]")
-        
+
         result_text = ';'.join(file_content)
         api_logger.info(f"File processing completed, result length: {len(result_text)}")
-        
+
         return success(data=result_text, msg="转换文本成功")
-        
+
     except Exception as e:
         api_logger.error(f"File processing failed: {str(e)}", exc_info=True)
         return fail(BizCode.INTERNAL_ERROR, "转换文本失败", str(e))
@@ -429,8 +495,8 @@ async def read_server_async(
 
 @router.get("/read_result/", response_model=ApiResponse)
 async def get_read_task_result(
-    task_id: str,
-    current_user: User = Depends(get_current_user)
+        task_id: str,
+        current_user: User = Depends(get_current_user)
 ):
     """
     Get the status and result of an async read task
@@ -451,7 +517,7 @@ async def get_read_task_result(
     try:
         result = task_service.get_task_memory_read_result(task_id)
         status = result.get("status")
-        
+
         if status == "SUCCESS":
             # 任务成功完成
             task_result = result.get("result", {})
@@ -469,7 +535,7 @@ async def get_read_task_result(
             else:
                 # 旧格式：直接返回结果
                 return success(data=task_result, msg="查询任务已完成")
-                
+
         elif status == "FAILURE":
             # 任务失败
             error_info = result.get("result", "Unknown error")
@@ -478,7 +544,7 @@ async def get_read_task_result(
             else:
                 error_msg = str(error_info)
             return fail(BizCode.INTERNAL_ERROR, "查询任务失败", error_msg)
-            
+
         elif status in ["PENDING", "STARTED"]:
             # 任务进行中
             return success(
@@ -498,7 +564,7 @@ async def get_read_task_result(
                 },
                 msg=f"任务状态: {status}"
             )
-            
+
     except Exception as e:
         api_logger.error(f"Read task status check failed: {str(e)}", exc_info=True)
         return fail(BizCode.INTERNAL_ERROR, "任务状态查询失败", str(e))
@@ -506,8 +572,8 @@ async def get_read_task_result(
 
 @router.get("/write_result/", response_model=ApiResponse)
 async def get_write_task_result(
-    task_id: str,
-    current_user: User = Depends(get_current_user)
+        task_id: str,
+        current_user: User = Depends(get_current_user)
 ):
     """
     Get the status and result of an async write task
@@ -528,7 +594,7 @@ async def get_write_task_result(
     try:
         result = task_service.get_task_memory_write_result(task_id)
         status = result.get("status")
-        
+
         if status == "SUCCESS":
             # 任务成功完成
             task_result = result.get("result", {})
@@ -546,7 +612,7 @@ async def get_write_task_result(
             else:
                 # 旧格式：直接返回结果
                 return success(data=task_result, msg="写入任务已完成")
-                
+
         elif status == "FAILURE":
             # 任务失败
             error_info = result.get("result", "Unknown error")
@@ -555,7 +621,7 @@ async def get_write_task_result(
             else:
                 error_msg = str(error_info)
             return fail(BizCode.INTERNAL_ERROR, "写入任务失败", error_msg)
-            
+
         elif status in ["PENDING", "STARTED"]:
             # 任务进行中
             return success(
@@ -575,7 +641,7 @@ async def get_write_task_result(
                 },
                 msg=f"任务状态: {status}"
             )
-            
+
     except Exception as e:
         api_logger.error(f"Write task status check failed: {str(e)}", exc_info=True)
         return fail(BizCode.INTERNAL_ERROR, "任务状态查询失败", str(e))
@@ -583,9 +649,9 @@ async def get_write_task_result(
 
 @router.post("/status_type", response_model=ApiResponse)
 async def status_type(
-    user_input: Write_UserInput,
-    db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
+        user_input: Write_UserInput,
+        db: Session = Depends(get_db),
+        current_user: User = Depends(get_current_user)
 ):
     """
     Determine the type of user message (read or write)
@@ -628,26 +694,21 @@ async def status_type(
 
 @router.get("/stats/types", response_model=ApiResponse)
 async def get_knowledge_type_stats_api(
-    end_user_id: Optional[str] = Query(None, description="用户ID（可选）"),
-    only_active: bool = Query(True, description="仅统计有效记录(status=1)"),
-    current_user: User = Depends(get_current_user)
+        end_user_id: Optional[str] = Query(None, description="用户ID（可选）"),
+        only_active: bool = Query(True, description="仅统计有效记录(status=1)"),
+        current_user: User = Depends(get_current_user),
+        db: Session = Depends(get_db),
 ):
     """
-    统计当前空间下各知识库类型的数量，包含 General | Web | Third-party | Folder | memory。
+    统计当前空间下各知识库类型的数量，包含 General | Web | Third-party | Folder。
     会对缺失类型补 0，返回字典形式。
     可选按状态过滤。
     - 知识库类型根据当前用户的 current_workspace_id 过滤
-    - memory 是 Neo4j 中 Chunk 的数量，根据 end_user_id (end_user_id) 过滤
-    - 如果用户没有当前工作空间或未提供 end_user_id，对应的统计返回 0
+    - 如果用户没有当前工作空间，对应的统计返回 0
     """
-    api_logger.info(f"Knowledge type stats requested for workspace_id: {current_user.current_workspace_id}, end_user_id: {end_user_id}")
+    api_logger.info(
+        f"Knowledge type stats requested for workspace_id: {current_user.current_workspace_id}, end_user_id: {end_user_id}")
     try:
-        from app.db import get_db
-        
-        # 获取数据库会话
-        db_gen = get_db()
-        db = next(db_gen)
-        
         # 调用service层函数
         result = await memory_agent_service.get_knowledge_type_stats(
             end_user_id=end_user_id,
@@ -655,48 +716,70 @@ async def get_knowledge_type_stats_api(
             current_workspace_id=current_user.current_workspace_id,
             db=db
         )
-        
+
         return success(data=result, msg="获取知识库类型统计成功")
     except Exception as e:
         api_logger.error(f"Knowledge type stats failed: {str(e)}")
         return fail(BizCode.INTERNAL_ERROR, "获取知识库类型统计失败", str(e))
 
 
-@router.get("/analytics/hot_memory_tags/by_user", response_model=ApiResponse)
-async def get_hot_memory_tags_by_user_api(
-    end_user_id: Optional[str] = Query(None, description="用户ID（可选）"),
-    limit: int = Query(20, description="返回标签数量限制"),
-    current_user: User = Depends(get_current_user),
-    db: Session=Depends(get_db),
+@router.get("/analytics/interest_distribution/by_user", response_model=ApiResponse)
+async def get_interest_distribution_by_user_api(
+        end_user_id: str = Query(..., description="用户ID（必填）"),
+        limit: int = Query(5, le=5, description="返回兴趣标签数量限制，最多5个"),
+        language_type: str = Header(default=None, alias="X-Language-Type"),
+        current_user: User = Depends(get_current_user),
+        db: Session = Depends(get_db),
 ):
     """
-    获取指定用户的热门记忆标签
+    获取指定用户的兴趣分布标签
     
-    注意：标签语言由写入时的 X-Language-Type 决定，查询时不进行翻译
+    与热门标签不同，此接口专注于识别用户的兴趣活动（运动、爱好、学习、创作等），
+    过滤掉纯物品、工具、地点等不代表用户主动参与活动的名词。
     
     返回格式：
     [
-        {"name": "标签名", "frequency": 频次},
+        {"name": "兴趣活动名", "frequency": 频次},
         ...
     ]
     """
-    api_logger.info(f"Hot memory tags by user requested: end_user_id={end_user_id}")
+    language = get_language_from_header(language_type)
+    api_logger.info(f"Interest distribution by user requested: end_user_id={end_user_id}, language={language}")
     try:
-        result = await memory_agent_service.get_hot_memory_tags_by_user(
+        # 优先读取缓存
+        cached = await InterestMemoryCache.get_interest_distribution(
             end_user_id=end_user_id,
-            limit=limit
+            language=language,
         )
-        return success(data=result, msg="获取热门记忆标签成功")
+        if cached is not None:
+            api_logger.info(f"Interest distribution cache hit: end_user_id={end_user_id}")
+            return success(data=cached, msg="获取兴趣分布标签成功")
+
+        # 缓存未命中，调用模型生成
+        result = await memory_agent_service.get_interest_distribution_by_user(
+            end_user_id=end_user_id,
+            limit=limit,
+            language=language
+        )
+
+        # 写入缓存，24小时过期
+        await InterestMemoryCache.set_interest_distribution(
+            end_user_id=end_user_id,
+            language=language,
+            data=result,
+        )
+
+        return success(data=result, msg="获取兴趣分布标签成功")
     except Exception as e:
-        api_logger.error(f"Hot memory tags by user failed: {str(e)}")
-        return fail(BizCode.INTERNAL_ERROR, "获取热门记忆标签失败", str(e))
+        api_logger.error(f"Interest distribution by user failed: {str(e)}")
+        return fail(BizCode.INTERNAL_ERROR, "获取兴趣分布标签失败", str(e))
 
 
 @router.get("/analytics/user_profile", response_model=ApiResponse)
 async def get_user_profile_api(
-    end_user_id: Optional[str] = Query(None, description="用户ID（可选）"),
-    db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
+        end_user_id: Optional[str] = Query(None, description="用户ID（可选）"),
+        db: Session = Depends(get_db),
+        current_user: User = Depends(get_current_user)
 ):
     """
     获取用户详情，包含：
@@ -734,17 +817,17 @@ async def get_user_profile_api(
 # ):
 #     """
 #     Get parsed API documentation (Public endpoint - no authentication required)
-    
+
 #     Args:
 #         file_path: Optional path to API docs file. If None, uses default path.
-    
+
 #     Returns:
 #         Parsed API documentation including title, meta info, and sections
 #     """
 #     api_logger.info(f"API docs requested, file_path: {file_path or 'default'}")
 #     try:
 #         result = await memory_agent_service.get_api_docs(file_path)
-        
+
 #         if result.get("success"):
 #             return success(msg=result["msg"], data=result["data"])
 #         else:
@@ -760,9 +843,9 @@ async def get_user_profile_api(
 
 @router.get("/end_user/{end_user_id}/connected_config", response_model=ApiResponse)
 async def get_end_user_connected_config(
-    end_user_id: str,
-    db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
+        end_user_id: str,
+        db: Session = Depends(get_db),
+        current_user: User = Depends(get_current_user)
 ):
     """
     获取终端用户关联的记忆配置
@@ -778,12 +861,9 @@ async def get_end_user_connected_config(
     Returns:
         包含 memory_config_id 和相关信息的响应
     """
-    from app.services.memory_agent_service import (
-        get_end_user_connected_config as get_config,
-    )
-    
+
     api_logger.info(f"Getting connected config for end_user: {end_user_id}")
-    
+
     try:
         result = get_config(end_user_id, db)
         return success(data=result, msg="获取终端用户关联配置成功")
@@ -792,4 +872,4 @@ async def get_end_user_connected_config(
         return fail(BizCode.NOT_FOUND, str(e))
     except Exception as e:
         api_logger.error(f"Failed to get end user connected config: {str(e)}", exc_info=True)
-        return fail(BizCode.INTERNAL_ERROR, "获取终端用户关联配置失败", str(e))
+        return fail(BizCode.INTERNAL_ERROR, "获取终端用户关联配置失败", str(e))

api/app/controllers/memory_dashboard_controller.py

@@ -1,4 +1,7 @@
+
+import uuid
 from fastapi import APIRouter, Depends, HTTPException, status, Query
+from pydantic import BaseModel, Field
 from sqlalchemy.orm import Session
 from typing import Optional
 from app.core.response_utils import success
@@ -7,8 +10,9 @@ from app.dependencies import get_current_user
 from app.models.user_model import User
 from app.schemas.response_schema import ApiResponse
 
-from app.services import memory_dashboard_service, memory_storage_service, workspace_service
+from app.services import memory_dashboard_service, workspace_service
 from app.services.memory_agent_service import get_end_users_connected_configs_batch
+from app.services.app_statistics_service import AppStatisticsService
 from app.core.logging_config import get_api_logger
 
 # 获取API专用日志器
@@ -44,140 +48,149 @@ def get_workspace_total_end_users(
 
 
 @router.get("/end_users", response_model=ApiResponse)
-async def get_workspace_end_users(
+def get_workspace_end_users(
+    workspace_id: Optional[uuid.UUID] = Query(None, description="工作空间ID（可选，默认当前用户工作空间）"),
+    keyword: Optional[str] = Query(None, description="搜索关键词（同时模糊匹配 other_name 和 id）"),
+    page: int = Query(1, ge=1, description="页码，从1开始"),
+    pagesize: int = Query(10, ge=1, description="每页数量"),
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
 ):
     """
-    获取工作空间的宿主列表（高性能优化版本 v2）
+    获取工作空间的宿主列表（分页查询，支持模糊搜索）
     
-    优化策略：
-    1. 批量查询 end_users（一次查询而非循环）
-    2. 并发查询所有用户的记忆数量（Neo4j）
-    3. RAG 模式使用批量查询（一次 SQL）
-    4. 只返回必要字段减少数据传输
-    5. 添加短期缓存减少重复查询
-    6. 并发执行配置查询和记忆数量查询
-    
-    返回格式：
-    {
-        "end_user": {"id": "uuid", "other_name": "名称"},
-        "memory_num": {"total": 数量},
-        "memory_config": {"memory_config_id": "id", "memory_config_name": "名称"}
-    }
+    新增：记忆数量过滤：
+        Neo4j 模式：
+        - 使用 end_users.memory_count 过滤 memory_count > 0 的宿主
+        - memory_num.total 直接取 end_user.memory_count
+
+        RAG 模式：
+        - 使用 documents.chunk_num 聚合过滤 chunk 总数 > 0 的宿主
+        - memory_num.total 取聚合后的 chunk 总数
+
+    返回工作空间下的宿主列表，支持分页查询和模糊搜索。
+    通过 keyword 参数同时模糊匹配 other_name 和 id 字段。
+
+    Args:
+        workspace_id: 工作空间ID（可选，默认当前用户工作空间）
+        keyword: 搜索关键词（可选，同时模糊匹配 other_name 和 id）
+        page: 页码（从1开始，默认1）
+        pagesize: 每页数量（默认10）
+        db: 数据库会话
+        current_user: 当前用户
+
+    Returns:
+        ApiResponse: 包含宿主列表和分页信息
     """
-    import asyncio
-    import json
-    from app.aioRedis import aio_redis_get, aio_redis_set
-    
-    workspace_id = current_user.current_workspace_id
-    
-    # 尝试从缓存获取（30秒缓存）
-    cache_key = f"end_users:workspace:{workspace_id}"
-    try:
-        cached_data = await aio_redis_get(cache_key)
-        if cached_data:
-            api_logger.info(f"从缓存获取宿主列表: workspace_id={workspace_id}")
-            return success(data=json.loads(cached_data), msg="宿主列表获取成功")
-    except Exception as e:
-        api_logger.warning(f"Redis 缓存读取失败: {str(e)}")
-    
+    # 如果未提供 workspace_id，使用当前用户的工作空间
+    if workspace_id is None:
+        workspace_id = current_user.current_workspace_id
     # 获取当前空间类型
     current_workspace_type = memory_dashboard_service.get_current_workspace_type(db, workspace_id, current_user)
-    api_logger.info(f"用户 {current_user.username} 请求获取工作空间 {workspace_id} 的宿主列表")
-    
-    # 获取 end_users（已优化为批量查询）
-    end_users = memory_dashboard_service.get_workspace_end_users(
-        db=db,
-        workspace_id=workspace_id,
-        current_user=current_user
-    )
+    api_logger.info(f"用户 {current_user.username} 请求获取工作空间 {workspace_id} 的宿主列表, 类型: {current_workspace_type}")
+
+    if current_workspace_type == "rag":
+        end_users_result = memory_dashboard_service.get_workspace_end_users_paginated_rag(
+            db=db,
+            workspace_id=workspace_id,
+            current_user=current_user,
+            page=page,
+            pagesize=pagesize,
+            keyword=keyword,
+        )
+        raw_items = end_users_result.get("items", [])
+        end_users = [item["end_user"] for item in raw_items]
+    else:
+        end_users_result = memory_dashboard_service.get_workspace_end_users_paginated(
+            db=db,
+            workspace_id=workspace_id,
+            current_user=current_user,
+            page=page,
+            pagesize=pagesize,
+            keyword=keyword,
+        )
+        raw_items = end_users_result.get("items", [])
+        end_users = raw_items
+
+    total = end_users_result.get("total", 0)
+
     if not end_users:
-        api_logger.info("工作空间下没有宿主")
-        # 缓存空结果，避免重复查询
-        try:
-            await aio_redis_set(cache_key, json.dumps([]), expire=30)
-        except Exception as e:
-            api_logger.warning(f"Redis 缓存写入失败: {str(e)}")
-        return success(data=[], msg="宿主列表获取成功")
-    
+        api_logger.info(f"工作空间下没有宿主或当前页无数据: total={total}, page={page}")
+        return success(data={
+            "items": [],
+            "page": {
+                "page": page,
+                "pagesize": pagesize,
+                "total": total,
+                "hasnext": (page * pagesize) < total,
+            },
+        }, msg="宿主列表获取成功")
+
     end_user_ids = [str(user.id) for user in end_users]
-    
-    # 并发执行两个独立的查询任务
-    async def get_memory_configs():
-        """获取记忆配置（在线程池中执行同步查询）"""
-        try:
-            return await asyncio.to_thread(
-                get_end_users_connected_configs_batch,
-                end_user_ids, db
-            )
-        except Exception as e:
-            api_logger.error(f"批量获取记忆配置失败: {str(e)}")
-            return {}
-    
-    async def get_memory_nums():
-        """获取记忆数量"""
-        if current_workspace_type == "rag":
-            # RAG 模式：批量查询
-            try:
-                chunk_map = await asyncio.to_thread(
-                    memory_dashboard_service.get_users_total_chunk_batch,
-                    end_user_ids, db, current_user
-                )
-                return {uid: {"total": count} for uid, count in chunk_map.items()}
-            except Exception as e:
-                api_logger.error(f"批量获取 RAG chunk 数量失败: {str(e)}")
-                return {uid: {"total": 0} for uid in end_user_ids}
-        
-        elif current_workspace_type == "neo4j":
-            # Neo4j 模式：并发查询（带并发限制）
-            # 使用信号量限制并发数，避免大量用户时压垮 Neo4j
-            MAX_CONCURRENT_QUERIES = 10
-            semaphore = asyncio.Semaphore(MAX_CONCURRENT_QUERIES)
-            
-            async def get_neo4j_memory_num(end_user_id: str):
-                async with semaphore:
-                    try:
-                        return await memory_storage_service.search_all(end_user_id)
-                    except Exception as e:
-                        api_logger.error(f"获取用户 {end_user_id} Neo4j 记忆数量失败: {str(e)}")
-                        return {"total": 0}
-            
-            memory_nums_list = await asyncio.gather(*[get_neo4j_memory_num(uid) for uid in end_user_ids])
-            return {end_user_ids[i]: memory_nums_list[i] for i in range(len(end_user_ids))}
-        
-        return {uid: {"total": 0} for uid in end_user_ids}
-    
-    # 并发执行配置查询和记忆数量查询
-    memory_configs_map, memory_nums_map = await asyncio.gather(
-        get_memory_configs(),
-        get_memory_nums()
-    )
-    
-    # 构建结果（优化：使用列表推导式）
-    result = []
-    for end_user in end_users:
+
+    try:
+        memory_configs_map = get_end_users_connected_configs_batch(end_user_ids, db)
+    except Exception as e:
+        api_logger.error(f"批量获取记忆配置失败: {str(e)}")
+        memory_configs_map = {}
+
+    # 触发按需初始化：为 implicit_emotions_storage / interest_distribution 中没有记录的用户异步生成数据
+    try:
+        from app.celery_app import celery_app as _celery_app
+        _celery_app.send_task(
+            "app.tasks.init_implicit_emotions_for_users",
+            kwargs={"end_user_ids": end_user_ids},
+        )
+        _celery_app.send_task(
+            "app.tasks.init_interest_distribution_for_users",
+            kwargs={"end_user_ids": end_user_ids},
+        )
+        api_logger.info(f"已触发按需初始化任务，候选用户数: {len(end_user_ids)}")
+    except Exception as e:
+        api_logger.warning(f"触发按需初始化任务失败（不影响主流程）: {e}")
+
+    items = []
+    for index, end_user in enumerate(end_users):
         user_id = str(end_user.id)
         config_info = memory_configs_map.get(user_id, {})
-        result.append({
-            'end_user': {
-                'id': user_id,
-                'other_name': end_user.other_name
+
+        if current_workspace_type == "rag":
+            memory_total = int(raw_items[index].get("memory_count", 0) or 0)
+        else:
+            memory_total = int(getattr(end_user, "memory_count", 0) or 0)
+
+        items.append({
+            "end_user": {
+                "id": user_id,
+                "other_name": end_user.other_name,
             },
-            'memory_num': memory_nums_map.get(user_id, {"total": 0}),
-            'memory_config': {
+            "memory_num": {"total": memory_total},
+            "memory_config": {
                 "memory_config_id": config_info.get("memory_config_id"),
-                "memory_config_name": config_info.get("memory_config_name")
-            }
+                "memory_config_name": config_info.get("memory_config_name"),
+            },
         })
-    
-    # 写入缓存（30秒过期）
+
+    # 触发社区聚类补全任务（异步，不阻塞接口响应）
     try:
-        await aio_redis_set(cache_key, json.dumps(result), expire=30)
+        from app.tasks import init_community_clustering_for_users
+        init_community_clustering_for_users.delay(end_user_ids=end_user_ids, workspace_id=str(workspace_id))
+        api_logger.info(f"已触发社区聚类补全任务，候选用户数: {len(end_user_ids)}")
     except Exception as e:
-        api_logger.warning(f"Redis 缓存写入失败: {str(e)}")
-    
-    api_logger.info(f"成功获取 {len(end_users)} 个宿主记录")
+        api_logger.warning(f"触发社区聚类补全任务失败（不影响主流程）: {str(e)}")
+
+    # 构建分页响应
+    result = {
+        "items": items,
+        "page": {
+            "page": page,
+            "pagesize": pagesize,
+            "total": total,
+            "hasnext": (page * pagesize) < total
+        }
+    }
+
+    api_logger.info(f"成功获取 {len(end_users)} 个宿主记录，总计 {total} 条")
     return success(data=result, msg="宿主列表获取成功")
 
 
@@ -383,17 +396,19 @@ def get_current_user_rag_total_num(
     total_chunk = memory_dashboard_service.get_current_user_total_chunk(end_user_id, db, current_user)
     return success(data=total_chunk, msg="宿主RAG知识数据获取成功")
 
+
 @router.get("/rag_content", response_model=ApiResponse)
 def get_rag_content(
     end_user_id: str = Query(..., description="宿主ID"),
-    limit: int = Query(15, description="返回记录数"),
+    page: int = Query(1, gt=0, description="页码，从1开始"),
+    pagesize: int = Query(15, gt=0, le=100, description="每页返回记录数"),
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
 ):
     """
-    获取当前宿主知识库中的chunk内容
+    获取当前宿主知识库中的chunk内容（分页）
     """
-    data = memory_dashboard_service.get_rag_content(end_user_id, limit, db, current_user)
+    data = memory_dashboard_service.get_rag_content(end_user_id, page, pagesize, db, current_user)
     return success(data=data, msg="宿主RAGchunk数据获取成功")
 
 
@@ -406,26 +421,18 @@ async def get_chunk_summary_tag(
     current_user: User = Depends(get_current_user),
 ):
     """
-    获取chunk总结、提取的标签和人物形象
-    
+    读取RAG摘要、标签和人物形象（纯读库，不触发生成）。
+
     返回格式：
     {
-        "summary": "chunk内容的总结",
-        "tags": [
-            {"tag": "标签1", "frequency": 5},
-            {"tag": "标签2", "frequency": 3},
-            ...
-        ],
-        "personas": [
-            "产品设计师",
-            "旅行爱好者",
-            "摄影发烧友",
-            ...
-        ]
+        "summary": "用户摘要",
+        "tags": [{"tag": "标签1", "frequency": 5}, ...],
+        "personas": ["产品设计师", ...],
+        "generated": true/false  // false表示尚未生产，请调用 /generate_rag_profile
     }
     """
-    api_logger.info(f"用户 {current_user.username} 请求获取宿主 {end_user_id} 的chunk摘要、标签和人物形象")
-    
+    api_logger.info(f"用户 {current_user.username} 读取宿主 {end_user_id} 的RAG摘要/标签/人物形象")
+
     data = await memory_dashboard_service.get_chunk_summary_and_tags(
         end_user_id=end_user_id,
         limit=limit,
@@ -433,9 +440,8 @@ async def get_chunk_summary_tag(
         db=db,
         current_user=current_user
     )
-    
-    api_logger.info(f"成功获取chunk摘要、{len(data.get('tags', []))} 个标签和 {len(data.get('personas', []))} 个人物形象")
-    return success(data=data, msg="chunk摘要、标签和人物形象获取成功")
+
+    return success(data=data, msg="获取成功")
 
 
 @router.get("/chunk_insight", response_model=ApiResponse)
@@ -446,29 +452,64 @@ async def get_chunk_insight(
     current_user: User = Depends(get_current_user),
 ):
     """
-    获取chunk的洞察内容
-    
+    读取RAG洞察报告（纯读库，不触发生成）。
+
     返回格式：
     {
-        "insight": "对chunk内容的深度洞察分析"
+        "insight": "总体概述",
+        "behavior_pattern": "行为模式",
+        "key_findings": "关键发现",
+        "growth_trajectory": "成长轨迹",
+        "generated": true/false  // false表示尚未生产，请调用 /generate_rag_profile
     }
     """
-    api_logger.info(f"用户 {current_user.username} 请求获取宿主 {end_user_id} 的chunk洞察")
-    
+    api_logger.info(f"用户 {current_user.username} 读取宿主 {end_user_id} 的RAG洞察")
+
     data = await memory_dashboard_service.get_chunk_insight(
         end_user_id=end_user_id,
         limit=limit,
         db=db,
         current_user=current_user
     )
-    
-    api_logger.info("成功获取chunk洞察")
-    return success(data=data, msg="chunk洞察获取成功")
+
+    return success(data=data, msg="获取成功")
+
+
+class GenerateRagProfileRequest(BaseModel):
+    end_user_id: str = Field(..., description="宿主ID")
+    limit: int = Field(15, description="参与生成的chunk数量上限")
+    max_tags: int = Field(10, description="最大标签数量")
+
+
+@router.post("/generate_rag_profile", response_model=ApiResponse)
+async def generate_rag_profile(
+    body: GenerateRagProfileRequest,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+):
+    """
+    生产接口：为RAG存储模式的宿主全量重新生成完整画像并持久化到end_user表。
+    每次请求都会重新生成，覆盖已有数据。
+    """
+    api_logger.info(f"用户 {current_user.username} 触发RAG画像生产: end_user_id={body.end_user_id}")
+
+    data = await memory_dashboard_service.generate_rag_profile(
+        end_user_id=body.end_user_id,
+        limit=body.limit,
+        max_tags=body.max_tags,
+        db=db,
+        current_user=current_user,
+    )
+
+    api_logger.info(f"RAG画像生产完成: {data}")
+    return success(data=data, msg="RAG画像生产完成")
 
 
 @router.get("/dashboard_data", response_model=ApiResponse)
 async def dashboard_data(
     end_user_id: Optional[str] = Query(None, description="可选的用户ID"),
+    start_date: Optional[int] = Query(None, description="开始时间戳（毫秒）"),
+    end_date: Optional[int] = Query(None, description="结束时间戳（毫秒）"),
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
 ):
@@ -503,6 +544,15 @@ async def dashboard_data(
     workspace_id = current_user.current_workspace_id
     api_logger.info(f"用户 {current_user.username} 请求获取工作空间 {workspace_id} 的dashboard整合数据")
     
+    # 如果没有提供时间范围，默认使用最近30天
+    if start_date is None or end_date is None:
+        from datetime import datetime, timedelta
+        end_dt = datetime.now()
+        start_dt = end_dt - timedelta(days=30)
+        end_date = int(end_dt.timestamp() * 1000)
+        start_date = int(start_dt.timestamp() * 1000)
+        api_logger.info(f"使用默认时间范围: {start_dt} 到 {end_dt}")
+    
     # 获取 storage_type，如果为 None 则使用默认值
     storage_type = workspace_service.get_workspace_storage_type(
         db=db,
@@ -531,7 +581,7 @@ async def dashboard_data(
                 "total_api_call": None
             }
             
-            # 1. 获取记忆总量（total_memory）
+            # 1. 获取记忆总量（total_memory）—— neo4j 独有逻辑：查询 neo4j 存储节点
             try:
                 total_memory_data = await memory_dashboard_service.get_workspace_total_memory_count(
                     db=db,
@@ -540,41 +590,33 @@ async def dashboard_data(
                     end_user_id=end_user_id
                 )
                 neo4j_data["total_memory"] = total_memory_data.get("total_memory_count", 0)
-                # total_app: 统计当前空间下的所有app数量
-                from app.repositories import app_repository
-                apps_orm = app_repository.get_apps_by_workspace_id(db, workspace_id)
-                neo4j_data["total_app"] = len(apps_orm)
-                api_logger.info(f"成功获取记忆总量: {neo4j_data['total_memory']}, 应用数量: {neo4j_data['total_app']}")
+                api_logger.info(f"成功获取记忆总量: {neo4j_data['total_memory']}")
             except Exception as e:
                 api_logger.warning(f"获取记忆总量失败: {str(e)}")
             
-            # 2. 获取知识库类型统计（total_knowledge）
-            try:
-                from app.services.memory_agent_service import MemoryAgentService 
-                memory_agent_service = MemoryAgentService()
-                knowledge_stats = await memory_agent_service.get_knowledge_type_stats(
-                    end_user_id=end_user_id,
-                    only_active=True,
-                    current_workspace_id=workspace_id,
-                    db=db
-                )
-                neo4j_data["total_knowledge"] = knowledge_stats.get("total", 0)
-                api_logger.info(f"成功获取知识库类型统计total: {neo4j_data['total_knowledge']}")
-            except Exception as e:
-                api_logger.warning(f"获取知识库类型统计失败: {str(e)}")
+            # 2. 获取共享统计数据（total_app、total_knowledge、total_api_call）
+            common_stats = memory_dashboard_service.get_dashboard_common_stats(db, workspace_id)
+            neo4j_data.update(common_stats)
+            api_logger.info(f"成功获取共享统计: app={common_stats['total_app']}, knowledge={common_stats['total_knowledge']}, api_call={common_stats['total_api_call']}")
             
-            # 3. 获取API调用增量（total_api_call，转换为整数）
+            # 计算昨日对比
             try:
-                api_increment = memory_dashboard_service.get_workspace_api_increment(
+                changes = memory_dashboard_service.get_dashboard_yesterday_changes(
                     db=db,
                     workspace_id=workspace_id,
-                    current_user=current_user
+                    storage_type=storage_type,
+                    today_data=neo4j_data
                 )
-                neo4j_data["total_api_call"] = api_increment
-                api_logger.info(f"成功获取API调用增量: {neo4j_data['total_api_call']}")
+                neo4j_data.update(changes)
             except Exception as e:
-                api_logger.warning(f"获取API调用增量失败: {str(e)}")
-            
+                api_logger.warning(f"计算neo4j昨日对比失败: {str(e)}")
+                neo4j_data.update({
+                    "total_memory_change": None,
+                    "total_app_change": None,
+                    "total_knowledge_change": None,
+                    "total_api_call_change": None,
+                })
+
             result["neo4j_data"] = neo4j_data
             api_logger.info("成功获取neo4j_data")
         
@@ -587,28 +629,37 @@ async def dashboard_data(
                 "total_api_call": None
             }
             
-            # 获取RAG相关数据
+            # 1. 获取记忆总量（total_memory）—— rag 独有逻辑：查询 document 表的 chunk_num
             try:
-                # total_memory: 使用 total_chunk（总chunk数）
-                total_chunk = memory_dashboard_service.get_rag_total_chunk(db, current_user)
+                total_chunk = memory_dashboard_service.get_rag_user_kb_total_chunk(db, current_user)
                 rag_data["total_memory"] = total_chunk
-                
-                # total_app: 统计当前空间下的所有app数量
-                from app.repositories import app_repository
-                apps_orm = app_repository.get_apps_by_workspace_id(db, workspace_id)
-                rag_data["total_app"] = len(apps_orm)
-                
-                # total_knowledge: 使用 total_kb（总知识库数）
-                total_kb = memory_dashboard_service.get_rag_total_kb(db, current_user)
-                rag_data["total_knowledge"] = total_kb
-                
-                # total_api_call: 固定值
-                rag_data["total_api_call"] = 1024
-                
-                api_logger.info(f"成功获取RAG相关数据: memory={total_chunk}, app={len(apps_orm)}, knowledge={total_kb}")
+                api_logger.info(f"成功获取RAG记忆总量: {total_chunk}")
             except Exception as e:
-                api_logger.warning(f"获取RAG相关数据失败: {str(e)}")
+                api_logger.warning(f"获取RAG记忆总量失败: {str(e)}")
             
+            # 2. 获取共享统计数据（total_app、total_knowledge、total_api_call）
+            common_stats = memory_dashboard_service.get_dashboard_common_stats(db, workspace_id)
+            rag_data.update(common_stats)
+            api_logger.info(f"成功获取共享统计: app={common_stats['total_app']}, knowledge={common_stats['total_knowledge']}, api_call={common_stats['total_api_call']}")
+            
+            # 计算昨日对比
+            try:
+                changes = memory_dashboard_service.get_dashboard_yesterday_changes(
+                    db=db,
+                    workspace_id=workspace_id,
+                    storage_type=storage_type,
+                    today_data=rag_data
+                )
+                rag_data.update(changes)
+            except Exception as e:
+                api_logger.warning(f"计算RAG昨日对比失败: {str(e)}")
+                rag_data.update({
+                    "total_memory_change": None,
+                    "total_app_change": None,
+                    "total_knowledge_change": None,
+                    "total_api_call_change": None,
+                })
+
             result["rag_data"] = rag_data
             api_logger.info("成功获取rag_data")
         

api/app/controllers/memory_explicit_controller.py

@@ -4,7 +4,9 @@
 处理显性记忆相关的API接口，包括情景记忆和语义记忆的查询。
 """
 
-from fastapi import APIRouter, Depends
+from typing import Optional
+
+from fastapi import APIRouter, Depends, Query
 
 from app.core.logging_config import get_api_logger
 from app.core.response_utils import success, fail
@@ -69,6 +71,140 @@ async def get_explicit_memory_overview_api(
         return fail(BizCode.INTERNAL_ERROR, "显性记忆总览查询失败", str(e))
 
 
+@router.get("/episodics", response_model=ApiResponse)
+async def get_episodic_memory_list_api(
+    end_user_id: str = Query(..., description="end user ID"),
+    page: int = Query(1, gt=0, description="page number, starting from 1"),
+    pagesize: int = Query(10, gt=0, le=100, description="number of items per page, max 100"),
+    start_date: Optional[int] = Query(None, description="start timestamp (ms)"),
+    end_date: Optional[int] = Query(None, description="end timestamp (ms)"),
+    episodic_type: str = Query("all", description="episodic type ：all/conversation/project_work/learning/decision/important_event"),
+    current_user: User = Depends(get_current_user),
+) -> dict:
+    """
+    获取情景记忆分页列表
+
+    返回指定用户的情景记忆列表，支持分页、时间范围筛选和情景类型筛选。
+
+    Args:
+        end_user_id: 终端用户ID（必填）
+        page: 页码（从1开始，默认1）
+        pagesize: 每页数量（默认10，最大100）
+        start_date: 开始时间戳（可选，毫秒），自动扩展到当天 00:00:00
+        end_date: 结束时间戳（可选，毫秒），自动扩展到当天 23:59:59
+        episodic_type: 情景类型筛选（可选，默认all）
+        current_user: 当前用户
+
+    Returns:
+        ApiResponse: 包含情景记忆分页列表
+
+    Examples:
+        - 基础分页查询：GET /episodics?end_user_id=xxx&page=1&pagesize=5
+          返回第1页，每页5条数据
+        - 按时间范围筛选：GET /episodics?end_user_id=xxx&page=1&pagesize=5&start_date=1738684800000&end_date=1738771199000
+          返回指定时间范围内的数据
+        - 按情景类型筛选：GET /episodics?end_user_id=xxx&page=1&pagesize=5&episodic_type=important_event
+          返回类型为"重要事件"的数据
+
+    Notes:
+        - start_date 和 end_date 必须同时提供或同时不提供
+        - start_date 不能大于 end_date
+        - episodic_type 可选值：all, conversation, project_work, learning, decision, important_event
+        - total 为该用户情景记忆总数（不受筛选条件影响）
+        - page.total 为筛选后的总条数
+    """
+    workspace_id = current_user.current_workspace_id
+
+    # 检查用户是否已选择工作空间
+    if workspace_id is None:
+        api_logger.warning(f"用户 {current_user.username} 尝试查询情景记忆列表但未选择工作空间")
+        return fail(BizCode.INVALID_PARAMETER, "请先切换到一个工作空间", "current_workspace_id is None")
+
+    api_logger.info(
+        f"情景记忆分页查询: end_user_id={end_user_id}, "
+        f"start_date={start_date}, end_date={end_date}, episodic_type={episodic_type}, "
+        f"page={page}, pagesize={pagesize}, username={current_user.username}"
+    )
+
+    # 1. 参数校验
+    if page < 1 or pagesize < 1:
+        api_logger.warning(f"分页参数错误: page={page}, pagesize={pagesize}")
+        return fail(BizCode.INVALID_PARAMETER, "分页参数必须大于0")
+
+    valid_episodic_types = ["all", "conversation", "project_work", "learning", "decision", "important_event"]
+    if episodic_type not in valid_episodic_types:
+        api_logger.warning(f"无效的情景类型参数: {episodic_type}")
+        return fail(BizCode.INVALID_PARAMETER, f"无效的情景类型参数，可选值：{', '.join(valid_episodic_types)}")
+
+    # 时间戳参数校验
+    if (start_date is not None and end_date is None) or (end_date is not None and start_date is None):
+        return fail(BizCode.INVALID_PARAMETER, "start_date和end_date必须同时提供")
+
+    if start_date is not None and end_date is not None and start_date > end_date:
+        return fail(BizCode.INVALID_PARAMETER, "start_date不能大于end_date")
+
+    # 2. 执行查询
+    try:
+        result = await memory_explicit_service.get_episodic_memory_list(
+            end_user_id=end_user_id,
+            page=page,
+            pagesize=pagesize,
+            start_date=start_date,
+            end_date=end_date,
+            episodic_type=episodic_type,
+        )
+        api_logger.info(
+            f"情景记忆分页查询成功: end_user_id={end_user_id}, "
+            f"total={result['total']}, 返回={len(result['items'])}条"
+        )
+    except Exception as e:
+        api_logger.error(f"情景记忆分页查询失败: end_user_id={end_user_id}, error={str(e)}")
+        return fail(BizCode.INTERNAL_ERROR, "情景记忆分页查询失败", str(e))
+
+    # 3. 返回结构化响应
+    return success(data=result, msg="查询成功")
+
+@router.get("/semantics", response_model=ApiResponse)
+async def get_semantic_memory_list_api(
+    end_user_id: str = Query(..., description="终端用户ID"),
+    current_user: User = Depends(get_current_user),
+) -> dict:
+    """
+    获取语义记忆列表
+
+    返回指定用户的全量语义记忆列表。
+
+    Args:
+        end_user_id: 终端用户ID（必填）
+        current_user: 当前用户
+
+    Returns:
+        ApiResponse: 包含语义记忆全量列表
+    """
+    workspace_id = current_user.current_workspace_id
+
+    if workspace_id is None:
+        api_logger.warning(f"用户 {current_user.username} 尝试查询语义记忆列表但未选择工作空间")
+        return fail(BizCode.INVALID_PARAMETER, "请先切换到一个工作空间", "current_workspace_id is None")
+
+    api_logger.info(
+        f"语义记忆列表查询: end_user_id={end_user_id}, username={current_user.username}"
+    )
+
+    try:
+        result = await memory_explicit_service.get_semantic_memory_list(
+            end_user_id=end_user_id
+        )
+        api_logger.info(
+            f"语义记忆列表查询成功: end_user_id={end_user_id}, total={len(result)}"
+        )
+    except Exception as e:
+        api_logger.error(f"语义记忆列表查询失败: end_user_id={end_user_id}, error={str(e)}")
+        return fail(BizCode.INTERNAL_ERROR, "语义记忆列表查询失败", str(e))
+
+    return success(data=result, msg="查询成功")
+
+
 @router.post("/details", response_model=ApiResponse)
 async def get_explicit_memory_details_api(
     request: ExplicitMemoryDetailsRequest,

api/app/controllers/memory_forget_controller.py

@@ -31,6 +31,7 @@ from app.schemas.memory_storage_schema import (
     ForgettingCurveRequest,
     ForgettingCurveResponse,
     ForgettingCurvePoint,
+    PendingNodesResponse,
 )
 from app.schemas.response_schema import ApiResponse
 from app.services.memory_forget_service import MemoryForgetService
@@ -308,6 +309,100 @@ async def get_forgetting_stats(
         return fail(BizCode.INTERNAL_ERROR, "获取遗忘引擎统计失败", str(e))
 
 
+@router.get("/pending-nodes", response_model=ApiResponse)
+async def get_pending_nodes(
+    end_user_id: str,
+    page: int = 1,
+    pagesize: int = 10,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    """
+    获取待遗忘节点列表（独立分页接口）
+
+    查询满足遗忘条件的节点（激活值低于阈值且最后访问时间超过最小天数）。
+    此接口独立分页，与 /stats 接口分离。
+
+    Args:
+        end_user_id: 组ID（即 end_user_id，必填）
+        page: 页码（从1开始，默认1）
+        pagesize: 每页数量（默认10）
+        current_user: 当前用户
+        db: 数据库会话
+
+    Returns:
+        ApiResponse: 包含待遗忘节点列表和分页信息的响应
+
+    Examples:
+        - 第1页，每页10条：GET /memory/forget-memory/pending-nodes?end_user_id=xxx&page=1&pagesize=10
+        - 第2页，每页20条：GET /memory/forget-memory/pending-nodes?end_user_id=xxx&page=2&pagesize=20
+
+    Notes:
+        - page 从1开始，pagesize 必须大于0
+        - 返回格式：{"items": [...], "page": {"page": 1, "pagesize": 10, "total": 100, "hasnext": true}}
+    """
+    workspace_id = current_user.current_workspace_id
+    # 检查用户是否已选择工作空间
+    if workspace_id is None:
+        api_logger.warning(f"用户 {current_user.username} 尝试获取待遗忘节点但未选择工作空间")
+        return fail(BizCode.INVALID_PARAMETER, "请先切换到一个工作空间", "current_workspace_id is None")
+
+    # 验证 end_user_id 必填
+    if not end_user_id:
+        api_logger.warning(f"用户 {current_user.username} 尝试获取待遗忘节点但未提供 end_user_id")
+        return fail(BizCode.INVALID_PARAMETER, "end_user_id 不能为空", "end_user_id is required")
+
+    # 通过 end_user_id 获取关联的 config_id
+    try:
+        from app.services.memory_agent_service import get_end_user_connected_config
+
+        connected_config = get_end_user_connected_config(end_user_id, db)
+        config_id = connected_config.get("memory_config_id")
+        config_id = resolve_config_id(config_id, db)
+
+        if config_id is None:
+            api_logger.warning(f"终端用户 {end_user_id} 未关联记忆配置")
+            return fail(BizCode.INVALID_PARAMETER, f"终端用户 {end_user_id} 未关联记忆配置", "memory_config_id is None")
+
+        api_logger.debug(f"通过 end_user_id={end_user_id} 获取到 config_id={config_id}")
+    except ValueError as e:
+        api_logger.warning(f"获取终端用户配置失败: {str(e)}")
+        return fail(BizCode.INVALID_PARAMETER, str(e), "ValueError")
+    except Exception as e:
+        api_logger.error(f"获取终端用户配置时发生错误: {str(e)}")
+        return fail(BizCode.INTERNAL_ERROR, "获取终端用户配置失败", str(e))
+
+    # 验证分页参数
+    if page < 1:
+        return fail(BizCode.INVALID_PARAMETER, "page 必须大于等于1", "page < 1")
+    if pagesize < 1:
+        return fail(BizCode.INVALID_PARAMETER, "pagesize 必须大于等于1", "pagesize < 1")
+
+    api_logger.info(
+        f"用户 {current_user.username} 在工作空间 {workspace_id} 请求获取待遗忘节点: "
+        f"end_user_id={end_user_id}, page={page}, pagesize={pagesize}"
+    )
+
+    try:
+        # 调用服务层获取待遗忘节点列表
+        result = await forget_service.get_pending_nodes(
+            db=db,
+            end_user_id=end_user_id,
+            config_id=config_id,
+            page=page,
+            pagesize=pagesize
+        )
+
+        # 构建响应
+        response_data = PendingNodesResponse(**result)
+
+        return success(data=response_data.model_dump(), msg="查询成功")
+
+    except Exception as e:
+        api_logger.error(f"获取待遗忘节点列表失败: {str(e)}")
+        return fail(BizCode.INTERNAL_ERROR, "获取待遗忘节点列表失败", str(e))
+
+
 @router.post("/forgetting_curve", response_model=ApiResponse)
 async def get_forgetting_curve(
     request: ForgettingCurveRequest,

api/app/controllers/memory_reflection_controller.py

@@ -1,3 +1,19 @@
+"""
+Memory Reflection Controller
+
+This module provides REST API endpoints for managing memory reflection configurations
+and operations. It handles reflection engine setup, configuration management, and
+execution of self-reflection processes across memory systems.
+
+Key Features:
+- Reflection configuration management (save, retrieve, update)
+- Workspace-wide reflection execution across multiple applications
+- Individual configuration-based reflection runs
+- Multi-language support for reflection outputs
+- Integration with Neo4j memory storage and LLM models
+- Comprehensive error handling and logging
+"""
+
 import asyncio
 import time
 import uuid
@@ -28,9 +44,13 @@ from sqlalchemy.orm import Session
 
 from app.utils.config_utils import resolve_config_id
 
+# Load environment variables for configuration
 load_dotenv()
+
+# Initialize API logger for request tracking and debugging
 api_logger = get_api_logger()
 
+# Configure router with prefix and tags for API organization
 router = APIRouter(
     prefix="/memory",
     tags=["Memory"],
@@ -43,7 +63,38 @@ async def save_reflection_config(
     current_user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    """Save reflection configuration to data_comfig table"""
+    """
+    Save reflection configuration to memory config table
+    
+    Persists reflection engine configuration settings to the data_config table,
+    including reflection parameters, model settings, and evaluation criteria.
+    Validates configuration parameters and ensures data consistency.
+    
+    Args:
+        request: Memory reflection configuration data including:
+            - config_id: Configuration identifier to update
+            - reflection_enabled: Whether reflection is enabled
+            - reflection_period_in_hours: Reflection execution interval
+            - reflexion_range: Scope of reflection (partial/all)
+            - baseline: Reflection strategy (time/fact/hybrid)
+            - reflection_model_id: LLM model for reflection operations
+            - memory_verify: Enable memory verification checks
+            - quality_assessment: Enable quality assessment evaluation
+        current_user: Authenticated user saving the configuration
+        db: Database session for data operations
+    
+    Returns:
+        dict: Success response with saved reflection configuration data
+        
+    Raises:
+        HTTPException 400: If config_id is missing or parameters are invalid
+        HTTPException 500: If configuration save operation fails
+        
+    Database Operations:
+        - Updates memory_config table with reflection settings
+        - Commits transaction and refreshes entity
+        - Maintains configuration consistency
+    """
     try:
         config_id = request.config_id
         config_id = resolve_config_id(config_id, db)
@@ -54,6 +105,7 @@ async def save_reflection_config(
             )
         api_logger.info(f"用户 {current_user.username} 保存反思配置，config_id: {config_id}")
 
+        # Update reflection configuration in database
         memory_config = MemoryConfigRepository.update_reflection_config(
             db,
             config_id=config_id,
@@ -66,6 +118,7 @@ async def save_reflection_config(
             quality_assessment=request.quality_assessment
         )
 
+        # Commit transaction and refresh entity
         db.commit()
         db.refresh(memory_config)
 
@@ -102,13 +155,55 @@ async def start_workspace_reflection(
     current_user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    """启动工作空间中所有匹配应用的反思功能"""
+    """
+    Start reflection functionality for all matching applications in workspace
+    
+    Initiates reflection processes across all applications within the user's current
+    workspace that have valid memory configurations. Processes each application's
+    configurations and associated end users, executing reflection operations
+    with proper error isolation and transaction management.
+    
+    This endpoint serves as a workspace-wide reflection orchestrator, ensuring
+    that reflection failures for individual users don't affect other operations.
+    
+    Args:
+        current_user: Authenticated user initiating workspace reflection
+        db: Database session for configuration queries
+    
+    Returns:
+        dict: Success response with reflection results for all processed applications:
+            - app_id: Application identifier
+            - config_id: Memory configuration identifier
+            - end_user_id: End user identifier
+            - reflection_result: Individual reflection operation result
+    
+    Processing Logic:
+        1. Retrieve all applications in the current workspace
+        2. Filter applications with valid memory configurations
+        3. For each configuration, find matching releases
+        4. Execute reflection for each end user with isolated transactions
+        5. Aggregate results with error handling per user
+    
+    Error Handling:
+        - Individual user reflection failures are isolated
+        - Failed operations are logged and included in results
+        - Database transactions are isolated per user to prevent cascading failures
+        - Comprehensive error reporting for debugging
+    
+    Raises:
+        HTTPException 500: If workspace reflection initialization fails
+        
+    Performance Notes:
+        - Uses independent database sessions for each user operation
+        - Prevents transaction failures from affecting other users
+        - Comprehensive logging for operation tracking
+    """
     workspace_id = current_user.current_workspace_id
 
     try:
         api_logger.info(f"用户 {current_user.username} 启动workspace反思，workspace_id: {workspace_id}")
 
-        # 使用独立的数据库会话来获取工作空间应用详情，避免事务失败
+        # Use independent database session to get workspace app details, avoiding transaction failures
         from app.db import get_db_context
         with get_db_context() as query_db:
             service = WorkspaceAppService(query_db)
@@ -116,8 +211,9 @@ async def start_workspace_reflection(
         
         reflection_results = []
         
+        # Process each application in the workspace
         for data in result['apps_detailed_info']:
-            # 跳过没有配置的应用
+            # Skip applications without configurations
             if not data['memory_configs']:
                 api_logger.debug(f"应用 {data['id']} 没有memory_configs，跳过")
                 continue
@@ -126,22 +222,22 @@ async def start_workspace_reflection(
             memory_configs = data['memory_configs']
             end_users = data['end_users']
 
-            # 为每个配置和用户组合执行反思
+            # Execute reflection for each configuration and user combination
             for config in memory_configs:
                 config_id_str = str(config['config_id'])
 
-                # 找到匹配此配置的所有release
+                # Find all releases matching this configuration
                 matching_releases = [r for r in releases if str(r['config']) == config_id_str]
 
                 if not matching_releases:
                     api_logger.debug(f"配置 {config_id_str} 没有匹配的release")
                     continue
 
-                # 为每个用户执行反思 - 使用独立的数据库会话
+                # Execute reflection for each user - using independent database sessions
                 for user in end_users:
                     api_logger.info(f"为用户 {user['id']} 启动反思，config_id: {config_id_str}")
 
-                    # 为每个用户创建独立的数据库会话，避免事务失败影响其他用户
+                    # Create independent database session for each user to avoid transaction failure impact
                     with get_db_context() as user_db:
                         try:
                             reflection_service = MemoryReflectionService(user_db)
@@ -184,14 +280,51 @@ async def start_reflection_configs(
         current_user: User = Depends(get_current_user),
         db: Session = Depends(get_db),
 ) -> dict:
-    """通过config_id查询memory_config表中的反思配置信息"""
+    """
+    Query reflection configuration information by config_id
+    
+    Retrieves detailed reflection configuration settings from the memory_config
+    table for a specific configuration ID. Provides comprehensive reflection
+    parameters including model settings, evaluation criteria, and operational flags.
+    
+    Args:
+        config_id: Configuration identifier (UUID or integer) to query
+        current_user: Authenticated user making the request
+        db: Database session for data operations
+    
+    Returns:
+        dict: Success response with detailed reflection configuration:
+            - config_id: Resolved configuration identifier
+            - reflection_enabled: Whether reflection is enabled for this config
+            - reflection_period_in_hours: Reflection execution interval
+            - reflexion_range: Scope of reflection operations (partial/all)
+            - baseline: Reflection strategy (time/fact/hybrid)
+            - reflection_model_id: LLM model identifier for reflection
+            - memory_verify: Memory verification flag
+            - quality_assessment: Quality assessment flag
+    
+    Database Operations:
+        - Queries memory_config table by resolved config_id
+        - Retrieves all reflection-related configuration fields
+        - Resolves configuration ID for consistent formatting
+    
+    Raises:
+        HTTPException 404: If configuration with specified ID is not found
+        HTTPException 500: If configuration query operation fails
+        
+    ID Resolution:
+        - Supports both UUID and integer config_id formats
+        - Automatically resolves to appropriate internal format
+        - Maintains consistency across different ID representations
+    """
     config_id = resolve_config_id(config_id, db)
     try:
         config_id=resolve_config_id(config_id,db)
         api_logger.info(f"用户 {current_user.username} 查询反思配置，config_id: {config_id}")
         result = MemoryConfigRepository.query_reflection_config_by_id(db, config_id)
         memory_config_id = resolve_config_id(result.config_id, db)
-        # 构建返回数据
+        
+        # Build response data with comprehensive configuration details
         reflection_config = {
             "config_id": memory_config_id,
             "reflection_enabled": result.enable_self_reflexion,
@@ -204,10 +337,12 @@ async def start_reflection_configs(
         }
         api_logger.info(f"成功查询反思配置，config_id: {config_id}")
         return success(data=reflection_config, msg="反思配置查询成功")
-        
 
+        api_logger.info(f"Successfully queried reflection config, config_id: {config_id}")
+        return success(data=reflection_config, msg="Reflection configuration query successful")
+        
     except HTTPException:
-        # 重新抛出HTTP异常
+        # Re-raise HTTP exceptions without modification
         raise
     except Exception as e:
         api_logger.error(f"查询反思配置失败: {str(e)}")
@@ -223,13 +358,66 @@ async def reflection_run(
     current_user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    """Activate the reflection function for all matching applications in the workspace"""
-    # 使用集中化的语言校验
+    """
+    Execute reflection engine with specified configuration
+    
+    Runs the reflection engine using configuration parameters from the database.
+    Validates model availability, sets up the reflection engine with proper
+    configuration, and executes the reflection process with multi-language support.
+    
+    This endpoint provides a test run capability for reflection configurations,
+    allowing users to validate their reflection settings and see results before
+    deploying to production environments.
+    
+    Args:
+        config_id: Configuration identifier (UUID or integer) for reflection settings
+        language_type: Language preference header for output localization (optional)
+        current_user: Authenticated user executing the reflection
+        db: Database session for configuration queries
+    
+    Returns:
+        dict: Success response with reflection execution results including:
+            - baseline: Reflection strategy used
+            - source_data: Input data processed
+            - memory_verifies: Memory verification results (if enabled)
+            - quality_assessments: Quality assessment results (if enabled)
+            - reflexion_data: Generated reflection insights and solutions
+    
+    Configuration Validation:
+        - Verifies configuration exists in database
+        - Validates LLM model availability
+        - Falls back to default model if specified model is unavailable
+        - Ensures all required parameters are properly set
+    
+    Reflection Engine Setup:
+        - Creates ReflectionConfig with database parameters
+        - Initializes Neo4j connector for memory access
+        - Sets up ReflectionEngine with validated model
+        - Configures language preferences for output
+    
+    Error Handling:
+        - Model validation with fallback to default
+        - Configuration validation and error reporting
+        - Comprehensive logging for debugging
+        - Graceful handling of missing configurations
+    
+    Raises:
+        HTTPException 404: If configuration is not found
+        HTTPException 500: If reflection execution fails
+        
+    Performance Notes:
+        - Direct database query for configuration retrieval
+        - Model validation to prevent runtime failures
+        - Efficient reflection engine initialization
+        - Language-aware output processing
+    """
+    # Use centralized language validation for consistent localization
     language = get_language_from_header(language_type)
 
     api_logger.info(f"用户 {current_user.username} 查询反思配置，config_id: {config_id}")
     config_id = resolve_config_id(config_id, db)
-    # 使用MemoryConfigRepository查询反思配置
+    
+    # Query reflection configuration using MemoryConfigRepository
     result = MemoryConfigRepository.query_reflection_config_by_id(db, config_id)
     if not result:
         raise HTTPException(
@@ -239,7 +427,7 @@ async def reflection_run(
 
     api_logger.info(f"成功查询反思配置，config_id: {config_id}")
 
-    # 验证模型ID是否存在
+    # Validate model ID existence
     model_id = result.reflection_model_id
     if model_id:
         try:
@@ -250,6 +438,7 @@ async def reflection_run(
             # 可以设置为None，让反思引擎使用默认模型
             model_id = None
 
+    # Create reflection configuration with database parameters
     config = ReflectionConfig(
         enabled=result.enable_self_reflexion,
         iteration_period=result.iteration_period,
@@ -262,11 +451,13 @@ async def reflection_run(
         model_id=model_id,
         language_type=language_type
     )
+    
+    # Initialize Neo4j connector and reflection engine
     connector = Neo4jConnector()
     engine = ReflectionEngine(
         config=config,
         neo4j_connector=connector,
-        llm_client=model_id  # 传入验证后的 model_id
+        llm_client=model_id  # Pass validated model_id
     )
 
     result=await (engine.reflection_run())

api/app/controllers/memory_short_term_controller.py

@@ -1,19 +1,40 @@
-from fastapi import APIRouter, Depends, HTTPException, status,Header
+"""
+Memory Short Term Controller
+
+This module provides REST API endpoints for managing short-term and long-term memory
+data retrieval and analysis. It handles memory system statistics, data aggregation,
+and provides comprehensive memory insights for end users.
+
+Key Features:
+- Short-term memory data retrieval and statistics
+- Long-term memory data aggregation
+- Entity count integration
+- Multi-language response support
+- Memory system analytics and reporting
+"""
+
+from typing import Optional
+
+from dotenv import load_dotenv
+from fastapi import APIRouter, Depends, Header, HTTPException, status
+from sqlalchemy.orm import Session
+
 from app.core.language_utils import get_language_from_header
 from app.core.logging_config import get_api_logger
 from app.core.response_utils import success
 from app.db import get_db
 from app.dependencies import get_current_user
 from app.models.user_model import User
-
+from app.services.memory_short_service import LongService, ShortService
 from app.services.memory_storage_service import search_entity
-from app.services.memory_short_service import ShortService,LongService
-from dotenv import load_dotenv
-from sqlalchemy.orm import Session
-from typing import Optional
+
+# Load environment variables for configuration
 load_dotenv()
+
+# Initialize API logger for request tracking and debugging
 api_logger = get_api_logger()
 
+# Configure router with prefix and tags for API organization
 router = APIRouter(
     prefix="/memory/short",
     tags=["Memory"],
@@ -25,24 +46,73 @@ async def short_term_configs(
         current_user: User = Depends(get_current_user),
         db: Session = Depends(get_db),
 ):
-    # 使用集中化的语言校验
+    """
+    Retrieve comprehensive short-term and long-term memory statistics
+    
+    Provides a comprehensive overview of memory system data for a specific end user,
+    including short-term memory entries, long-term memory aggregations, entity counts,
+    and retrieval statistics. Supports multi-language responses based on request headers.
+    
+    This endpoint serves as a central dashboard for memory system analytics, combining
+    data from multiple memory subsystems to provide a holistic view of user memory state.
+    
+    Args:
+        end_user_id: Unique identifier for the end user whose memory data to retrieve
+        language_type: Language preference header for response localization (optional)
+        current_user: Authenticated user making the request (injected by dependency)
+        db: Database session for data operations (injected by dependency)
+    
+    Returns:
+        dict: Success response containing comprehensive memory statistics:
+            - short_term: List of short-term memory entries with detailed data
+            - long_term: List of long-term memory aggregations and summaries
+            - entity: Count of entities associated with the end user
+            - retrieval_number: Total count of short-term memory retrievals
+            - long_term_number: Total count of long-term memory entries
+    
+    Response Structure:
+        {
+            "code": 200,
+            "msg": "Short-term memory system data retrieved successfully",
+            "data": {
+                "short_term": [...],      # Short-term memory entries
+                "long_term": [...],       # Long-term memory data
+                "entity": 42,             # Entity count
+                "retrieval_number": 156,  # Short-term retrieval count
+                "long_term_number": 23    # Long-term memory count
+            }
+        }
+    
+    Raises:
+        HTTPException: If end_user_id is invalid or data retrieval fails
+        
+    Performance Notes:
+        - Combines multiple service calls for comprehensive data
+        - Entity search is performed asynchronously for better performance
+        - Response time depends on memory data volume for the specified user
+    """
+    # Use centralized language validation for consistent localization
     language = get_language_from_header(language_type)
     
-    # 获取短期记忆数据
-    short_term=ShortService(end_user_id)
-    short_result=short_term.get_short_databasets()
-    short_count=short_term.get_short_count()
+    # Retrieve short-term memory data and statistics
+    short_term = ShortService(end_user_id, db)
+    short_result = short_term.get_short_databasets()  # Get short-term memory entries
+    short_count = short_term.get_short_count()        # Get short-term retrieval count
 
-    long_term=LongService(end_user_id)
-    long_result=long_term.get_long_databasets()
+    # Retrieve long-term memory data and aggregations
+    long_term = LongService(end_user_id, db)
+    long_result = long_term.get_long_databasets()     # Get long-term memory entries
 
+    # Get entity count for the specified end user
     entity_result = await search_entity(end_user_id)
+    
+    # Compile comprehensive memory statistics response
     result = {
-        'short_term': short_result,
-        'long_term': long_result,
-        'entity': entity_result.get('num', 0),
-        "retrieval_number":short_count,
-        "long_term_number":len(long_result)
+        'short_term': short_result,                    # Short-term memory entries
+        'long_term': long_result,                      # Long-term memory data
+        'entity': entity_result.get('num', 0),        # Entity count (default to 0 if not found)
+        "retrieval_number": short_count,               # Short-term retrieval statistics
+        "long_term_number": len(long_result)          # Long-term memory entry count
     }
 
     return success(data=result, msg="短期记忆系统数据获取成功")

api/app/controllers/memory_storage_controller.py

@@ -2,7 +2,7 @@ from typing import Optional
 from uuid import UUID
 
 from fastapi import APIRouter, Depends, Query
-from fastapi.responses import StreamingResponse
+from fastapi.responses import StreamingResponse, JSONResponse
 from sqlalchemy.orm import Session
 
 from app.core.error_codes import BizCode
@@ -26,7 +26,7 @@ from app.services.memory_storage_service import (
     analytics_hot_memory_tags,
     analytics_recent_activity_stats,
     kb_type_distribution,
-    search_all,
+    search_all_batch,
     search_chunk,
     search_detials,
     search_dialogue,
@@ -34,6 +34,7 @@ from app.services.memory_storage_service import (
     search_entity,
     search_statement,
 )
+from app.core.quota_stub import check_memory_engine_quota
 from fastapi import APIRouter, Depends, Header
 from fastapi.responses import StreamingResponse
 from sqlalchemy.orm import Session
@@ -54,8 +55,8 @@ router = APIRouter(
 
 @router.get("/info", response_model=ApiResponse)
 async def get_storage_info(
-    storage_id: str,
-    current_user: User = Depends(get_current_user)
+        storage_id: str,
+        current_user: User = Depends(get_current_user)
 ):
     """
     Example wrapper endpoint - retrieves storage information
@@ -75,23 +76,20 @@ async def get_storage_info(
         return fail(BizCode.INTERNAL_ERROR, "存储信息获取失败", str(e))
 
 
-
-
-
-
-
-@router.post("/create_config", response_model=ApiResponse)   # 创建配置文件，其他参数默认
+@router.post("/create_config", response_model=ApiResponse)  # 创建配置文件，其他参数默认
+@check_memory_engine_quota
 def create_config(
-    payload: ConfigParamsCreate,
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db),
+        payload: ConfigParamsCreate,
+        current_user: User = Depends(get_current_user),
+        db: Session = Depends(get_db),
+        x_language_type: Optional[str] = Header(None, alias="X-Language-Type"),
 ) -> dict:
     workspace_id = current_user.current_workspace_id
     # 检查用户是否已选择工作空间
     if workspace_id is None:
         api_logger.warning(f"用户 {current_user.username} 尝试创建配置但未选择工作空间")
         return fail(BizCode.INVALID_PARAMETER, "请先切换到一个工作空间", "current_workspace_id is None")
-    
+
     api_logger.info(f"用户 {current_user.username} 在工作空间 {workspace_id} 请求创建配置: {payload.config_name}")
     try:
         # 将 workspace_id 注入到 payload 中（保持为 UUID 类型）
@@ -99,17 +97,43 @@ def create_config(
         svc = DataConfigService(db)
         result = svc.create(payload)
         return success(data=result, msg="创建成功")
+    except ValueError as e:
+        err_str = str(e)
+        if err_str.startswith("DUPLICATE_CONFIG_NAME:"):
+            config_name = err_str.split(":", 1)[1]
+            api_logger.warning(f"重复的配置名称 '{config_name}' 在工作空间 {workspace_id}")
+            lang = get_language_from_header(x_language_type)
+            if lang == "en":
+                msg = fail(BizCode.BAD_REQUEST, "Config name already exists",
+                           f"A config named \"{config_name}\" already exists in the current workspace. Please use a different name.")
+            else:
+                msg = fail(BizCode.BAD_REQUEST, "配置名称已存在",
+                           f"当前工作空间下已存在名为「{config_name}」的记忆配置，请使用其他名称")
+            return JSONResponse(status_code=400, content=msg)
+        api_logger.error(f"Create config failed: {err_str}")
+        return fail(BizCode.INTERNAL_ERROR, "创建配置失败", err_str)
     except Exception as e:
+        from sqlalchemy.exc import IntegrityError
+        if isinstance(e, IntegrityError) and "uq_workspace_config_name" in str(getattr(e, 'orig', '')):
+            api_logger.warning(f"重复的配置名称 '{payload.config_name}' 在工作空间 {workspace_id}")
+            lang = get_language_from_header(x_language_type)
+            if lang == "en":
+                msg = fail(BizCode.BAD_REQUEST, "Config name already exists",
+                           f"A config named \"{payload.config_name}\" already exists in the current workspace. Please use a different name.")
+            else:
+                msg = fail(BizCode.BAD_REQUEST, "配置名称已存在",
+                           f"当前工作空间下已存在名为「{payload.config_name}」的记忆配置，请使用其他名称")
+            return JSONResponse(status_code=400, content=msg)
         api_logger.error(f"Create config failed: {str(e)}")
         return fail(BizCode.INTERNAL_ERROR, "创建配置失败", str(e))
 
 
 @router.delete("/delete_config", response_model=ApiResponse)  # 删除数据库中的内容（按配置名称）
 def delete_config(
-    config_id: UUID|int,
-    force: bool = Query(False, description="是否强制删除（即使有终端用户正在使用）"),
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db),
+        config_id: UUID | int,
+        force: bool = Query(False, description="是否强制删除（即使有终端用户正在使用）"),
+        current_user: User = Depends(get_current_user),
+        db: Session = Depends(get_db),
 ) -> dict:
     """删除记忆配置（带终端用户保护）
     
@@ -122,24 +146,24 @@ def delete_config(
         force: 设置为 true 可强制删除（即使有终端用户正在使用）
     """
     workspace_id = current_user.current_workspace_id
-    config_id=resolve_config_id(config_id, db)
+    config_id = resolve_config_id(config_id, db)
     # 检查用户是否已选择工作空间
     if workspace_id is None:
         api_logger.warning(f"用户 {current_user.username} 尝试删除配置但未选择工作空间")
         return fail(BizCode.INVALID_PARAMETER, "请先切换到一个工作空间", "current_workspace_id is None")
-    
+
     api_logger.info(
         f"用户 {current_user.username} 在工作空间 {workspace_id} 请求删除配置: "
         f"config_id={config_id}, force={force}"
     )
-    
+
     try:
         # 使用带保护的删除服务
         from app.services.memory_config_service import MemoryConfigService
-        
+
         config_service = MemoryConfigService(db)
         result = config_service.delete_config(config_id=config_id, force=force)
-        
+
         if result["status"] == "error":
             api_logger.warning(
                 f"记忆配置删除被拒绝: config_id={config_id}, reason={result['message']}"
@@ -149,7 +173,7 @@ def delete_config(
                 msg=result["message"],
                 data={"config_id": str(config_id), "is_default": result.get("is_default", False)}
             )
-        
+
         if result["status"] == "warning":
             api_logger.warning(
                 f"记忆配置正在使用，无法删除: config_id={config_id}, "
@@ -163,7 +187,7 @@ def delete_config(
                     "force_required": result["force_required"]
                 }
             )
-        
+
         api_logger.info(
             f"记忆配置删除成功: config_id={config_id}, "
             f"affected_users={result['affected_users']}"
@@ -172,7 +196,7 @@ def delete_config(
             msg=result["message"],
             data={"affected_users": result["affected_users"]}
         )
-        
+
     except Exception as e:
         api_logger.error(f"Delete config failed: {str(e)}", exc_info=True)
         return fail(BizCode.INTERNAL_ERROR, "删除配置失败", str(e))
@@ -180,9 +204,9 @@ def delete_config(
 
 @router.post("/update_config", response_model=ApiResponse)  # 更新配置文件中name和desc
 def update_config(
-    payload: ConfigUpdate,
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db),
+        payload: ConfigUpdate,
+        current_user: User = Depends(get_current_user),
+        db: Session = Depends(get_db),
 ) -> dict:
     workspace_id = current_user.current_workspace_id
     payload.config_id = resolve_config_id(payload.config_id, db)
@@ -190,12 +214,13 @@ def update_config(
     if workspace_id is None:
         api_logger.warning(f"用户 {current_user.username} 尝试更新配置但未选择工作空间")
         return fail(BizCode.INVALID_PARAMETER, "请先切换到一个工作空间", "current_workspace_id is None")
-    
+
     # 校验至少有一个字段需要更新
     if payload.config_name is None and payload.config_desc is None and payload.scene_id is None:
         api_logger.warning(f"用户 {current_user.username} 尝试更新配置但未提供任何更新字段")
-        return fail(BizCode.INVALID_PARAMETER, "请至少提供一个需要更新的字段", "config_name, config_desc, scene_id 均为空")
-    
+        return fail(BizCode.INVALID_PARAMETER, "请至少提供一个需要更新的字段",
+                    "config_name, config_desc, scene_id 均为空")
+
     api_logger.info(f"用户 {current_user.username} 在工作空间 {workspace_id} 请求更新配置: {payload.config_id}")
     try:
         svc = DataConfigService(db)
@@ -208,9 +233,9 @@ def update_config(
 
 @router.post("/update_config_extracted", response_model=ApiResponse)  # 更新数据库中的部分内容 所有业务字段均可选
 def update_config_extracted(
-    payload: ConfigUpdateExtracted,
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db),
+        payload: ConfigUpdateExtracted,
+        current_user: User = Depends(get_current_user),
+        db: Session = Depends(get_db),
 ) -> dict:
     workspace_id = current_user.current_workspace_id
     payload.config_id = resolve_config_id(payload.config_id, db)
@@ -218,7 +243,7 @@ def update_config_extracted(
     if workspace_id is None:
         api_logger.warning(f"用户 {current_user.username} 尝试更新提取配置但未选择工作空间")
         return fail(BizCode.INVALID_PARAMETER, "请先切换到一个工作空间", "current_workspace_id is None")
-    
+
     api_logger.info(f"用户 {current_user.username} 在工作空间 {workspace_id} 请求更新提取配置: {payload.config_id}")
     try:
         svc = DataConfigService(db)
@@ -233,11 +258,11 @@ def update_config_extracted(
 # 遗忘引擎配置接口已迁移到 memory_forget_controller.py
 # 使用新接口: /api/memory/forget/read_config 和 /api/memory/forget/update_config
 
-@router.get("/read_config_extracted", response_model=ApiResponse) # 通过查询参数读取某条配置（固定路径） 没有意义的话就删除
+@router.get("/read_config_extracted", response_model=ApiResponse)  # 通过查询参数读取某条配置（固定路径） 没有意义的话就删除
 def read_config_extracted(
-    config_id: UUID | int,
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db),
+        config_id: UUID | int,
+        current_user: User = Depends(get_current_user),
+        db: Session = Depends(get_db),
 ) -> dict:
     workspace_id = current_user.current_workspace_id
     config_id = resolve_config_id(config_id, db)
@@ -245,7 +270,7 @@ def read_config_extracted(
     if workspace_id is None:
         api_logger.warning(f"用户 {current_user.username} 尝试读取提取配置但未选择工作空间")
         return fail(BizCode.INVALID_PARAMETER, "请先切换到一个工作空间", "current_workspace_id is None")
-    
+
     api_logger.info(f"用户 {current_user.username} 在工作空间 {workspace_id} 请求读取提取配置: {config_id}")
     try:
         svc = DataConfigService(db)
@@ -255,18 +280,19 @@ def read_config_extracted(
         api_logger.error(f"Read config extracted failed: {str(e)}")
         return fail(BizCode.INTERNAL_ERROR, "查询配置失败", str(e))
 
-@router.get("/read_all_config", response_model=ApiResponse) # 读取所有配置文件列表
+
+@router.get("/read_all_config", response_model=ApiResponse)  # 读取所有配置文件列表
 def read_all_config(
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db),
+        current_user: User = Depends(get_current_user),
+        db: Session = Depends(get_db),
 ) -> dict:
     workspace_id = current_user.current_workspace_id
-    
+
     # 检查用户是否已选择工作空间
     if workspace_id is None:
         api_logger.warning(f"用户 {current_user.username} 尝试查询配置但未选择工作空间")
         return fail(BizCode.INVALID_PARAMETER, "请先切换到一个工作空间", "current_workspace_id is None")
-    
+
     api_logger.info(f"用户 {current_user.username} 在工作空间 {workspace_id} 请求读取所有配置")
     try:
         svc = DataConfigService(db)
@@ -280,14 +306,14 @@ def read_all_config(
 
 @router.post("/pilot_run", response_model=None)
 async def pilot_run(
-    payload: ConfigPilotRun,
-    language_type: str = Header(default=None, alias="X-Language-Type"),
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db),
+        payload: ConfigPilotRun,
+        language_type: str = Header(default=None, alias="X-Language-Type"),
+        current_user: User = Depends(get_current_user),
+        db: Session = Depends(get_db),
 ) -> StreamingResponse:
     # 使用集中化的语言校验
     language = get_language_from_header(language_type)
-    
+
     api_logger.info(
         f"Pilot run requested: config_id={payload.config_id}, "
         f"dialogue_text_length={len(payload.dialogue_text)}, "
@@ -310,9 +336,9 @@ async def pilot_run(
 
 @router.get("/search/kb_type_distribution", response_model=ApiResponse)
 async def get_kb_type_distribution(
-    end_user_id: Optional[str] = None,
-    current_user: User = Depends(get_current_user),
-    ) -> dict:
+        end_user_id: Optional[str] = None,
+        current_user: User = Depends(get_current_user),
+) -> dict:
     api_logger.info(f"KB type distribution requested for end_user_id: {end_user_id}")
     try:
         result = await kb_type_distribution(end_user_id)
@@ -321,12 +347,12 @@ async def get_kb_type_distribution(
         api_logger.error(f"KB type distribution failed: {str(e)}")
         return fail(BizCode.INTERNAL_ERROR, "知识库类型分布查询失败", str(e))
 
-    
+
 @router.get("/search/dialogue", response_model=ApiResponse)
 async def search_dialogues_num(
-    end_user_id: Optional[str] = None,
-    current_user: User = Depends(get_current_user),
-    ) -> dict:
+        end_user_id: Optional[str] = None,
+        current_user: User = Depends(get_current_user),
+) -> dict:
     api_logger.info(f"Search dialogue requested for end_user_id: {end_user_id}")
     try:
         result = await search_dialogue(end_user_id)
@@ -338,9 +364,9 @@ async def search_dialogues_num(
 
 @router.get("/search/chunk", response_model=ApiResponse)
 async def search_chunks_num(
-    end_user_id: Optional[str] = None,
-    current_user: User = Depends(get_current_user),
-    ) -> dict:
+        end_user_id: Optional[str] = None,
+        current_user: User = Depends(get_current_user),
+) -> dict:
     api_logger.info(f"Search chunk requested for end_user_id: {end_user_id}")
     try:
         result = await search_chunk(end_user_id)
@@ -352,9 +378,9 @@ async def search_chunks_num(
 
 @router.get("/search/statement", response_model=ApiResponse)
 async def search_statements_num(
-    end_user_id: Optional[str] = None,
-    current_user: User = Depends(get_current_user),
-    ) -> dict:
+        end_user_id: Optional[str] = None,
+        current_user: User = Depends(get_current_user),
+) -> dict:
     api_logger.info(f"Search statement requested for end_user_id: {end_user_id}")
     try:
         result = await search_statement(end_user_id)
@@ -366,9 +392,9 @@ async def search_statements_num(
 
 @router.get("/search/entity", response_model=ApiResponse)
 async def search_entities_num(
-    end_user_id: Optional[str] = None,
-    current_user: User = Depends(get_current_user),
-    ) -> dict:
+        end_user_id: Optional[str] = None,
+        current_user: User = Depends(get_current_user),
+) -> dict:
     api_logger.info(f"Search entity requested for end_user_id: {end_user_id}")
     try:
         result = await search_entity(end_user_id)
@@ -380,12 +406,15 @@ async def search_entities_num(
 
 @router.get("/search", response_model=ApiResponse)
 async def search_all_num(
-    end_user_id: Optional[str] = None,
-    current_user: User = Depends(get_current_user),
-    ) -> dict:
+        end_user_id: Optional[str] = None,
+        current_user: User = Depends(get_current_user),
+) -> dict:
     api_logger.info(f"Search all requested for end_user_id: {end_user_id}")
     try:
-        result = await search_all(end_user_id)
+        if not end_user_id:
+            return success(data={"total": 0}, msg="查询成功")
+        batch_result = await search_all_batch([end_user_id])
+        result = {"total": batch_result.get(end_user_id, 0)}
         return success(data=result, msg="查询成功")
     except Exception as e:
         api_logger.error(f"Search all failed: {str(e)}")
@@ -394,9 +423,9 @@ async def search_all_num(
 
 @router.get("/search/detials", response_model=ApiResponse)
 async def search_entities_detials(
-    end_user_id: Optional[str] = None,
-    current_user: User = Depends(get_current_user),
-    ) -> dict:
+        end_user_id: Optional[str] = None,
+        current_user: User = Depends(get_current_user),
+) -> dict:
     api_logger.info(f"Search details requested for end_user_id: {end_user_id}")
     try:
         result = await search_detials(end_user_id)
@@ -408,9 +437,9 @@ async def search_entities_detials(
 
 @router.get("/search/edges", response_model=ApiResponse)
 async def search_entity_edges(
-    end_user_id: Optional[str] = None,
-    current_user: User = Depends(get_current_user),
-    ) -> dict:
+        end_user_id: Optional[str] = None,
+        current_user: User = Depends(get_current_user),
+) -> dict:
     api_logger.info(f"Search edges requested for end_user_id: {end_user_id}")
     try:
         result = await search_edges(end_user_id)
@@ -420,14 +449,12 @@ async def search_entity_edges(
         return fail(BizCode.INTERNAL_ERROR, "边查询失败", str(e))
 
 
-
-
 @router.get("/analytics/hot_memory_tags", response_model=ApiResponse)
 async def get_hot_memory_tags_api(
-    limit: int = 10,
-    db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user),
-    ) -> dict:
+        limit: int = 10,
+        db: Session = Depends(get_db),
+        current_user: User = Depends(get_current_user),
+) -> dict:
     """
     获取热门记忆标签（带Redis缓存）
     
@@ -438,18 +465,18 @@ async def get_hot_memory_tags_api(
     - 缓存未命中：~600-800ms（取决于LLM速度）
     """
     workspace_id = current_user.current_workspace_id
-    
+
     # 构建缓存键
     cache_key = f"hot_memory_tags:{workspace_id}:{limit}"
-    
+
     api_logger.info(f"Hot memory tags requested for workspace: {workspace_id}, limit: {limit}")
-    
+
     try:
         # 尝试从Redis缓存获取
         import json
 
         from app.aioRedis import aio_redis_get, aio_redis_set
-        
+
         cached_result = await aio_redis_get(cache_key)
         if cached_result:
             api_logger.info(f"Cache hit for key: {cache_key}")
@@ -458,11 +485,11 @@ async def get_hot_memory_tags_api(
                 return success(data=data, msg="查询成功（缓存）")
             except json.JSONDecodeError:
                 api_logger.warning(f"Failed to parse cached data, will refresh")
-        
+
         # 缓存未命中，执行查询
         api_logger.info(f"Cache miss for key: {cache_key}, executing query")
         result = await analytics_hot_memory_tags(db, current_user, limit)
-        
+
         # 写入缓存（过期时间：5分钟）
         # 注意：result是列表，需要转换为JSON字符串
         try:
@@ -472,9 +499,9 @@ async def get_hot_memory_tags_api(
         except Exception as cache_error:
             # 缓存写入失败不影响主流程
             api_logger.warning(f"Failed to cache result: {str(cache_error)}")
-        
+
         return success(data=result, msg="查询成功")
-        
+
     except Exception as e:
         api_logger.error(f"Hot memory tags failed: {str(e)}")
         return fail(BizCode.INTERNAL_ERROR, "热门标签查询失败", str(e))
@@ -482,8 +509,8 @@ async def get_hot_memory_tags_api(
 
 @router.delete("/analytics/hot_memory_tags/cache", response_model=ApiResponse)
 async def clear_hot_memory_tags_cache(
-    current_user: User = Depends(get_current_user),
-    ) -> dict:
+        current_user: User = Depends(get_current_user),
+) -> dict:
     """
     清除热门标签缓存
     
@@ -493,12 +520,12 @@ async def clear_hot_memory_tags_cache(
     - 数据更新后立即生效
     """
     workspace_id = current_user.current_workspace_id
-    
+
     api_logger.info(f"Clear hot memory tags cache requested for workspace: {workspace_id}")
-    
+
     try:
         from app.aioRedis import aio_redis_delete
-        
+
         # 清除所有limit的缓存（常见的limit值）
         cleared_count = 0
         for limit in [5, 10, 15, 20, 30, 50]:
@@ -507,12 +534,12 @@ async def clear_hot_memory_tags_cache(
             if result:
                 cleared_count += 1
                 api_logger.info(f"Cleared cache for key: {cache_key}")
-        
+
         return success(
-            data={"cleared_count": cleared_count}, 
+            data={"cleared_count": cleared_count},
             msg=f"成功清除 {cleared_count} 个缓存"
         )
-        
+
     except Exception as e:
         api_logger.error(f"Clear cache failed: {str(e)}")
         return fail(BizCode.INTERNAL_ERROR, "清除缓存失败", str(e))
@@ -520,13 +547,13 @@ async def clear_hot_memory_tags_cache(
 
 @router.get("/analytics/recent_activity_stats", response_model=ApiResponse)
 async def get_recent_activity_stats_api(
-    current_user: User = Depends(get_current_user),
-    ) -> dict:
-    api_logger.info("Recent activity stats requested")
+        current_user: User = Depends(get_current_user),
+) -> dict:
+    workspace_id = str(current_user.current_workspace_id) if current_user.current_workspace_id else None
+    api_logger.info(f"Recent activity stats requested: workspace_id={workspace_id}")
     try:
-        result = await analytics_recent_activity_stats()
+        result = await analytics_recent_activity_stats(workspace_id=workspace_id)
         return success(data=result, msg="查询成功")
     except Exception as e:
         api_logger.error(f"Recent activity stats failed: {str(e)}")
         return fail(BizCode.INTERNAL_ERROR, "最近活动统计失败", str(e))
-

api/app/controllers/memory_working_controller.py

@@ -8,6 +8,7 @@ from app.core.response_utils import success
 from app.db import get_db
 from app.dependencies import get_current_user
 from app.models import User
+from app.schemas import conversation_schema
 from app.schemas.response_schema import ApiResponse
 from app.services.conversation_service import ConversationService
 
@@ -32,35 +33,47 @@ def get_memory_count(
 @router.get("/{end_user_id}/conversations", response_model=ApiResponse)
 def get_conversations(
         end_user_id: uuid.UUID,
+        page: int = 1,
+        pagesize: int = 20,
         current_user: User = Depends(get_current_user),
         db: Session = Depends(get_db)
 ):
     """
-    Retrieve all conversations for the current user in a specific group.
+    Retrieve conversations for the current user in a specific group with pagination.
 
     Args:
         end_user_id (UUID): The group identifier.
+        page (int): Page number (1-based). Defaults to 1.
+        pagesize (int): Number of items per page. Defaults to 20.
         current_user (User, optional): The authenticated user.
         db (Session, optional): SQLAlchemy session.
 
     Returns:
-        ApiResponse: Contains a list of conversation IDs.
-
-    Notes:
-        - Initializes the ConversationService with the current DB session.
-        - Returns only conversation IDs for lightweight response.
-        - Logs can be added to trace requests in production.
+        ApiResponse: Contains a paginated list of conversations.
     """
+    page = max(1, page)
+    page_size = max(1, min(pagesize, 100))  # Limit page size between 1 and 100
     conversation_service = ConversationService(db)
-    conversations = conversation_service.get_user_conversations(
-        end_user_id
+    conversations, total = conversation_service.get_user_conversations(
+        end_user_id,
+        page=page,
+        page_size=page_size
     )
-    return success(data=[
-        {
-            "id": conversation.id,
-            "title": conversation.title
-        } for conversation in conversations
-    ], msg="get conversations success")
+    return success(data={
+        "items": [
+            {
+                "id": conversation.id,
+                "title": conversation.title
+            } for conversation in conversations
+        ],
+        "total": total,
+        "page": {
+            "page": page,
+            "pagesize": page_size,
+            "total": total,
+            "hasnext": (page * page_size) < total
+        },
+    }, msg="get conversations success")
 
 
 @router.get("/{end_user_id}/messages", response_model=ApiResponse)
@@ -90,11 +103,7 @@ def get_messages(
         conversation_id,
     )
     messages = [
-        {
-            "role": message.role,
-            "content": message.content,
-            "created_at": int(message.created_at.timestamp() * 1000),
-        }
+        conversation_schema.Message.model_validate(message)
         for message in messages_obj
     ]
     return success(data=messages, msg="get conversation history success")

api/app/controllers/model_controller.py

@@ -15,6 +15,7 @@ from app.core.response_utils import success
 from app.schemas.response_schema import ApiResponse, PageData
 from app.services.model_service import ModelConfigService, ModelApiKeyService, ModelBaseService
 from app.core.logging_config import get_api_logger
+from app.core.quota_stub import check_model_quota, check_model_activation_quota
 
 # 获取API专用日志器
 api_logger = get_api_logger()
@@ -42,6 +43,7 @@ def get_model_strategies():
 @router.get("", response_model=ApiResponse)
 def get_model_list(
         type: Optional[list[str]] = Query(None, description="模型类型筛选（支持多个，如 ?type=LLM 或 ?type=LLM,EMBEDDING）"),
+        capability: Optional[list[str]] = Query(None, description="能力筛选（支持多个，如 ?capability=chat 或 ?capability=chat, embedding）"),
         provider: Optional[model_schema.ModelProvider] = Query(None, description="提供商筛选(基于API Key)"),
         is_active: Optional[bool] = Query(None, description="激活状态筛选"),
         is_public: Optional[bool] = Query(None, description="公开状态筛选"),
@@ -74,10 +76,21 @@ def get_model_list(
             unique_flat_type = list(dict.fromkeys(flat_type))
             type_list = [ModelType(t.lower()) for t in unique_flat_type]
 
+        capability_list = []
+        if capability is not None:
+            flat_capability = []
+            for item in capability:
+                split_items = [c.strip() for c in item.split(', ') if c.strip()]
+                flat_capability.extend(split_items)
+
+            unique_flat_capability = list(dict.fromkeys(flat_capability))
+            capability_list = unique_flat_capability
+
         api_logger.error(f"获取模型type_list: {type_list}")
         query = model_schema.ModelConfigQuery(
             type=type_list,
             provider=provider,
+            capability=capability_list,
             is_active=is_active,
             is_public=is_public,
             search=search,
@@ -291,6 +304,7 @@ async def create_model(
 
 
 @router.post("/composite", response_model=ApiResponse)
+@check_model_quota
 async def create_composite_model(
     model_data: model_schema.CompositeModelCreate,
     db: Session = Depends(get_db),
@@ -317,6 +331,7 @@ async def create_composite_model(
 
 
 @router.put("/composite/{model_id}", response_model=ApiResponse)
+@check_model_activation_quota
 async def update_composite_model(
     model_id: uuid.UUID,
     model_data: model_schema.CompositeModelCreate,
@@ -371,6 +386,11 @@ def update_model(
 
     if model_data.type is not None or model_data.provider is not None:
         raise BusinessException("不允许更改模型类型和供应商", BizCode.INVALID_PARAMETER)
+
+    if model_data.is_active:
+        active_keys = ModelApiKeyService.get_api_keys_by_model(db=db, model_config_id=model_id, is_active=model_data.is_active)
+        if not active_keys:
+            raise BusinessException("请先为该模型配置可用的 API Key", BizCode.INVALID_PARAMETER)
     
     try:
         api_logger.debug(f"开始更新模型配置: model_id={model_id}")
@@ -469,7 +489,9 @@ async def create_model_api_key_by_provider(
             config=api_key_data.config,
             is_active=api_key_data.is_active,
             priority=api_key_data.priority,
-            model_config_ids=model_config_ids
+            model_config_ids=model_config_ids,
+            capability=api_key_data.capability,
+            is_omni=api_key_data.is_omni
         )
         created_keys, failed_models = await ModelApiKeyService.create_api_key_by_provider(db=db, data=create_data)
         

api/app/controllers/ontology_controller.py

@@ -25,13 +25,15 @@ from typing import Dict, Optional, List
 from urllib.parse import quote
 
 from fastapi import APIRouter, Depends, HTTPException, File, UploadFile, Form, Header
-from fastapi.responses import StreamingResponse
+from fastapi.responses import StreamingResponse, JSONResponse
 from sqlalchemy.orm import Session
 
+from app.core.quota_stub import check_ontology_project_quota
+
 from app.core.config import settings
 from app.core.error_codes import BizCode
 from app.core.language_utils import get_language_from_header
-from app.core.logging_config import get_api_logger
+from app.core.logging_config import get_api_logger, get_business_logger
 from app.core.response_utils import fail, success
 from app.db import get_db
 from app.dependencies import get_current_user
@@ -61,6 +63,7 @@ from app.repositories.ontology_scene_repository import OntologySceneRepository
 
 
 api_logger = get_api_logger()
+business_logger = get_business_logger()
 logger = logging.getLogger(__name__)
 
 router = APIRouter(
@@ -123,15 +126,23 @@ def _get_ontology_service(
             )
         
         # 通过 Repository 获取可用的 API Key（负载均衡逻辑由 Repository 处理）
-        from app.repositories.model_repository import ModelApiKeyRepository
-        api_keys = ModelApiKeyRepository.get_by_model_config(db, model_config.id)
-        if not api_keys:
+        # from app.repositories.model_repository import ModelApiKeyRepository
+        from app.services.model_service import ModelApiKeyService
+        api_key_config = ModelApiKeyService.get_available_api_key(db, model_config.id)
+        if not api_key_config:
             logger.error(f"Model {llm_id} has no active API key")
             raise HTTPException(
                 status_code=400,
                 detail="指定的LLM模型没有可用的API密钥"
             )
-        api_key_config = api_keys[0]
+        # api_keys = ModelApiKeyRepository.get_by_model_config(db, model_config.id)
+        # if not api_keys:
+        #     logger.error(f"Model {llm_id} has no active API key")
+        #     raise HTTPException(
+        #         status_code=400,
+        #         detail="指定的LLM模型没有可用的API密钥"
+        #     )
+        # api_key_config = api_keys[0]
         
         is_composite = getattr(model_config, 'is_composite', False)
         logger.info(
@@ -153,6 +164,8 @@ def _get_ontology_service(
             provider=actual_provider,
             api_key=api_key_config.api_key,
             base_url=api_key_config.api_base,
+            is_omni=api_key_config.is_omni,
+            capability=api_key_config.capability,
             max_retries=3,
             timeout=60.0
         )
@@ -276,10 +289,12 @@ async def extract_ontology(
 # ==================== 本体场景管理接口 ====================
 
 @router.post("/scene", response_model=ApiResponse)
+@check_ontology_project_quota
 async def create_scene(
     request: SceneCreateRequest,
     db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
+    current_user: User = Depends(get_current_user),
+    x_language_type: Optional[str] = Header(None, alias="X-Language-Type")
 ):
     """创建本体场景
     
@@ -350,8 +365,18 @@ async def create_scene(
         return fail(BizCode.BAD_REQUEST, "请求参数无效", str(e))
         
     except RuntimeError as e:
-        api_logger.error(f"Runtime error in scene creation: {str(e)}", exc_info=True)
-        return fail(BizCode.INTERNAL_ERROR, "场景创建失败", str(e))
+        err_str = str(e)
+        if "UniqueViolation" in err_str or "uq_workspace_scene_name" in err_str:
+            api_logger.warning(f"Duplicate scene name '{request.scene_name}' in workspace {current_user.current_workspace_id}")
+            from app.core.language_utils import get_language_from_header
+            lang = get_language_from_header(x_language_type)
+            if lang == "en":
+                msg = fail(BizCode.BAD_REQUEST, "Scene name already exists", f"A scene named \"{request.scene_name}\" already exists in the current workspace. Please use a different name.")
+            else:
+                msg = fail(BizCode.BAD_REQUEST, "场景名称已存在", f"当前工作空间下已存在名为「{request.scene_name}」的场景，请使用其他名称")
+            return JSONResponse(status_code=400, content=msg)
+        api_logger.error(f"Runtime error in scene creation: {err_str}", exc_info=True)
+        return fail(BizCode.INTERNAL_ERROR, "场景创建失败", err_str)
         
     except Exception as e:
         api_logger.error(f"Unexpected error in scene creation: {str(e)}", exc_info=True)
@@ -399,6 +424,20 @@ async def update_scene(
             api_logger.warning(f"User {current_user.id} has no current workspace")
             return fail(BizCode.BAD_REQUEST, "请求参数无效", "当前用户没有工作空间")
         
+        # 检查是否为系统默认场景
+        scene_repo = OntologySceneRepository(db)
+        scene = scene_repo.get_by_id(scene_uuid)
+        if scene and scene.is_system_default:
+            business_logger.warning(
+                f"尝试修改系统默认场景: user_id={current_user.id}, "
+                f"scene_id={scene_id}, scene_name={scene.scene_name}"
+            )
+            return fail(
+                BizCode.BAD_REQUEST,
+                "系统默认场景不可修改",
+                "该场景为系统预设场景，不允许修改"
+            )
+        
         # 创建OntologyService实例
         from app.core.memory.llm_tools.openai_client import OpenAIClient
         from app.core.models.base import RedBearModelConfig
@@ -491,6 +530,19 @@ async def delete_scene(
             api_logger.warning(f"User {current_user.id} has no current workspace")
             return fail(BizCode.BAD_REQUEST, "请求参数无效", "当前用户没有工作空间")
         
+        # 检查是否为系统默认场景
+        scene_repo = OntologySceneRepository(db)
+        scene = scene_repo.get_by_id(scene_uuid)
+        if scene and scene.is_system_default:
+            business_logger.warning(
+                f"尝试删除系统默认场景: user_id={current_user.id}, "
+                f"scene_id={scene_id}, scene_name={scene.scene_name}"
+            )
+            raise HTTPException(
+                status_code=400,
+                detail="SYSTEM_DEFAULT_SCENE_CANNOT_DELETE"
+            )
+        
         # 创建OntologyService实例
         from app.core.memory.llm_tools.openai_client import OpenAIClient
         from app.core.models.base import RedBearModelConfig
@@ -514,6 +566,9 @@ async def delete_scene(
         
         return success(data={"deleted": success_flag}, msg="场景删除成功")
         
+    except HTTPException:
+        raise
+
     except ValueError as e:
         api_logger.warning(f"Validation error in scene deletion: {str(e)}")
         return fail(BizCode.BAD_REQUEST, "请求参数无效", str(e))
@@ -621,7 +676,8 @@ async def get_scenes(
 async def create_class(
     request: ClassCreateRequest,
     db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
+    current_user: User = Depends(get_current_user),
+    x_language_type: Optional[str] = Header(None, alias="X-Language-Type")
 ):
     """创建本体类型
     
@@ -636,7 +692,7 @@ async def create_class(
         ApiResponse: 包含创建的类型信息
     """
     from app.controllers.ontology_secondary_routes import create_class_handler
-    return await create_class_handler(request, db, current_user)
+    return await create_class_handler(request, db, current_user, x_language_type)
 
 
 @router.put("/class/{class_id}", response_model=ApiResponse)

api/app/controllers/ontology_secondary_routes.py

@@ -7,11 +7,11 @@
 from uuid import UUID
 from typing import Optional
 
-from fastapi import Depends
+from fastapi import Depends, Header
 from sqlalchemy.orm import Session
 
 from app.core.error_codes import BizCode
-from app.core.logging_config import get_api_logger
+from app.core.logging_config import get_api_logger, get_business_logger
 from app.core.response_utils import fail, success
 from app.db import get_db
 from app.dependencies import get_current_user
@@ -30,9 +30,11 @@ from app.schemas.response_schema import ApiResponse
 from app.services.ontology_service import OntologyService
 from app.core.memory.llm_tools.openai_client import OpenAIClient
 from app.core.models.base import RedBearModelConfig
+from app.repositories.ontology_class_repository import OntologyClassRepository
 
 
 api_logger = get_api_logger()
+business_logger = get_business_logger()
 
 
 def _get_dummy_ontology_service(db: Session) -> OntologyService:
@@ -56,7 +58,7 @@ async def scenes_handler(
     workspace_id: Optional[str] = None,
     scene_name: Optional[str] = None,
     page: Optional[int] = None,
-    page_size: Optional[int] = None,
+    pagesize: Optional[int] = None,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user)
 ):
@@ -69,14 +71,14 @@ async def scenes_handler(
         workspace_id: 工作空间ID（可选，默认当前用户工作空间）
         scene_name: 场景名称关键词（可选，支持模糊匹配）
         page: 页码（可选，从1开始，仅在全量查询时有效）
-        page_size: 每页数量（可选，仅在全量查询时有效）
+        pagesize: 每页数量（可选，仅在全量查询时有效）
         db: 数据库会话
         current_user: 当前用户
     """
     operation = "search" if scene_name else "list"
     api_logger.info(
         f"Scene {operation} requested by user {current_user.id}, "
-        f"workspace_id={workspace_id}, keyword={scene_name}, page={page}, page_size={page_size}"
+        f"workspace_id={workspace_id}, keyword={scene_name}, page={page}, pagesize={pagesize}"
     )
     
     try:
@@ -103,13 +105,13 @@ async def scenes_handler(
                 api_logger.warning(f"Invalid page number: {page}")
                 return fail(BizCode.BAD_REQUEST, "请求参数无效", "页码必须大于0")
             
-            if page_size is not None and page_size < 1:
-                api_logger.warning(f"Invalid page_size: {page_size}")
+            if pagesize is not None and pagesize < 1:
+                api_logger.warning(f"Invalid pagesize: {pagesize}")
                 return fail(BizCode.BAD_REQUEST, "请求参数无效", "每页数量必须大于0")
             
-            # 如果只提供了page或page_size中的一个，返回错误
-            if (page is not None and page_size is None) or (page is None and page_size is not None):
-                api_logger.warning(f"Incomplete pagination params: page={page}, page_size={page_size}")
+            # 如果只提供了page或pagesize中的一个，返回错误
+            if (page is not None and pagesize is None) or (page is None and pagesize is not None):
+                api_logger.warning(f"Incomplete pagination params: page={page}, pagesize={pagesize}")
                 return fail(BizCode.BAD_REQUEST, "请求参数无效", "分页参数page和pagesize必须同时提供")
             
             # 模糊搜索场景（支持分页）
@@ -117,17 +119,15 @@ async def scenes_handler(
             total = len(scenes)
             
             # 如果提供了分页参数，进行分页处理
-            if page is not None and page_size is not None:
-                start_idx = (page - 1) * page_size
-                end_idx = start_idx + page_size
+            if page is not None and pagesize is not None:
+                start_idx = (page - 1) * pagesize
+                end_idx = start_idx + pagesize
                 scenes = scenes[start_idx:end_idx]
             
             # 构建响应
             items = []
             for scene in scenes:
-                # 获取前3个class_name作为entity_type
                 entity_type = [cls.class_name for cls in scene.classes[:3]] if scene.classes else None
-                # 动态计算 type_num
                 type_num = len(scene.classes) if scene.classes else 0
                 
                 items.append(SceneResponse(
@@ -139,17 +139,16 @@ async def scenes_handler(
                     workspace_id=scene.workspace_id,
                     created_at=scene.created_at,
                     updated_at=scene.updated_at,
-                    classes_count=type_num
+                    classes_count=type_num,
+                    is_system_default=scene.is_system_default
                 ))
             
             # 构建响应（包含分页信息）
-            if page is not None and page_size is not None:
-                # 计算是否有下一页
-                hasnext = (page * page_size) < total
-                
+            if page is not None and pagesize is not None:
+                hasnext = (page * pagesize) < total
                 pagination_info = PaginationInfo(
                     page=page,
-                    pagesize=page_size,
+                    pagesize=pagesize,
                     total=total,
                     hasnext=hasnext
                 )
@@ -163,28 +162,25 @@ async def scenes_handler(
             )
         else:
             # 获取所有场景（支持分页）
-            # 验证分页参数
             if page is not None and page < 1:
                 api_logger.warning(f"Invalid page number: {page}")
                 return fail(BizCode.BAD_REQUEST, "请求参数无效", "页码必须大于0")
             
-            if page_size is not None and page_size < 1:
-                api_logger.warning(f"Invalid page_size: {page_size}")
+            if pagesize is not None and pagesize < 1:
+                api_logger.warning(f"Invalid pagesize: {pagesize}")
                 return fail(BizCode.BAD_REQUEST, "请求参数无效", "每页数量必须大于0")
             
-            # 如果只提供了page或page_size中的一个，返回错误
-            if (page is not None and page_size is None) or (page is None and page_size is not None):
-                api_logger.warning(f"Incomplete pagination params: page={page}, page_size={page_size}")
+            # 如果只提供了page或pagesize中的一个，返回错误
+            if (page is not None and pagesize is None) or (page is None and pagesize is not None):
+                api_logger.warning(f"Incomplete pagination params: page={page}, pagesize={pagesize}")
                 return fail(BizCode.BAD_REQUEST, "请求参数无效", "分页参数page和pagesize必须同时提供")
             
-            scenes, total = service.list_scenes(ws_uuid, page, page_size)
+            scenes, total = service.list_scenes(ws_uuid, page, pagesize)
             
             # 构建响应
             items = []
             for scene in scenes:
-                # 获取前3个class_name作为entity_type
                 entity_type = [cls.class_name for cls in scene.classes[:3]] if scene.classes else None
-                # 动态计算 type_num
                 type_num = len(scene.classes) if scene.classes else 0
                 
                 items.append(SceneResponse(
@@ -196,17 +192,16 @@ async def scenes_handler(
                     workspace_id=scene.workspace_id,
                     created_at=scene.created_at,
                     updated_at=scene.updated_at,
-                    classes_count=type_num
+                    classes_count=type_num,
+                    is_system_default=scene.is_system_default
                 ))
             
             # 构建响应（包含分页信息）
-            if page is not None and page_size is not None:
-                # 计算是否有下一页
-                hasnext = (page * page_size) < total
-                
+            if page is not None and pagesize is not None:
+                hasnext = (page * pagesize) < total
                 pagination_info = PaginationInfo(
                     page=page,
-                    pagesize=page_size,
+                    pagesize=pagesize,
                     total=total,
                     hasnext=hasnext
                 )
@@ -236,7 +231,8 @@ async def scenes_handler(
 async def create_class_handler(
     request: ClassCreateRequest,
     db: Session = Depends(get_db),
-    current_user: User = Depends(get_current_user)
+    current_user: User = Depends(get_current_user),
+    x_language_type: Optional[str] = None
 ):
     """创建本体类型（统一使用列表形式，支持单个或批量）"""
     
@@ -269,8 +265,11 @@ async def create_class_handler(
         ]
         
         if count == 1:
-            # 单个创建
+            # 单个创建 - 先检查重名
             class_data = classes_data[0]
+            existing = OntologyClassRepository(db).get_by_name(class_data["class_name"], request.scene_id)
+            if existing:
+                raise ValueError(f"DUPLICATE_CLASS_NAME:{class_data['class_name']}")
             ontology_class = service.create_class(
                 scene_id=request.scene_id,
                 class_name=class_data["class_name"],
@@ -328,12 +327,36 @@ async def create_class_handler(
             return success(data=response.model_dump(mode='json'), msg="批量创建完成")
         
     except ValueError as e:
-        api_logger.warning(f"Validation error in class creation: {str(e)}")
-        return fail(BizCode.BAD_REQUEST, "请求参数无效", str(e))
-        
+        err_str = str(e)
+        if err_str.startswith("DUPLICATE_CLASS_NAME:"):
+            class_name = err_str.split(":", 1)[1]
+            api_logger.warning(f"Duplicate class name '{class_name}' in scene {request.scene_id}")
+            from app.core.language_utils import get_language_from_header
+            from fastapi.responses import JSONResponse
+            lang = get_language_from_header(x_language_type)
+            if lang == "en":
+                msg = fail(BizCode.BAD_REQUEST, "Class name already exists", f"A class named \"{class_name}\" already exists in this scene. Please use a different name.")
+            else:
+                msg = fail(BizCode.BAD_REQUEST, "类型名称已存在", f"当前场景下已存在名为「{class_name}」的类型，请使用其他名称")
+            return JSONResponse(status_code=400, content=msg)
+        api_logger.warning(f"Validation error in class creation: {err_str}")
+        return fail(BizCode.BAD_REQUEST, "请求参数无效", err_str)
+
     except RuntimeError as e:
-        api_logger.error(f"Runtime error in class creation: {str(e)}", exc_info=True)
-        return fail(BizCode.INTERNAL_ERROR, "类型创建失败", str(e))
+        err_str = str(e)
+        if "UniqueViolation" in err_str or "uq_scene_class_name" in err_str:
+            api_logger.warning(f"Duplicate class name in scene {request.scene_id}")
+            from app.core.language_utils import get_language_from_header
+            from fastapi.responses import JSONResponse
+            lang = get_language_from_header(x_language_type)
+            class_name = request.classes[0].class_name if request.classes else ""
+            if lang == "en":
+                msg = fail(BizCode.BAD_REQUEST, "Class name already exists", f"A class named \"{class_name}\" already exists in this scene. Please use a different name.")
+            else:
+                msg = fail(BizCode.BAD_REQUEST, "类型名称已存在", f"当前场景下已存在名为「{class_name}」的类型，请使用其他名称")
+            return JSONResponse(status_code=400, content=msg)
+        api_logger.error(f"Runtime error in class creation: {err_str}", exc_info=True)
+        return fail(BizCode.INTERNAL_ERROR, "类型创建失败", err_str)
         
     except Exception as e:
         api_logger.error(f"Unexpected error in class creation: {str(e)}", exc_info=True)
@@ -366,6 +389,20 @@ async def update_class_handler(
             api_logger.warning(f"User {current_user.id} has no current workspace")
             return fail(BizCode.BAD_REQUEST, "请求参数无效", "当前用户没有工作空间")
         
+        # 检查是否为系统默认类型
+        class_repo = OntologyClassRepository(db)
+        ontology_class = class_repo.get_by_id(class_uuid)
+        if ontology_class and ontology_class.is_system_default:
+            business_logger.warning(
+                f"尝试修改系统默认类型: user_id={current_user.id}, "
+                f"class_id={class_id}, class_name={ontology_class.class_name}"
+            )
+            return fail(
+                BizCode.BAD_REQUEST,
+                "系统默认类型不可修改",
+                "该类型为系统预设类型，不允许修改"
+            )
+        
         # 创建Service
         service = _get_dummy_ontology_service(db)
         
@@ -429,6 +466,20 @@ async def delete_class_handler(
             api_logger.warning(f"User {current_user.id} has no current workspace")
             return fail(BizCode.BAD_REQUEST, "请求参数无效", "当前用户没有工作空间")
         
+        # 检查是否为系统默认类型
+        class_repo = OntologyClassRepository(db)
+        ontology_class = class_repo.get_by_id(class_uuid)
+        if ontology_class and ontology_class.is_system_default:
+            business_logger.warning(
+                f"尝试删除系统默认类型: user_id={current_user.id}, "
+                f"class_id={class_id}, class_name={ontology_class.class_name}"
+            )
+            return fail(
+                BizCode.BAD_REQUEST,
+                "系统默认类型不可删除",
+                "该类型为系统预设类型，不允许删除"
+            )
+        
         # 创建Service
         service = _get_dummy_ontology_service(db)
         
@@ -585,6 +636,7 @@ async def classes_handler(
             scene_id=scene_uuid,
             scene_name=scene.scene_name,
             scene_description=scene.scene_description,
+            is_system_default=scene.is_system_default,
             items=items
         )
         

api/app/controllers/prompt_optimizer_controller.py

@@ -124,10 +124,11 @@ async def get_prompt_opt(
                     skill=data.skill
             ):
                 # chunk 是 prompt 的增量内容
-                yield f"event:message\ndata: {json.dumps(chunk)}\n\n"
+                yield f"event:message\ndata: {json.dumps(chunk, ensure_ascii=False)}\n\n"
         except Exception as e:
             yield f"event:error\ndata: {json.dumps(
-                {"error": str(e)}
+                {"error": str(e)},
+                ensure_ascii=False
             )}\n\n"
         yield "event:end\ndata: {}\n\n"
 

api/app/controllers/public_share_controller.py

@@ -2,25 +2,34 @@ import hashlib
 import json
 import uuid
 from typing import Annotated
+
 from fastapi import APIRouter, Depends, Query, Request
 from fastapi.responses import StreamingResponse
 from sqlalchemy.orm import Session
 
+from app.core.error_codes import BizCode
+from app.core.exceptions import BusinessException
 from app.core.logging_config import get_business_logger
-from app.core.response_utils import success
+from app.core.quota_manager import check_end_user_quota
+from app.core.response_utils import success, fail
 from app.db import get_db, get_db_read
 from app.dependencies import get_share_user_id, ShareTokenData
+from app.models.app_model import AppType
 from app.repositories import knowledge_repository
+from app.repositories.end_user_repository import EndUserRepository
 from app.repositories.workflow_repository import WorkflowConfigRepository
 from app.schemas import release_share_schema, conversation_schema
 from app.schemas.response_schema import PageData, PageMeta
 from app.services import workspace_service
+from app.services.app_chat_service import AppChatService, get_app_chat_service
+from app.services.app_service import AppService
 from app.services.auth_service import create_access_token
 from app.services.conversation_service import ConversationService
 from app.services.release_share_service import ReleaseShareService
 from app.services.shared_chat_service import SharedChatService
-from app.services.app_chat_service import AppChatService, get_app_chat_service
-from app.utils.app_config_utils import dict_to_multi_agent_config, workflow_config_4_app_release, \
+from app.services.workflow_service import WorkflowService
+from app.models.file_metadata_model import FileMetadata
+from app.utils.app_config_utils import workflow_config_4_app_release, \
     agent_config_4_app_release, multi_agent_config_4_app_release
 
 router = APIRouter(prefix="/public/share", tags=["Public Share"])
@@ -206,15 +215,27 @@ def list_conversations(
     logger.debug(f"share_data:{share_data.user_id}")
     other_id = share_data.user_id
     service = SharedChatService(db)
-    share, release = service._get_release_by_share_token(share_data.share_token, password)
-    from app.repositories.end_user_repository import EndUserRepository
+    share, release = service.get_release_by_share_token(share_data.share_token, password)
     end_user_repo = EndUserRepository(db)
+    app_service = AppService(db)
+    app = app_service._get_app_or_404(share.app_id)
+    workspace_id = app.workspace_id
+
+    # 仅在新建终端用户时检查配额
+    existing_end_user = end_user_repo.get_end_user_by_other_id(workspace_id=workspace_id, other_id=other_id)
+    if existing_end_user is None:
+        from app.core.quota_manager import _check_quota
+        from app.models.workspace_model import Workspace
+        ws = db.query(Workspace).filter(Workspace.id == workspace_id).first()
+        if ws:
+            _check_quota(db, ws.tenant_id, "end_user_quota", "end_user", workspace_id=workspace_id)
+
     new_end_user = end_user_repo.get_or_create_end_user(
         app_id=share.app_id,
+        workspace_id=workspace_id,
         other_id=other_id
     )
     logger.debug(new_end_user.id)
-    service = SharedChatService(db)
     conversations, total = service.list_conversations(
         share_token=share_data.share_token,
         user_id=str(new_end_user.id),
@@ -251,8 +272,41 @@ def get_conversation(
     conv_service = ConversationService(db)
     messages = conv_service.get_messages(conversation_id)
 
-    # 构建响应
-    conv_dict = conversation_schema.Conversation.model_validate(conversation).model_dump()
+    file_ids = []
+    message_file_id_map = {}
+
+    # 第一次遍历：解析 audio_url，收集所有有效的 file_id
+    for idx, m in enumerate(messages):
+        if m.role == "assistant" and m.meta_data:
+            audio_url = m.meta_data.get("audio_url")
+            if not audio_url:
+                continue
+            try:
+                file_id = uuid.UUID(audio_url.rstrip("/").split("/")[-1])
+            except (ValueError, IndexError):
+                # audio_url 无法解析为 UUID，标记为 unknown
+                m.meta_data["audio_status"] = "unknown"
+                continue
+
+            file_ids.append(file_id)
+            message_file_id_map[idx] = file_id
+
+    # 批量查询所有相关的 FileMetadata
+    file_status_map = {}
+    if file_ids:
+        file_metas = (
+            db.query(FileMetadata)
+            .filter(FileMetadata.id.in_(set(file_ids)))
+            .all()
+        )
+        file_status_map = {fm.id: fm.status for fm in file_metas}
+
+    # 第二次遍历：将查询结果映射回消息
+    for idx, file_id in message_file_id_map.items():
+        m = messages[idx]
+        m.meta_data["audio_status"] = file_status_map.get(file_id, "unknown")
+
+    conv_dict = conversation_schema.Conversation.model_validate(conversation).model_dump(mode="json")
     conv_dict["messages"] = [
         conversation_schema.Message.model_validate(m) for m in messages
     ]
@@ -293,40 +347,61 @@ async def chat(
 
     # 提前验证和准备（在流式响应开始前完成）
     # 这样可以确保错误能正确返回，而不是在流式响应中间出错
-    from app.models.app_model import AppType
+
     try:
-        from app.core.exceptions import BusinessException
-        from app.core.error_codes import BizCode
-        from app.services.app_service import AppService
         # 验证分享链接和密码
-        share, release = service._get_release_by_share_token(share_token, password)
+        share, release = service.get_release_by_share_token(share_token, password)
 
         # # Create end_user_id by concatenating app_id with user_id
         # end_user_id = f"{share.app_id}_{user_id}"
 
         # Store end_user_id in database with original user_id
-        from app.repositories.end_user_repository import EndUserRepository
         end_user_repo = EndUserRepository(db)
+        app_service = AppService(db)
+        app = app_service._get_app_or_404(share.app_id)
+        workspace_id = app.workspace_id
+
+        # 仅在新建终端用户时检查配额，已有用户复用不受限制
+        existing_end_user = end_user_repo.get_end_user_by_other_id(workspace_id=workspace_id, other_id=other_id)
+        logger.info(f"终端用户配额检查: workspace_id={workspace_id}, other_id={other_id}, existing={existing_end_user is not None}")
+        if existing_end_user is None:
+            from app.core.quota_manager import _check_quota
+            from app.models.workspace_model import Workspace
+            ws = db.query(Workspace).filter(Workspace.id == workspace_id).first()
+            if ws:
+                logger.info(f"新终端用户，执行配额检查: tenant_id={ws.tenant_id}")
+                _check_quota(db, ws.tenant_id, "end_user_quota", "end_user", workspace_id=workspace_id)
+
         new_end_user = end_user_repo.get_or_create_end_user(
             app_id=share.app_id,
+            workspace_id=workspace_id,
             other_id=other_id,
-            original_user_id=user_id  # Save original user_id to other_id
+            original_user_id=user_id
         )
+
+        # Only extract and set memory_config_id when the end user doesn't have one yet
+        if not new_end_user.memory_config_id:
+            from app.services.memory_config_service import MemoryConfigService
+            memory_config_service = MemoryConfigService(db)
+            memory_config_id, _ = memory_config_service.extract_memory_config_id(release.type, release.config or {})
+            if memory_config_id:
+                new_end_user.memory_config_id = memory_config_id
+                db.commit()
+                db.refresh(new_end_user)
         end_user_id = str(new_end_user.id)
 
-        appid = share.app_id
+        # appid = share.app_id
         """获取存储类型和工作空间的ID"""
 
         # 直接通过 SQLAlchemy 查询 app（仅查询未删除的应用）
-        from app.models.app_model import App
-        app = db.query(App).filter(
-            App.id == appid,
-            App.is_active.is_(True)
-        ).first()
-        if not app:
-            raise BusinessException("应用不存在", BizCode.APP_NOT_FOUND)
+        # app = db.query(App).filter(
+        #     App.id == appid,
+        #     App.is_active.is_(True)
+        # ).first()
+        # if not app:
+        #     raise BusinessException("应用不存在", BizCode.APP_NOT_FOUND)
 
-        workspace_id = app.workspace_id
+        # workspace_id = app.workspace_id
 
         # 直接从 workspace 获取 storage_type（公开分享场景无需权限检查）
         storage_type = workspace_service.get_workspace_storage_type_without_auth(
@@ -359,12 +434,12 @@ async def chat(
         app_type = release.app.type if release.app else None
 
         # 根据应用类型验证配置
-        if app_type == "agent":
+        if app_type == AppType.AGENT:
             # Agent 类型：验证模型配置
             model_config_id = release.default_model_config_id
             if not model_config_id:
                 raise BusinessException("Agent 应用未配置模型", BizCode.AGENT_CONFIG_MISSING)
-        elif app_type == "multi_agent":
+        elif app_type == AppType.MULTI_AGENT:
             # Multi-Agent 类型：验证多 Agent 配置
             config = release.config or {}
             if not config.get("sub_agents"):
@@ -402,31 +477,10 @@ async def chat(
         # 流式返回
         agent_config = agent_config_4_app_release(release)
 
-        if payload.stream:
-            # async def event_generator():
-            #     async for event in service.chat_stream(
-            #         share_token=share_token,
-            #         message=payload.message,
-            #         conversation_id=conversation.id,  # 使用已创建的会话 ID
-            #         user_id=str(new_end_user.id),  # 转换为字符串
-            #         variables=payload.variables,
-            #         password=password,
-            #         web_search=payload.web_search,
-            #         memory=payload.memory,
-            #         storage_type=storage_type,
-            #         user_rag_memory_id=user_rag_memory_id
-            #     ):
-            #         yield event
+        if not (agent_config.model_parameters.get("deep_thinking", False) and payload.thinking):
+            agent_config.model_parameters["deep_thinking"] = False
 
-            # return StreamingResponse(
-            #     event_generator(),
-            #     media_type="text/event-stream",
-            #     headers={
-            #         "Cache-Control": "no-cache",
-            #         "Connection": "keep-alive",
-            #         "X-Accel-Buffering": "no"
-            #     }
-            # )
+        if payload.stream:
             async def event_generator():
                 async for event in app_chat_service.agnet_chat_stream(
                         message=payload.message,
@@ -452,20 +506,6 @@ async def chat(
                     "X-Accel-Buffering": "no"
                 }
             )
-        # 非流式返回
-        # result = await service.chat(
-        #     share_token=share_token,
-        #     message=payload.message,
-        #     conversation_id=conversation.id,  # 使用已创建的会话 ID
-        #     user_id=str(new_end_user.id),  # 转换为字符串
-        #     variables=payload.variables,
-        #     password=password,
-        #     web_search=payload.web_search,
-        #     memory=payload.memory,
-        #     storage_type=storage_type,
-        #     user_rag_memory_id=user_rag_memory_id
-        # )
-        # return success(data=conversation_schema.ChatResponse(**result))
         result = await app_chat_service.agnet_chat(
             message=payload.message,
             conversation_id=conversation.id,  # 使用已创建的会话 ID
@@ -524,48 +564,6 @@ async def chat(
         )
 
         return success(data=conversation_schema.ChatResponse(**result).model_dump(mode="json"))
-        # 多 Agent 流式返回
-        # if payload.stream:
-        #     async def event_generator():
-        #         async for event in service.multi_agent_chat_stream(
-        #             share_token=share_token,
-        #             message=payload.message,
-        #             conversation_id=conversation.id,  # 使用已创建的会话 ID
-        #             user_id=str(new_end_user.id),  # 转换为字符串
-        #             variables=payload.variables,
-        #             password=password,
-        #             web_search=payload.web_search,
-        #             memory=payload.memory,
-        #                 storage_type=storage_type,
-        #                 user_rag_memory_id=user_rag_memory_id
-        #         ):
-        #             yield event
-
-        #     return StreamingResponse(
-        #         event_generator(),
-        #         media_type="text/event-stream",
-        #         headers={
-        #             "Cache-Control": "no-cache",
-        #             "Connection": "keep-alive",
-        #             "X-Accel-Buffering": "no"
-        #         }
-        #     )
-
-        # # 多 Agent 非流式返回
-        # result = await service.multi_agent_chat(
-        #     share_token=share_token,
-        #     message=payload.message,
-        #     conversation_id=conversation.id,  # 使用已创建的会话 ID
-        #     user_id=str(new_end_user.id),  # 转换为字符串
-        #     variables=payload.variables,
-        #     password=password,
-        #     web_search=payload.web_search,
-        #     memory=payload.memory,
-        #     storage_type=storage_type,
-        #     user_rag_memory_id=user_rag_memory_id
-        # )
-
-        # return success(data=conversation_schema.ChatResponse(**result))
     elif app_type == AppType.WORKFLOW:
         config = workflow_config_4_app_release(release)
         if not config.id:
@@ -610,11 +608,11 @@ async def chat(
 
         # 多 Agent 非流式返回
         result = await app_chat_service.workflow_chat(
-
             message=payload.message,
             conversation_id=conversation.id,  # 使用已创建的会话 ID
             user_id=end_user_id,  # 转换为字符串
             variables=payload.variables,
+            files=payload.files,
             config=config,
             web_search=payload.web_search,
             memory=payload.memory,
@@ -638,6 +636,40 @@ async def chat(
         # return success(data=conversation_schema.ChatResponse(**result).model_dump(mode="json"))
 
     else:
-        from app.core.exceptions import BusinessException
-        from app.core.error_codes import BizCode
         raise BusinessException(f"不支持的应用类型: {app_type}", BizCode.APP_TYPE_NOT_SUPPORTED)
+
+
+@router.get("/config", summary="获取应用启动配置")
+async def config_query(
+        password: str = Query(None, description="访问密码"),
+        share_data: ShareTokenData = Depends(get_share_user_id),
+        db: Session = Depends(get_db),
+):
+    share_service = SharedChatService(db)
+    share_token = share_data.share_token
+    share, release = share_service.get_release_by_share_token(share_token, password)
+    if release.app.type == AppType.WORKFLOW:
+        workflow_service = WorkflowService(db)
+        content = {
+            "app_type": release.app.type,
+            "variables": workflow_service.get_start_node_variables(release.config),
+            "memory":  workflow_service.is_memory_enable(release.config),
+            "features": release.config.get("features")
+        }
+    elif release.app.type == AppType.AGENT:
+        content = {
+            "app_type": release.app.type,
+            "variables": release.config.get("variables"),
+            "memory": release.config.get("memory", {}).get("enabled"),
+            "features": release.config.get("features"),
+            "model_parameters": release.config.get("model_parameters")
+        }
+    elif release.app.type == AppType.MULTI_AGENT:
+        content = {
+            "app_type": release.app.type,
+            "variables": [],
+            "features": release.config.get("features")
+        }
+    else:
+        return fail(msg="Unsupported app type", code=BizCode.APP_TYPE_NOT_SUPPORTED)
+    return success(data=content)

api/app/controllers/service/__init__.py

@@ -4,7 +4,18 @@
 认证方式: API Key
 """
 from fastapi import APIRouter
-from . import app_api_controller, rag_api_knowledge_controller, rag_api_document_controller, rag_api_file_controller, rag_api_chunk_controller, memory_api_controller
+
+from . import (
+    app_api_controller,
+    end_user_api_controller,
+    memory_api_controller,
+    memory_config_api_controller,
+    rag_api_chunk_controller,
+    rag_api_document_controller,
+    rag_api_file_controller,
+    rag_api_knowledge_controller,
+    user_memory_api_controller,
+)
 
 # 创建 V1 API 路由器
 service_router = APIRouter()
@@ -16,5 +27,8 @@ service_router.include_router(rag_api_document_controller.router)
 service_router.include_router(rag_api_file_controller.router)
 service_router.include_router(rag_api_chunk_controller.router)
 service_router.include_router(memory_api_controller.router)
+service_router.include_router(end_user_api_controller.router)
+service_router.include_router(memory_config_api_controller.router)
+service_router.include_router(user_memory_api_controller.router)
 
 __all__ = ["service_router"]

api/app/controllers/service/app_api_controller.py

@@ -14,6 +14,7 @@ from app.core.response_utils import success
 from app.db import get_db
 from app.models.app_model import App
 from app.models.app_model import AppType
+from app.models.app_release_model import AppRelease
 from app.repositories import knowledge_repository
 from app.repositories.end_user_repository import EndUserRepository
 from app.schemas import AppChatRequest, conversation_schema
@@ -61,18 +62,18 @@ async def list_apps():
 #     return success(data={"received": True}, msg="消息已接收")
 
 
-def _checkAppConfig(app: App):
-    if app.type == AppType.AGENT:
-        if not app.current_release.config:
+def _checkAppConfig(release: AppRelease):
+    if release.type == AppType.AGENT:
+        if not release.config:
             raise BusinessException("Agent 应用未配置模型", BizCode.AGENT_CONFIG_MISSING)
-    elif app.type == AppType.MULTI_AGENT:
-        if not app.current_release.config:
+    elif release.type == AppType.MULTI_AGENT:
+        if not release.config:
             raise BusinessException("Multi-Agent 应用未配置模型", BizCode.AGENT_CONFIG_MISSING)
-    elif app.type == AppType.WORKFLOW:
-        if not app.current_release.config:
+    elif release.type == AppType.WORKFLOW:
+        if not release.config:
             raise BusinessException("工作流应用未配置模型", BizCode.AGENT_CONFIG_MISSING)
     else:
-        raise BusinessException("不支持的应用类型", BizCode.AGENT_CONFIG_MISSING)
+        raise BusinessException("不支持的应用类型", BizCode.APP_TYPE_NOT_SUPPORTED)
 
 
 @router.post("/chat")
@@ -86,18 +87,39 @@ async def chat(
         app_service: Annotated[AppService, Depends(get_app_service)] = None,
         message: str = Body(..., description="聊天消息内容"),
 ):
+    """
+    Agent/Workflow 聊天接口
+
+    - 不传 version：使用当前生效版本（current_release，回滚后为回滚目标版本）
+    - 传 version=release_id：使用指定版本uuid的历史快照，例如 {"version": "{{release_id}}"}
+    """
     body = await request.json()
     payload = AppChatRequest(**body)
 
-    other_id = payload.user_id
     app = app_service.get_app(api_key_auth.resource_id, api_key_auth.workspace_id)
+
+    # 版本切换：指定 release_id 时查找对应历史快照，否则使用当前激活版本
+    if payload.version is not None:
+        active_release = app_service.get_release_by_id(app.id, payload.version)
+    else:
+        active_release = app.current_release
     other_id = payload.user_id
-    workspace_id = app.workspace_id
+    workspace_id = api_key_auth.workspace_id
     end_user_repo = EndUserRepository(db)
+
+    # 仅在新建终端用户时检查配额，已有用户复用不受限制
+    existing_end_user = end_user_repo.get_end_user_by_other_id(workspace_id=workspace_id, other_id=other_id)
+    if existing_end_user is None:
+        from app.core.quota_manager import _check_quota
+        from app.models.workspace_model import Workspace
+        ws = db.query(Workspace).filter(Workspace.id == workspace_id).first()
+        if ws:
+            _check_quota(db, ws.tenant_id, "end_user_quota", "end_user", workspace_id=workspace_id)
+
     new_end_user = end_user_repo.get_or_create_end_user(
         app_id=app.id,
+        workspace_id=workspace_id,
         other_id=other_id,
-        original_user_id=other_id  # Save original user_id to other_id
     )
     end_user_id = str(new_end_user.id)
     web_search = True
@@ -128,22 +150,28 @@ async def chat(
             storage_type = 'neo4j'
     app_type = app.type
     # check app config
-    _checkAppConfig(app)
+    _checkAppConfig(active_release)
 
     # 获取或创建会话（提前验证）
     conversation = conversation_service.create_or_get_conversation(
         app_id=app.id,
         workspace_id=workspace_id,
         user_id=end_user_id,
-        is_draft=False
+        is_draft=False,
+        conversation_id=payload.conversation_id
     )
 
     if app_type == AppType.AGENT:
 
         # print("="*50)
         # print(app.current_release.default_model_config_id)
-        agent_config = agent_config_4_app_release(app.current_release)
+        agent_config = agent_config_4_app_release(active_release)
         # print(agent_config.default_model_config_id)
+
+        # thinking 开关：仅当 agent 配置了 deep_thinking 且请求 thinking=True 时才启用
+        if not (agent_config.model_parameters.get("deep_thinking", False) and payload.thinking):
+            agent_config.model_parameters["deep_thinking"] = False
+
         # 流式返回
         if payload.stream:
             async def event_generator():
@@ -189,7 +217,7 @@ async def chat(
         return success(data=conversation_schema.ChatResponse(**result).model_dump(mode="json"))
     elif app_type == AppType.MULTI_AGENT:
         # 多 Agent 流式返回
-        config = multi_agent_config_4_app_release(app.current_release)
+        config = multi_agent_config_4_app_release(active_release)
         if payload.stream:
             async def event_generator():
                 async for event in app_chat_service.multi_agent_chat_stream(
@@ -232,7 +260,7 @@ async def chat(
         return success(data=conversation_schema.ChatResponse(**result).model_dump(mode="json"))
     elif app_type == AppType.WORKFLOW:
         # 多 Agent 流式返回
-        config = workflow_config_4_app_release(app.current_release)
+        config = workflow_config_4_app_release(active_release)
         if payload.stream:
             async def event_generator():
                 async for event in app_chat_service.workflow_chat_stream(
@@ -248,7 +276,8 @@ async def chat(
                         user_rag_memory_id=user_rag_memory_id,
                         app_id=app.id,
                         workspace_id=workspace_id,
-                        release_id=app.current_release.id,
+                        release_id=active_release.id,
+                        public=True
                 ):
                     event_type = event.get("event", "message")
                     event_data = event.get("data", {})
@@ -267,7 +296,7 @@ async def chat(
                 }
             )
 
-        # 多 Agent 非流式返回
+        # workflow 非流式返回
         result = await app_chat_service.workflow_chat(
 
             message=payload.message,
@@ -279,9 +308,10 @@ async def chat(
             memory=memory,
             storage_type=storage_type,
             user_rag_memory_id=user_rag_memory_id,
+            files=payload.files,
             app_id=app.id,
             workspace_id=workspace_id,
-            release_id=app.current_release.id
+            release_id=active_release.id
         )
         logger.debug(
             "工作流试运行返回结果",
@@ -295,6 +325,4 @@ async def chat(
             msg="工作流任务执行成功"
         )
     else:
-        from app.core.exceptions import BusinessException
-        from app.core.error_codes import BizCode
         raise BusinessException(f"不支持的应用类型: {app_type}", BizCode.APP_TYPE_NOT_SUPPORTED)

api/app/controllers/service/end_user_api_controller.py

@@ -0,0 +1,173 @@
+"""End User 服务接口 - 基于 API Key 认证"""
+
+import uuid
+
+from fastapi import APIRouter, Body, Depends, Request
+from sqlalchemy.orm import Session
+
+from app.controllers import user_memory_controllers
+from app.core.api_key_auth import require_api_key
+from app.core.error_codes import BizCode
+from app.core.exceptions import BusinessException
+from app.core.logging_config import get_business_logger
+from app.core.quota_stub import check_end_user_quota
+from app.core.response_utils import success
+from app.db import get_db
+from app.repositories.end_user_repository import EndUserRepository
+from app.schemas.api_key_schema import ApiKeyAuth
+from app.schemas.end_user_info_schema import EndUserInfoUpdate
+from app.schemas.memory_api_schema import CreateEndUserRequest, CreateEndUserResponse
+from app.services import api_key_service
+from app.services.memory_config_service import MemoryConfigService
+
+router = APIRouter(prefix="/end_user", tags=["V1 - End User API"])
+logger = get_business_logger()
+
+
+def _get_current_user(api_key_auth: ApiKeyAuth, db: Session):
+    """Build a current_user object from API key auth
+
+    Args:
+        api_key_auth: Validated API key auth info
+        db: Database session
+
+    Returns:
+        User object with current_workspace_id set
+    """
+    api_key = api_key_service.ApiKeyService.get_api_key(db, api_key_auth.api_key_id, api_key_auth.workspace_id)
+    current_user = api_key.creator
+    current_user.current_workspace_id = api_key_auth.workspace_id
+    return current_user
+
+
+@router.post("/create")
+@require_api_key(scopes=["memory"])
+@check_end_user_quota
+async def create_end_user(
+    request: Request,
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+    message: str = Body(None, description="Request body"),
+):
+    """
+    Create or retrieve an end user for the workspace.
+
+    Creates a new end user and connects it to a memory configuration.
+    If an end user with the same other_id already exists in the workspace,
+    returns the existing one.
+
+    Optionally accepts a memory_config_id to connect the end user to a specific
+    memory configuration. If not provided, falls back to the workspace default config.
+    Optionally accepts an app_id to bind the end user to a specific app.
+    """
+    body = await request.json()
+    payload = CreateEndUserRequest(**body)
+    workspace_id = api_key_auth.workspace_id
+
+    logger.info("Create end user request - other_id: %s, workspace_id: %s", payload.other_id, workspace_id)
+
+    # Resolve memory_config_id: explicit > workspace default
+    memory_config_id = None
+    config_service = MemoryConfigService(db)
+
+    if payload.memory_config_id:
+        try:
+            memory_config_id = uuid.UUID(payload.memory_config_id)
+        except ValueError:
+            raise BusinessException(
+                f"Invalid memory_config_id format: {payload.memory_config_id}",
+                BizCode.INVALID_PARAMETER
+            )
+        config = config_service.get_config_with_fallback(memory_config_id, workspace_id)
+        if not config:
+            raise BusinessException(
+                f"Memory config not found: {payload.memory_config_id}",
+                BizCode.MEMORY_CONFIG_NOT_FOUND
+            )
+        memory_config_id = config.config_id
+    else:
+        default_config = config_service.get_workspace_default_config(workspace_id)
+        if default_config:
+            memory_config_id = default_config.config_id
+            logger.info(f"Using workspace default memory config: {memory_config_id}")
+        else:
+            logger.warning(f"No default memory config found for workspace: {workspace_id}")
+
+    # Resolve app_id: explicit from payload, otherwise None
+    app_id = None
+    if payload.app_id:
+        try:
+            app_id = uuid.UUID(payload.app_id)
+        except ValueError:
+            raise BusinessException(
+                f"Invalid app_id format: {payload.app_id}",
+                BizCode.INVALID_PARAMETER
+            )
+
+    end_user_repo = EndUserRepository(db)
+    end_user = end_user_repo.get_or_create_end_user_with_config(
+        app_id=app_id,
+        workspace_id=workspace_id,
+        other_id=payload.other_id,
+        memory_config_id=memory_config_id,
+        other_name=payload.other_name,
+    )
+    end_user.other_name = payload.other_name  
+    logger.info(f"End user ready: {end_user.id}")
+
+    result = {
+        "id": str(end_user.id),
+        "other_id": end_user.other_id or "",
+        "other_name": end_user.other_name or "",
+        "workspace_id": str(end_user.workspace_id),
+        "memory_config_id": str(end_user.memory_config_id) if end_user.memory_config_id else None,
+    }
+
+    return success(data=CreateEndUserResponse(**result).model_dump(), msg="End user created successfully")
+
+
+@router.get("/info")
+@require_api_key(scopes=["memory"])
+async def get_end_user_info(
+    request: Request,
+    end_user_id: str,
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+):
+    """
+    Get end user info.
+
+    Retrieves the info record (aliases, meta_data, etc.) for the specified end user.
+    Delegates to the manager-side controller for shared logic.
+    """
+    current_user = _get_current_user(api_key_auth, db)
+    return await user_memory_controllers.get_end_user_info(
+        end_user_id=end_user_id,
+        current_user=current_user,
+        db=db,
+    )
+
+
+@router.post("/info/update")
+@require_api_key(scopes=["memory"])
+async def update_end_user_info(
+    request: Request,
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+    message: str = Body(None, description="Request body"),
+):
+    """
+    Update end user info.
+
+    Updates the info record (other_name, aliases, meta_data) for the specified end user.
+    Delegates to the manager-side controller for shared logic.
+    """
+    body = await request.json()
+    payload = EndUserInfoUpdate(**body)
+
+    current_user = _get_current_user(api_key_auth, db)
+    return await user_memory_controllers.update_end_user_info(
+        info_update=payload,
+        current_user=current_user,
+        db=db,
+    )

api/app/controllers/service/memory_api_controller.py

@@ -1,49 +1,84 @@
 """Memory 服务接口 - 基于 API Key 认证"""
 
+from fastapi import APIRouter, Body, Depends, Query, Request
+from sqlalchemy.orm import Session
+
+from app.celery_task_scheduler import scheduler
 from app.core.api_key_auth import require_api_key
 from app.core.logging_config import get_business_logger
+from app.core.quota_stub import check_end_user_quota
 from app.core.response_utils import success
 from app.db import get_db
 from app.schemas.api_key_schema import ApiKeyAuth
 from app.schemas.memory_api_schema import (
     MemoryReadRequest,
     MemoryReadResponse,
+    MemoryReadSyncResponse,
     MemoryWriteRequest,
     MemoryWriteResponse,
+    MemoryWriteSyncResponse,
 )
 from app.services.memory_api_service import MemoryAPIService
-from fastapi import APIRouter, Body, Depends, Request
-from sqlalchemy.orm import Session
 
 router = APIRouter(prefix="/memory", tags=["V1 - Memory API"])
 logger = get_business_logger()
 
 
+def _sanitize_task_result(result: dict) -> dict:
+    """Make Celery task result JSON-serializable.
+
+    Converts UUID and other non-serializable values to strings.
+
+    Args:
+        result: Raw task result dict from task_service
+
+    Returns:
+        JSON-safe dict
+    """
+    import uuid as _uuid
+    from datetime import datetime
+
+    def _convert(obj):
+        if isinstance(obj, dict):
+            return {k: _convert(v) for k, v in obj.items()}
+        if isinstance(obj, list):
+            return [_convert(i) for i in obj]
+        if isinstance(obj, _uuid.UUID):
+            return str(obj)
+        if isinstance(obj, datetime):
+            return obj.isoformat()
+        return obj
+
+    return _convert(result)
+
+
 @router.get("")
 async def get_memory_info():
     """获取记忆服务信息（占位）"""
     return success(data={}, msg="Memory API - Coming Soon")
 
 
-@router.post("/write_api_service")
+@router.post("/write")
 @require_api_key(scopes=["memory"])
-async def write_memory_api_service(
+async def write_memory(
     request: Request,
     api_key_auth: ApiKeyAuth = None,
     db: Session = Depends(get_db),
-    payload: MemoryWriteRequest = Body(..., embed=False),
-
+    message: str = Body(..., description="Message content"),
 ):
     """
-    Write memory to storage.
-    
-    Stores memory content for the specified end user using the Memory API Service.
+    Submit a memory write task.
+
+    Validates the end user, then dispatches the write to a Celery background task
+    with per-user fair locking. Returns a task_id for status polling.
     """
-    logger.info(f"Memory write request - end_user_id: {payload.end_user_id}, tenant_id: {api_key_auth.tenant_id}")
-    
+    body = await request.json()
+    payload = MemoryWriteRequest(**body)
+    logger.info(f"Memory write request - end_user_id: {payload.end_user_id}, workspace_id: {api_key_auth.workspace_id}")
+
     memory_api_service = MemoryAPIService(db)
-    
-    result = await memory_api_service.write_memory(
+
+    result = memory_api_service.write_memory(
         workspace_id=api_key_auth.workspace_id,
         end_user_id=payload.end_user_id,
         message=payload.message,
@@ -51,29 +86,52 @@ async def write_memory_api_service(
         storage_type=payload.storage_type,
         user_rag_memory_id=payload.user_rag_memory_id,
     )
-    
-    logger.info(f"Memory write successful for end_user: {payload.end_user_id}")
-    return success(data=MemoryWriteResponse(**result).model_dump(), msg="Memory written successfully")
+
+    logger.info(f"Memory write task submitted: task_id: {result['task_id']} end_user_id: {payload.end_user_id}")
+    return success(data=MemoryWriteResponse(**result).model_dump(), msg="Memory write task submitted")
 
 
-@router.post("/read_api_service")
+@router.get("/write/status")
 @require_api_key(scopes=["memory"])
-async def read_memory_api_service(
+async def get_write_task_status(
+    request: Request,
+    task_id: str = Query(..., description="Celery task ID"),
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+):
+    """
+    Check the status of a memory write task.
+
+    Returns the current status and result (if completed) of a previously submitted write task.
+    """
+    logger.info(f"Write task status check - task_id: {task_id}")
+
+    result = scheduler.get_task_status(task_id)
+
+    return success(data=_sanitize_task_result(result), msg="Task status retrieved")
+
+
+@router.post("/read")
+@require_api_key(scopes=["memory"])
+async def read_memory(
     request: Request,
     api_key_auth: ApiKeyAuth = None,
     db: Session = Depends(get_db),
-    payload: MemoryReadRequest = Body(..., embed=False),
+    message: str = Body(..., description="Query message"),
 ):
     """
-    Read memory from storage.
-    
-    Queries and retrieves memories for the specified end user with context-aware responses.
+    Submit a memory read task.
+
+    Validates the end user, then dispatches the read to a Celery background task.
+    Returns a task_id for status polling.
     """
+    body = await request.json()
+    payload = MemoryReadRequest(**body)
     logger.info(f"Memory read request - end_user_id: {payload.end_user_id}")
-    
+
     memory_api_service = MemoryAPIService(db)
-    
-    result = await memory_api_service.read_memory(
+
+    result = memory_api_service.read_memory(
         workspace_id=api_key_auth.workspace_id,
         end_user_id=payload.end_user_id,
         message=payload.message,
@@ -82,6 +140,95 @@ async def read_memory_api_service(
         storage_type=payload.storage_type,
         user_rag_memory_id=payload.user_rag_memory_id,
     )
-    
-    logger.info(f"Memory read successful for end_user: {payload.end_user_id}")
-    return success(data=MemoryReadResponse(**result).model_dump(), msg="Memory read successfully")
+
+    logger.info(f"Memory read task submitted: task_id={result['task_id']}, end_user_id: {payload.end_user_id}")
+    return success(data=MemoryReadResponse(**result).model_dump(), msg="Memory read task submitted")
+
+
+@router.get("/read/status")
+@require_api_key(scopes=["memory"])
+async def get_read_task_status(
+    request: Request,
+    task_id: str = Query(..., description="Celery task ID"),
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+):
+    """
+    Check the status of a memory read task.
+
+    Returns the current status and result (if completed) of a previously submitted read task.
+    """
+    logger.info(f"Read task status check - task_id: {task_id}")
+
+    from app.services.task_service import get_task_memory_read_result
+    result = get_task_memory_read_result(task_id)
+
+    return success(data=_sanitize_task_result(result), msg="Task status retrieved")
+
+
+@router.post("/write/sync")
+@require_api_key(scopes=["memory"])
+@check_end_user_quota
+async def write_memory_sync(
+    request: Request,
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+    message: str = Body(..., description="Message content"),
+):
+    """
+    Write memory synchronously.
+
+    Blocks until the write completes and returns the result directly.
+    For async processing with task polling, use /write instead.
+    """
+    body = await request.json()
+    payload = MemoryWriteRequest(**body)
+    logger.info(f"Memory write (sync) request - end_user_id: {payload.end_user_id}")
+
+    memory_api_service = MemoryAPIService(db)
+
+    result = await memory_api_service.write_memory_sync(
+        workspace_id=api_key_auth.workspace_id,
+        end_user_id=payload.end_user_id,
+        message=payload.message,
+        config_id=payload.config_id,
+        storage_type=payload.storage_type,
+        user_rag_memory_id=payload.user_rag_memory_id,
+    )
+
+    logger.info(f"Memory write (sync) successful for end_user: {payload.end_user_id}")
+    return success(data=MemoryWriteSyncResponse(**result).model_dump(), msg="Memory written successfully")
+
+
+@router.post("/read/sync")
+@require_api_key(scopes=["memory"])
+async def read_memory_sync(
+    request: Request,
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+    message: str = Body(..., description="Query message"),
+):
+    """
+    Read memory synchronously.
+
+    Blocks until the read completes and returns the answer directly.
+    For async processing with task polling, use /read instead.
+    """
+    body = await request.json()
+    payload = MemoryReadRequest(**body)
+    logger.info(f"Memory read (sync) request - end_user_id: {payload.end_user_id}")
+
+    memory_api_service = MemoryAPIService(db)
+
+    result = await memory_api_service.read_memory_sync(
+        workspace_id=api_key_auth.workspace_id,
+        end_user_id=payload.end_user_id,
+        message=payload.message,
+        search_switch=payload.search_switch,
+        config_id=payload.config_id,
+        storage_type=payload.storage_type,
+        user_rag_memory_id=payload.user_rag_memory_id,
+    )
+
+    logger.info(f"Memory read (sync) successful for end_user: {payload.end_user_id}")
+    return success(data=MemoryReadSyncResponse(**result).model_dump(), msg="Memory read successfully")

api/app/controllers/service/memory_config_api_controller.py

@@ -0,0 +1,491 @@
+"""Memory Config 服务接口 - 基于 API Key 认证"""
+
+from typing import Optional
+import uuid
+
+from fastapi import APIRouter, Body, Depends, Header, Query, Request
+from fastapi.encoders import jsonable_encoder
+from sqlalchemy.orm import Session
+
+from app.controllers import memory_storage_controller
+from app.controllers import memory_forget_controller
+from app.controllers import ontology_controller
+from app.controllers import emotion_config_controller
+from app.controllers import memory_reflection_controller
+from app.schemas.memory_storage_schema import ForgettingConfigUpdateRequest
+from app.controllers.emotion_config_controller import EmotionConfigUpdate
+from app.schemas.memory_reflection_schemas import Memory_Reflection
+from app.core.api_key_auth import require_api_key
+from app.core.error_codes import BizCode
+from app.core.exceptions import BusinessException
+from app.core.logging_config import get_business_logger
+from app.core.response_utils import success
+from app.db import get_db
+from app.repositories.memory_config_repository import MemoryConfigRepository
+from app.schemas.api_key_schema import ApiKeyAuth
+from app.schemas.memory_api_schema import (
+    ConfigUpdateExtractedRequest,
+    ConfigUpdateRequest,
+    ListConfigsResponse,
+    ConfigCreateRequest,
+    ConfigUpdateForgettingRequest,
+    EmotionConfigUpdateRequest,
+    ReflectionConfigUpdateRequest,
+)
+from app.schemas.memory_storage_schema import (
+    ConfigUpdate, 
+    ConfigUpdateExtracted,
+    ConfigParamsCreate,
+)
+from app.services import api_key_service
+from app.services.memory_api_service import MemoryAPIService
+from app.utils.config_utils import resolve_config_id
+
+router = APIRouter(prefix="/memory_config", tags=["V1 - Memory Config API"])
+logger = get_business_logger()
+
+
+def _get_current_user(api_key_auth: ApiKeyAuth, db: Session):
+    """Build a current_user object from API key auth
+
+    Args:
+        api_key_auth: Validated API key auth info
+        db: Database session
+
+    Returns:
+        User object with current_workspace_id set
+    """
+    api_key = api_key_service.ApiKeyService.get_api_key(db, api_key_auth.api_key_id, api_key_auth.workspace_id)
+    current_user = api_key.creator
+    current_user.current_workspace_id = api_key_auth.workspace_id
+    return current_user
+
+
+def _verify_config_ownership(config_id:str, workspace_id:uuid.UUID, db:Session):
+    """Verify that the config belongs to the workspace.
+    
+      Args: 
+          config_id: The ID of the config to verify
+          workspace_id: The workspace ID tocheck against
+          db: Database session for querying
+        Raises:
+            BusinessException: If the config does not exist or does not belong to the workspace
+    """
+    try:
+        resolved_id = resolve_config_id(config_id, db)
+    except ValueError as e:
+        raise BusinessException(
+            message=f"Invalid config_id: {e}",
+            code=BizCode.INVALID_PARAMETER,
+        )
+    config = MemoryConfigRepository.get_by_id(db, resolved_id)
+    if not config or config.workspace_id != workspace_id:
+        raise BusinessException(
+            message="Config not found or access denied",
+            code=BizCode.MEMORY_CONFIG_NOT_FOUND,
+        )
+
+# @router.get("/configs")
+# @require_api_key(scopes=["memory"])
+# async def list_memory_configs(
+#     request: Request,
+#     api_key_auth: ApiKeyAuth = None,
+#     db: Session = Depends(get_db),
+# ):
+#     """
+#     List all memory configs for the workspace.
+
+#     Returns all available memory configurations associated with the authorized workspace.
+#     """
+#     logger.info(f"List configs request - workspace_id: {api_key_auth.workspace_id}")
+
+#     memory_api_service = MemoryAPIService(db)
+
+#     result = memory_api_service.list_memory_configs(
+#         workspace_id=api_key_auth.workspace_id,
+#     )
+
+#     logger.info(f"Listed {result['total']} configs for workspace: {api_key_auth.workspace_id}")
+#     return success(data=ListConfigsResponse(**result).model_dump(), msg="Configs listed successfully")
+
+@router.get("/read_all_config")
+@require_api_key(scopes=["memory"])
+async def read_all_config(
+    request:Request,
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+):
+    """
+    List all memory configs with full details (enhanced version).
+
+    Returns complete config fields for the authorized workspace.
+    No config_id ownership check needed — results are filtered by workspace.
+    """
+    logger.info(f"V1 get all configs (full) - workspace: {api_key_auth.workspace_id}")
+
+    current_user = _get_current_user(api_key_auth, db)
+
+    return memory_storage_controller.read_all_config(
+        current_user=current_user,
+        db=db,
+    )
+
+@router.get("/scenes/simple")
+@require_api_key(scopes=["memory"])
+async def get_ontology_scenes(
+    request: Request,
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+):
+    """
+    Get available ontology scenes for the workspace.
+
+    Returns a simple list of scene_id and scene_name for dropdown selection.
+    Used before creating a memory config to choose which ontology scene to associate.
+    """
+    logger.info(f"V1 get scenes - workspace: {api_key_auth.workspace_id}")
+
+    current_user = _get_current_user(api_key_auth, db)
+
+    return await ontology_controller.get_scenes_simple(
+        db=db,
+        current_user=current_user,
+    )
+
+@router.get("/read_config_extracted")
+@require_api_key(scopes=["memory"])
+async def read_config_extracted(
+    request: Request,
+    config_id: str = Query(..., description="config_id"),
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+):
+    """
+    Get extraction engine config details for a specific config.
+
+    Only configs belonging to the authorized workspace can be queried.
+    """
+    logger.info(f"V1 read extracted config - config_id: {config_id}, workspace: {api_key_auth.workspace_id}")
+
+    _verify_config_ownership(config_id, api_key_auth.workspace_id, db)
+
+    current_user = _get_current_user(api_key_auth, db)
+
+    return memory_storage_controller.read_config_extracted(
+        config_id = config_id,
+        current_user = current_user,
+        db = db,
+    )
+
+@router.get("/read_config_forgetting")
+@require_api_key(scopes=["memory"])
+async def read_config_forgetting(
+    request: Request,
+    config_id: str = Query(..., description="config_id"),
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+):
+    """
+    Get forgetting settings for a specific memory config.
+
+    Only configs belonging to the authorized workspace can be queried.
+    """
+    logger.info(f"V1 read forgetting config - config_id: {config_id}, workspace: {api_key_auth.workspace_id}")
+
+    _verify_config_ownership(config_id, api_key_auth.workspace_id, db)
+
+    current_user = _get_current_user(api_key_auth, db)
+
+    result = await memory_forget_controller.read_forgetting_config(
+        config_id = config_id,
+        current_user = current_user,
+        db = db,
+    )
+    return jsonable_encoder(result)
+
+
+
+@router.get("/read_config_emotion")
+@require_api_key(scopes=["memory"])
+async def read_config_emotion(
+    request: Request,
+    config_id: str = Query(..., description="config_id"),
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+):
+    """
+    Get emotion engine config details for a specific config.
+
+    Only configs belonging to the authorized workspace can be queried.
+    """
+    logger.info(f"V1 read emotion config - config_id: {config_id}, workspace: {api_key_auth.workspace_id}")
+
+    _verify_config_ownership(config_id, api_key_auth.workspace_id, db)
+
+    current_user = _get_current_user(api_key_auth, db)
+
+    return jsonable_encoder(emotion_config_controller.get_emotion_config(
+        config_id=config_id,
+        db=db,
+        current_user=current_user,
+    ))
+
+@router.get("/read_config_reflection")
+@require_api_key(scopes=["memory"])
+async def read_config_reflection(
+    request: Request,
+    config_id: str = Query(..., description="config_id"),
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+):
+    """
+    Get reflection engine config details for a specific config.
+
+    Only configs belonging to the authorized workspace can be queried.
+    """
+    logger.info(f"V1 read reflection config - config_id: {config_id}, workspace: {api_key_auth.workspace_id}")
+
+    _verify_config_ownership(config_id, api_key_auth.workspace_id, db)
+
+    current_user = _get_current_user(api_key_auth, db)
+
+    return jsonable_encoder(await memory_reflection_controller.start_reflection_configs(
+        config_id=config_id,
+        current_user=current_user,
+        db=db,
+    ))
+
+
+@router.post("/create_config")
+@require_api_key(scopes=["memory"])
+async def create_memory_config(
+    request: Request,
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+    message: str = Body(None, description="Request body"),
+    x_language_type: Optional[str] = Header(None, alias="X-Language-Type"),
+):
+    """
+    Create a new memory config for the workspace.
+
+    The config will be associated with the workspace of the API Key.
+    config_name is required, other fields are optional.
+    """
+    body = await request.json()
+    payload = ConfigCreateRequest(**body)
+
+    logger.info(f"V1 create config - workspace: {api_key_auth.workspace_id}, config_name: {payload.config_name}")
+    
+    # 构造管理端 Schema，workspace_id 从 API Key 注入
+    current_user = _get_current_user(api_key_auth, db)
+    mgmt_payload = ConfigParamsCreate(
+        config_name=payload.config_name,
+        config_desc=payload.config_desc or "",
+        scene_id=payload.scene_id,
+        llm_id=payload.llm_id,
+        embedding_id=payload.embedding_id,
+        rerank_id=payload.rerank_id,
+        reflection_model_id=payload.reflection_model_id,
+        emotion_model_id=payload.emotion_model_id,
+    )
+    #将返回数据中UUID序列化处理
+    result =memory_storage_controller.create_config(
+        payload=mgmt_payload,
+        current_user=current_user,
+        db=db,
+        x_language_type=x_language_type,
+    )
+    return jsonable_encoder(result)
+
+@router.put("/update_config")
+@require_api_key(scopes=["memory"])
+async def update_memory_config(
+    request: Request,
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+    message: str = Body(None, description="Request body"),
+):
+    """
+    Update memory config basic info (name, description, scene).
+
+    Requires API Key with 'memory' scope
+    Only configs belonging to the authorized workspace can be updated.
+    """
+    body = await request.json()
+    payload = ConfigUpdateRequest(**body)
+    
+    logger.info(f"V1 update config - config_id: {payload.config_id}, workspace: {api_key_auth.workspace_id}")
+
+    _verify_config_ownership(payload.config_id, api_key_auth.workspace_id, db)
+
+    current_user = _get_current_user(api_key_auth, db)
+    mgmt_payload = ConfigUpdate(
+        config_id = payload.config_id,
+        config_name = payload.config_name,
+        config_desc = payload.config_desc,
+        scene_id = payload.scene_id,
+    )
+
+    return memory_storage_controller.update_config(
+        payload = mgmt_payload,
+        current_user = current_user,
+        db = db,
+    )
+
+@router.put("/update_config_extracted")
+@require_api_key(scopes=["memory"])
+async def update_memory_config_extracted(
+    request: Request,
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+    message: str = Body(None, description="Request body"),
+):
+   """
+    update memory config extraction engine config (models, thresholds, chunking, pruning, etc.).
+
+    Requires API Key with 'memory' scope.
+    Only configs belonging to the authorized workspace can be updated.
+   """
+   body = await request.json()
+   payload = ConfigUpdateExtractedRequest(**body)
+
+   logger.info(f"V1 update extracted config - config_id: {payload.config_id}, workspace: {api_key_auth.workspace_id}")
+
+   #校验权限
+   _verify_config_ownership(payload.config_id, api_key_auth.workspace_id, db)
+
+   current_user = _get_current_user(api_key_auth, db)
+   update_fields = payload.model_dump(exclude_unset=True)
+   mgmt_payload = ConfigUpdateExtracted(**update_fields)
+
+   return memory_storage_controller.update_config_extracted(
+        payload = mgmt_payload,
+        current_user = current_user,
+        db = db,
+   )
+
+@router.put("/update_config_forgetting")
+@require_api_key(scopes=["memory"])
+async def update_memory_config_forgetting(
+    request: Request,
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+    message: str = Body(None, description="Request body"),
+):
+   """
+    update memory config forgetting settings (forgetting strategy, parameters, etc.).
+
+    Requires API Key with 'memory' scope.
+    Only configs belonging to the authorized workspace can be updated.
+   """
+   body = await request.json()
+   payload = ConfigUpdateForgettingRequest(**body)
+
+   logger.info(f"V1 update forgetting config - config_id: {payload.config_id}, workspace: {api_key_auth.workspace_id}")
+
+   #校验权限
+   _verify_config_ownership(payload.config_id, api_key_auth.workspace_id, db)
+
+   current_user = _get_current_user(api_key_auth, db)
+   update_fields = payload.model_dump(exclude_unset=True)
+   mgmt_payload = ForgettingConfigUpdateRequest(**update_fields)
+
+   #将返回数据中UUID序列化处理
+   result = await memory_forget_controller.update_forgetting_config(
+        payload = mgmt_payload,
+        current_user = current_user,
+        db = db,
+   )
+   return jsonable_encoder(result)
+
+@router.put("/update_config_emotion")
+@require_api_key(scopes=["memory"])
+async def update_config_emotion(
+    request: Request,
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+    message: str = Body(None, description="Request body"),
+):
+    """
+    Update emotion engine config (full update).
+
+    All fields except emotion_model_id are required.
+    Only configs belonging to the authorized workspace can be updated.
+    """
+    body = await request.json()
+    payload = EmotionConfigUpdateRequest(**body)
+
+    logger.info(f"V1 update emotion config - config_id: {payload.config_id}, workspace: {api_key_auth.workspace_id}")
+
+    _verify_config_ownership(payload.config_id, api_key_auth.workspace_id, db)
+
+    current_user = _get_current_user(api_key_auth, db)
+    update_fields = payload.model_dump(exclude_unset=True)
+    mgmt_payload = EmotionConfigUpdate(**update_fields)
+    return jsonable_encoder(emotion_config_controller.update_emotion_config(
+        config=mgmt_payload,
+        db=db,
+        current_user=current_user,
+    ))
+
+@router.put("/update_config_reflection")
+@require_api_key(scopes=["memory"])
+async def update_config_reflection(
+    request: Request,
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+    message: str = Body(None, description="Request body"),
+):
+    """
+    Update reflection engine config (full update).
+
+    All fields are required.
+    Only configs belonging to the authorized workspace can be updated.
+    """
+    body = await request.json()
+    payload = ReflectionConfigUpdateRequest(**body)
+
+    logger.info(f"V1 update reflection config - config_id: {payload.config_id}, workspace: {api_key_auth.workspace_id}")
+
+    _verify_config_ownership(payload.config_id, api_key_auth.workspace_id, db)
+
+    current_user = _get_current_user(api_key_auth, db)
+    update_fields = payload.model_dump(exclude_unset=True)
+    mgmt_payload = Memory_Reflection(**update_fields)
+
+    return jsonable_encoder(await memory_reflection_controller.save_reflection_config(
+        request=mgmt_payload,
+        current_user=current_user,
+        db=db,
+    ))
+
+@router.delete("/delete_config")
+@require_api_key(scopes=["memory"])
+async def delete_memory_config(
+    config_id: str,
+    request: Request,
+    force: bool = Query(False, description="是否强制删除（即使有终端用户正在使用）"),
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+):
+    """
+    Delete a memory config.
+
+    - Default configs cannot be deleted.
+    - If end users are connected and force=False, returns a warning.
+    - If force=True, clears end user references and deletes the config.
+
+    Only configs belonging to the authorized workspace can be deleted.
+    """
+    logger.info(f"V1 delete config - config_id: {config_id}, force: {force}, workspace: {api_key_auth.workspace_id}")
+
+    _verify_config_ownership(config_id, api_key_auth.workspace_id, db)
+
+    current_user = _get_current_user(api_key_auth, db)
+
+    return memory_storage_controller.delete_config(
+        config_id=config_id,
+        force=force,
+        current_user=current_user,
+        db=db,
+    )

api/app/controllers/service/rag_api_chunk_controller.py

@@ -113,6 +113,33 @@ async def create_chunk(
                                                current_user=current_user)
 
 
+@router.post("/{kb_id}/{document_id}/chunk/batch", response_model=ApiResponse)
+@require_api_key(scopes=["rag"])
+async def create_chunks_batch(
+    kb_id: uuid.UUID,
+    document_id: uuid.UUID,
+    request: Request,
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+    items: list = Body(..., description="chunk items list"),
+):
+    """
+    Batch create chunks (max 8)
+    """
+    body = await request.json()
+    batch_data = chunk_schema.ChunkBatchCreate(**body)
+    # 0. Obtain the creator of the api key
+    api_key = api_key_service.ApiKeyService.get_api_key(db, api_key_auth.api_key_id, api_key_auth.workspace_id)
+    current_user = api_key.creator
+    current_user.current_workspace_id = api_key_auth.workspace_id
+
+    return await chunk_controller.create_chunks_batch(kb_id=kb_id,
+                                                      document_id=document_id,
+                                                      batch_data=batch_data,
+                                                      db=db,
+                                                      current_user=current_user)
+
+
 @router.get("/{kb_id}/{document_id}/{doc_id}", response_model=ApiResponse)
 @require_api_key(scopes=["rag"])
 async def get_chunk(
@@ -176,6 +203,7 @@ async def delete_chunk(
     request: Request,
     api_key_auth: ApiKeyAuth = None,
     db: Session = Depends(get_db),
+    force_refresh: bool = Query(False, description="Force Elasticsearch refresh after deletion"),
 ):
     """
     delete document chunk
@@ -188,6 +216,7 @@ async def delete_chunk(
     return await chunk_controller.delete_chunk(kb_id=kb_id,
                                                document_id=document_id,
                                                doc_id=doc_id,
+                                               force_refresh=force_refresh,
                                                db=db,
                                                current_user=current_user)
 

api/app/controllers/service/user_memory_api_controller.py

@@ -0,0 +1,230 @@
+"""User Memory 服务接口 — 基于 API Key 认证
+
+包装 user_memory_controllers.py 和 memory_agent_controller.py 中的内部接口，
+提供基于 API Key 认证的对外服务:
+1./analytics/graph_data - 知识图谱数据接口
+2./analytics/community_graph - 社区图谱接口
+3./analytics/node_statistics - 记忆节点统计接口
+4./analytics/user_summary - 用户摘要接口
+5./analytics/memory_insight - 记忆洞察接口
+6./analytics/interest_distribution - 兴趣分布接口
+7./analytics/end_user_info - 终端用户信息接口
+8./analytics/generate_cache - 缓存生成接口
+
+
+路由前缀: /memory
+子路径: /analytics/...
+最终路径: /v1/memory/analytics/...
+认证方式: API Key (@require_api_key)
+"""
+
+from typing import Optional
+
+from fastapi import APIRouter, Depends, Header, Query, Request, Body
+from sqlalchemy.orm import Session
+
+from app.core.api_key_auth import require_api_key
+from app.core.api_key_utils import get_current_user_from_api_key, validate_end_user_in_workspace
+from app.core.logging_config import get_business_logger
+from app.db import get_db
+from app.schemas.api_key_schema import ApiKeyAuth
+from app.schemas.memory_storage_schema import GenerateCacheRequest
+
+# 包装内部服务 controller
+from app.controllers import user_memory_controllers, memory_agent_controller
+
+router = APIRouter(prefix="/memory", tags=["V1 - User Memory API"])
+logger = get_business_logger()
+
+
+# ==================== 知识图谱 ====================
+
+
+@router.get("/analytics/graph_data")
+@require_api_key(scopes=["memory"])
+async def get_graph_data(
+    request: Request,
+    end_user_id: str = Query(..., description="End user ID"),
+    node_types: Optional[str] = Query(None, description="Comma-separated node types filter"),
+    limit: int = Query(100, description="Max nodes to return (auto-capped at 1000 in service layer)"),
+    depth: int = Query(1, description="Graph traversal depth (auto-capped at 3 in service layer)"),
+    center_node_id: Optional[str] = Query(None, description="Center node for subgraph"),
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+):
+    """Get knowledge graph data (nodes + edges) for an end user."""
+    current_user = get_current_user_from_api_key(db, api_key_auth)
+    validate_end_user_in_workspace(db, end_user_id, api_key_auth.workspace_id)
+
+    return await user_memory_controllers.get_graph_data_api(
+        end_user_id=end_user_id,
+        node_types=node_types,
+        limit=limit,
+        depth=depth,
+        center_node_id=center_node_id,
+        current_user=current_user,
+        db=db,
+    )
+
+
+@router.get("/analytics/community_graph")
+@require_api_key(scopes=["memory"])
+async def get_community_graph(
+    request: Request,
+    end_user_id: str = Query(..., description="End user ID"),
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+):
+    """Get community clustering graph for an end user."""
+    current_user = get_current_user_from_api_key(db, api_key_auth)
+    validate_end_user_in_workspace(db, end_user_id, api_key_auth.workspace_id)
+
+    return await user_memory_controllers.get_community_graph_data_api(
+        end_user_id=end_user_id,
+        current_user=current_user,
+        db=db,
+    )
+
+
+# ==================== 节点统计 ====================
+
+
+@router.get("/analytics/node_statistics")
+@require_api_key(scopes=["memory"])
+async def get_node_statistics(
+    request: Request,
+    end_user_id: str = Query(..., description="End user ID"),
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+):
+    """Get memory node type statistics for an end user."""
+    current_user = get_current_user_from_api_key(db, api_key_auth)
+    validate_end_user_in_workspace(db, end_user_id, api_key_auth.workspace_id)
+
+    return await user_memory_controllers.get_node_statistics_api(
+        end_user_id=end_user_id,
+        current_user=current_user,
+        db=db,
+    )
+
+
+# ==================== 用户摘要 & 洞察 ====================
+
+
+@router.get("/analytics/user_summary")
+@require_api_key(scopes=["memory"])
+async def get_user_summary(
+    request: Request,
+    end_user_id: str = Query(..., description="End user ID"),
+    language_type: str = Header(default=None, alias="X-Language-Type"),
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+):
+    """Get cached user summary for an end user."""
+    current_user = get_current_user_from_api_key(db, api_key_auth)
+    validate_end_user_in_workspace(db, end_user_id, api_key_auth.workspace_id)
+
+    return await user_memory_controllers.get_user_summary_api(
+        end_user_id=end_user_id,
+        language_type=language_type,
+        current_user=current_user,
+        db=db,
+    )
+
+
+@router.get("/analytics/memory_insight")
+@require_api_key(scopes=["memory"])
+async def get_memory_insight(
+    request: Request,
+    end_user_id: str = Query(..., description="End user ID"),
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+):
+    """Get cached memory insight report for an end user."""
+    current_user = get_current_user_from_api_key(db, api_key_auth)
+    validate_end_user_in_workspace(db, end_user_id, api_key_auth.workspace_id)
+
+    return await user_memory_controllers.get_memory_insight_report_api(
+        end_user_id=end_user_id,
+        current_user=current_user,
+        db=db,
+    )
+
+
+# ==================== 兴趣分布 ====================
+
+
+@router.get("/analytics/interest_distribution")
+@require_api_key(scopes=["memory"])
+async def get_interest_distribution(
+    request: Request,
+    end_user_id: str = Query(..., description="End user ID"),
+    limit: int = Query(5, le=5, description="Max interest tags to return"),
+    language_type: str = Header(default=None, alias="X-Language-Type"),
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+):
+    """Get interest distribution tags for an end user."""
+    current_user = get_current_user_from_api_key(db, api_key_auth)
+    validate_end_user_in_workspace(db, end_user_id, api_key_auth.workspace_id)
+
+    return await memory_agent_controller.get_interest_distribution_by_user_api(
+        end_user_id=end_user_id,
+        limit=limit,
+        language_type=language_type,
+        current_user=current_user,
+        db=db,
+    )
+
+
+# ==================== 终端用户信息 ====================
+
+
+@router.get("/analytics/end_user_info")
+@require_api_key(scopes=["memory"])
+async def get_end_user_info(
+    request: Request,
+    end_user_id: str = Query(..., description="End user ID"),
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+):
+    """Get end user basic information (name, aliases, metadata)."""
+    current_user = get_current_user_from_api_key(db, api_key_auth)
+    validate_end_user_in_workspace(db, end_user_id, api_key_auth.workspace_id)
+
+    return await user_memory_controllers.get_end_user_info(
+        end_user_id=end_user_id,
+        current_user=current_user,
+        db=db,
+    )
+
+
+# ==================== 缓存生成 ====================
+
+
+@router.post("/analytics/generate_cache")
+@require_api_key(scopes=["memory"])
+async def generate_cache(
+    request: Request,
+    api_key_auth: ApiKeyAuth = None,
+    db: Session = Depends(get_db),
+    message: str = Body(None, description="Request body"),
+    language_type: str = Header(default=None, alias="X-Language-Type"),
+):
+    """Trigger cache generation (user summary + memory insight) for an end user or all workspace users."""
+    body = await request.json()
+    cache_request = GenerateCacheRequest(**body)
+
+    current_user = get_current_user_from_api_key(db, api_key_auth)
+
+    if cache_request.end_user_id:
+        validate_end_user_in_workspace(db, cache_request.end_user_id, api_key_auth.workspace_id)
+
+    return await user_memory_controllers.generate_cache_api(
+        request=cache_request,
+        language_type=language_type,
+        current_user=current_user,
+        db=db,
+    )
+
+

api/app/controllers/skill_controller.py

@@ -11,11 +11,13 @@ from app.schemas import skill_schema
 from app.schemas.response_schema import PageData, PageMeta
 from app.services.skill_service import SkillService
 from app.core.response_utils import success
+from app.core.quota_stub import check_skill_quota
 
 router = APIRouter(prefix="/skills", tags=["Skills"])
 
 
 @router.post("", summary="创建技能")
+@check_skill_quota
 def create_skill(
     data: skill_schema.SkillCreate,
     db: Session = Depends(get_db),

api/app/controllers/tenant_subscription_controller.py

@@ -0,0 +1,173 @@
+"""
+租户套餐查询接口（普通用户可访问）
+"""
+import datetime
+from typing import Callable, Optional
+
+from fastapi import APIRouter, Depends
+from fastapi.responses import JSONResponse
+from sqlalchemy.orm import Session
+
+from app.core.logging_config import get_api_logger
+from app.core.response_utils import success, fail
+from app.db import get_db
+from app.dependencies import get_current_user
+from app.i18n.dependencies import get_translator
+from app.models.user_model import User
+from app.schemas.response_schema import ApiResponse
+
+logger = get_api_logger()
+
+router = APIRouter(prefix="/tenant", tags=["Tenant"])
+public_router = APIRouter(tags=["Tenant"])
+
+
+@router.get("/subscription", response_model=ApiResponse, summary="获取当前用户所属租户的套餐信息")
+async def get_my_tenant_subscription(
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+    t: Callable = Depends(get_translator),
+):
+    """
+    获取当前登录用户所属租户的有效套餐订阅信息。
+    包含套餐名称、版本、配额、到期时间等。
+    """
+    try:
+        from premium.platform_admin.package_plan_service import TenantSubscriptionService
+
+        if not current_user.tenant:
+            return JSONResponse(status_code=404, content=fail(code=404, msg="用户未关联租户"))
+
+        tenant_id = current_user.tenant.id
+        svc = TenantSubscriptionService(db)
+        sub = svc.get_subscription(tenant_id)
+
+        if not sub:
+            # 无订阅记录时，兜底返回免费套餐信息
+            free_plan = svc.plan_repo.get_free_plan()
+            if not free_plan:
+                return success(data=None, msg="暂无有效套餐")
+            return success(data={
+                "subscription_id": None,
+                "tenant_id": str(tenant_id),
+                "package_plan_id": str(free_plan.id),
+                "package_version": free_plan.version,
+                "package_plan": {
+                    "id": str(free_plan.id),
+                    "name": free_plan.name,
+                    "name_en": free_plan.name_en,
+                    "version": free_plan.version,
+                    "category": free_plan.category,
+                    "tier_level": free_plan.tier_level,
+                    "price": float(free_plan.price) if free_plan.price is not None else 0.0,
+                    "billing_cycle": free_plan.billing_cycle,
+                    "core_value": free_plan.core_value,
+                    "core_value_en": free_plan.core_value_en,
+                    "tech_support": free_plan.tech_support,
+                    "tech_support_en": free_plan.tech_support_en,
+                    "sla_compliance": free_plan.sla_compliance,
+                    "sla_compliance_en": free_plan.sla_compliance_en,
+                    "page_customization": free_plan.page_customization,
+                    "page_customization_en": free_plan.page_customization_en,
+                    "theme_color": free_plan.theme_color,
+                },
+                "started_at": None,
+                "expired_at": None,
+                "status": "active",
+                "quotas": free_plan.quotas or {},
+                "created_at": int(datetime.datetime.utcnow().timestamp() * 1000),
+                "updated_at": int(datetime.datetime.utcnow().timestamp() * 1000),
+            }, msg="免费套餐")
+
+        return success(data=svc.build_response(sub))
+
+    except ModuleNotFoundError:
+        # 社区版无 premium 模块，从配置文件读取免费套餐
+        if not current_user.tenant:
+            return JSONResponse(status_code=404, content=fail(code=404, msg="用户未关联租户"))
+
+        from app.config.default_free_plan import DEFAULT_FREE_PLAN
+
+        plan = DEFAULT_FREE_PLAN
+        response_data = {
+            "subscription_id": None,
+            "tenant_id": str(current_user.tenant.id),
+            "package_plan_id": None,
+            "package_version": plan["version"],
+            "package_plan": {
+                "id": None,
+                "name": plan["name"],
+                "name_en": plan.get("name_en"),
+                "version": plan["version"],
+                "category": plan["category"],
+                "tier_level": plan["tier_level"],
+                "price": float(plan["price"]),
+                "billing_cycle": plan["billing_cycle"],
+                "core_value": plan.get("core_value"),
+                "core_value_en": plan.get("core_value_en"),
+                "tech_support": plan.get("tech_support"),
+                "tech_support_en": plan.get("tech_support_en"),
+                "sla_compliance": plan.get("sla_compliance"),
+                "sla_compliance_en": plan.get("sla_compliance_en"),
+                "page_customization": plan.get("page_customization"),
+                "page_customization_en": plan.get("page_customization_en"),
+                "theme_color": plan.get("theme_color"),
+            },
+            "started_at": None,
+            "expired_at": None,
+            "status": "active",
+            "quotas": plan["quotas"],
+            "created_at": int(datetime.datetime.utcnow().timestamp() * 1000),
+            "updated_at": int(datetime.datetime.utcnow().timestamp() * 1000),
+        }
+        return success(data=response_data, msg="社区版免费套餐")
+
+    except Exception as e:
+        logger.error(f"获取租户套餐信息失败: {e}", exc_info=True)
+        return JSONResponse(status_code=500, content=fail(code=500, msg="获取套餐信息失败"))
+
+
+@public_router.get("/package-plans", response_model=ApiResponse, summary="获取套餐列表（公开）")
+async def list_package_plans_public(
+    category: Optional[str] = None,
+    status: Optional[bool] = None,
+    search: Optional[str] = None,
+    db: Session = Depends(get_db),
+):
+    """
+    公开接口，无需鉴权。
+    SaaS 版从数据库读取套餐列表；社区版降级返回 default_free_plan.py 中的免费套餐。
+    """
+    try:
+        from premium.platform_admin.package_plan_service import PackagePlanService
+        from premium.platform_admin.package_plan_schema import PackagePlanResponse
+        svc = PackagePlanService(db)
+        result = svc.get_list(page=1, size=9999, category=category, status=status, search=search)
+        return success(data=[PackagePlanResponse.model_validate(p).model_dump(mode="json") for p in result["items"]])
+    except ModuleNotFoundError:
+        from app.config.default_free_plan import DEFAULT_FREE_PLAN
+        plan = DEFAULT_FREE_PLAN
+        return success(data=[{
+            "id": None,
+            "name": plan["name"],
+            "name_en": plan.get("name_en"),
+            "version": plan["version"],
+            "category": plan["category"],
+            "tier_level": plan["tier_level"],
+            "price": float(plan["price"]),
+            "billing_cycle": plan["billing_cycle"],
+            "core_value": plan.get("core_value"),
+            "core_value_en": plan.get("core_value_en"),
+            "tech_support": plan.get("tech_support"),
+            "tech_support_en": plan.get("tech_support_en"),
+            "sla_compliance": plan.get("sla_compliance"),
+            "sla_compliance_en": plan.get("sla_compliance_en"),
+            "page_customization": plan.get("page_customization"),
+            "page_customization_en": plan.get("page_customization_en"),
+            "theme_color": plan.get("theme_color"),
+            "status": plan.get("status", True),
+            "quotas": plan["quotas"],
+        }])
+    except Exception as e:
+        logger.error(f"获取套餐列表失败: {e}", exc_info=True)
+        return JSONResponse(status_code=500, content=fail(code=500, msg="获取套餐列表失败"))

api/app/controllers/tool_controller.py

@@ -3,8 +3,11 @@ from typing import Optional
 
 from fastapi import APIRouter, Depends, HTTPException, Query
 from sqlalchemy.orm import Session
+
+from app.core.error_codes import BizCode
 from app.schemas.tool_schema import (
-    ToolCreateRequest, ToolUpdateRequest, ToolExecuteRequest, ParseSchemaRequest, CustomToolTestRequest
+    ToolCreateRequest, ToolUpdateRequest, ToolExecuteRequest, ParseSchemaRequest,
+    CustomToolTestRequest, ToolActiveUpdate
 )
 
 from app.core.response_utils import success
@@ -14,6 +17,7 @@ from app.models import User
 from app.models.tool_model import ToolType, ToolStatus, AuthType
 from app.services.tool_service import ToolService
 from app.schemas.response_schema import ApiResponse
+from app.core.exceptions import BusinessException
 
 router = APIRouter(prefix="/tools", tags=["Tool System"])
 
@@ -72,6 +76,8 @@ async def get_tool_methods(
         if methods is None:
             raise HTTPException(status_code=404, detail="工具不存在")
         return success(data=methods, msg="获取工具方法成功")
+    except HTTPException:
+        raise
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
 
@@ -97,7 +103,13 @@ async def create_tool(
 ):
     """创建工具"""
     try:
-        tool_id = service.create_tool(
+        # 将 MCP 来源字段合并进 config
+        if request.tool_type == ToolType.MCP:
+            for key in ("source_channel", "market_id", "market_config_id", "mcp_service_id"):
+                val = getattr(request, key, None)
+                if val is not None:
+                    request.config[key] = val
+        tool_id = await service.create_tool(
             name=request.name,
             tool_type=request.tool_type,
             tenant_id=current_user.tenant_id,
@@ -107,8 +119,12 @@ async def create_tool(
             tags=request.tags
         )
         return success(data={"tool_id": tool_id}, msg="工具创建成功")
+    except BusinessException as e:
+        raise HTTPException(status_code=400, detail=e.message)
     except ValueError as e:
         raise HTTPException(status_code=400, detail=str(e))
+    except HTTPException:
+        raise
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
 
@@ -137,6 +153,8 @@ async def update_tool(
         return success(msg="工具更新成功")
     except ValueError as e:
         raise HTTPException(status_code=400, detail=str(e))
+    except HTTPException:
+        raise
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
 
@@ -147,7 +165,7 @@ async def delete_tool(
         current_user: User = Depends(get_current_user),
         service: ToolService = Depends(get_tool_service)
 ):
-    """删除工具"""
+    """删除工具（逻辑删除，is_active=False）"""
     try:
         success_flag = service.delete_tool(tool_id, current_user.tenant_id)
         if not success_flag:
@@ -155,6 +173,34 @@ async def delete_tool(
         return success(msg="工具删除成功")
     except ValueError as e:
         raise HTTPException(status_code=400, detail=str(e))
+    except HTTPException:
+        raise
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.patch("/{tool_id}/active", response_model=ApiResponse)
+async def set_tool_active(
+        tool_id: str,
+        request: ToolActiveUpdate,
+        current_user: User = Depends(get_current_user),
+        service: ToolService = Depends(get_tool_service)
+):
+    """设置工具可用状态（启用/禁用）
+
+    - is_active=true: 启用工具
+    - is_active=false: 禁用工具（等同于删除，但可恢复）
+    """
+    try:
+        success_flag = service.set_tool_active(tool_id, current_user.tenant_id, request.is_active)
+        if not success_flag:
+            raise HTTPException(status_code=404, detail="工具不存在")
+        action = "启用" if request.is_active else "禁用"
+        return success(msg=f"工具已{action}")
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except HTTPException:
+        raise
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
 
@@ -187,6 +233,8 @@ async def execute_tool(
             },
             msg="工具执行完成"
         )
+    except HTTPException:
+        raise
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
 
@@ -203,6 +251,8 @@ async def parse_openapi_schema(
         if result["success"] is False:
             raise HTTPException(status_code=400, detail=result["message"])
         return success(data=result, msg="Schema解析完成")
+    except HTTPException:
+        raise
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
 
@@ -216,8 +266,10 @@ async def sync_mcp_tools(
     try:
         result = await service.sync_mcp_tools(tool_id, current_user.tenant_id)
         if not result.get("success", False):
-            raise HTTPException(status_code=400, detail=result.get("message", "同步失败"))
+            raise BusinessException(result.get("message", "工具列表同步失败"), BizCode.BAD_REQUEST)
         return success(data=result, msg="MCP工具列表同步完成")
+    except BusinessException:
+        raise
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
 
@@ -240,8 +292,10 @@ async def test_tool_connection(
             # 普通连接测试
             result = await service.test_connection(tool_id, current_user.tenant_id)
         if result["success"] is False:
-            raise HTTPException(status_code=400, detail=result["message"])
+            raise BusinessException(result["message"], BizCode.SERVICE_UNAVAILABLE)
         return success(data=result, msg="连接测试完成")
+    except BusinessException:
+        raise
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
 

api/app/controllers/user_controller.py

@@ -1,6 +1,7 @@
 from fastapi import APIRouter, Depends
 from sqlalchemy.orm import Session
 import uuid
+from typing import Callable
 
 from app.core.error_codes import BizCode
 from app.core.exceptions import BusinessException
@@ -19,6 +20,7 @@ from app.services import user_service
 from app.core.logging_config import get_api_logger
 from app.core.response_utils import success
 from app.core.security import verify_password
+from app.i18n.dependencies import get_translator
 
 # 获取API专用日志器
 api_logger = get_api_logger()
@@ -33,7 +35,8 @@ router = APIRouter(
 def create_superuser(
     user: user_schema.UserCreate,
     db: Session = Depends(get_db),
-    current_superuser: User = Depends(get_current_superuser)
+    current_superuser: User = Depends(get_current_superuser),
+    t: Callable = Depends(get_translator)
 ):
     """创建超级管理员（仅超级管理员可访问）"""
     api_logger.info(f"超级管理员创建请求: {user.username}, email: {user.email}")
@@ -42,7 +45,7 @@ def create_superuser(
     api_logger.info(f"超级管理员创建成功: {result.username} (ID: {result.id})")
     
     result_schema = user_schema.User.model_validate(result)
-    return success(data=result_schema, msg="超级管理员创建成功")
+    return success(data=result_schema, msg=t("users.create.superuser_success"))
 
 
 @router.delete("/{user_id}", response_model=ApiResponse)
@@ -50,6 +53,7 @@ def delete_user(
     user_id: uuid.UUID,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
+    t: Callable = Depends(get_translator)
 ):
     """停用用户（软删除）"""
     api_logger.info(f"用户停用请求: user_id={user_id}, 操作者: {current_user.username}")
@@ -57,13 +61,14 @@ def delete_user(
         db=db, user_id_to_deactivate=user_id, current_user=current_user
     )
     api_logger.info(f"用户停用成功: {result.username} (ID: {result.id})")
-    return success(msg="用户停用成功")
+    return success(msg=t("users.delete.deactivate_success"))
 
 @router.post("/{user_id}/activate", response_model=ApiResponse)
 def activate_user(
     user_id: uuid.UUID,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
+    t: Callable = Depends(get_translator)
 ):
     """激活用户"""
     api_logger.info(f"用户激活请求: user_id={user_id}, 操作者: {current_user.username}")
@@ -74,13 +79,14 @@ def activate_user(
     api_logger.info(f"用户激活成功: {result.username} (ID: {result.id})")
     
     result_schema = user_schema.User.model_validate(result)
-    return success(data=result_schema, msg="用户激活成功")
+    return success(data=result_schema, msg=t("users.activate.success"))
 
 
 @router.get("", response_model=ApiResponse)
 def get_current_user_info(
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
+    t: Callable = Depends(get_translator)
 ):
     """获取当前用户信息"""
     api_logger.info(f"当前用户信息请求: {current_user.username}")
@@ -105,7 +111,22 @@ def get_current_user_info(
                 break
     
     api_logger.info(f"当前用户信息获取成功: {result.username}, 角色: {result_schema.role}, 工作空间: {result_schema.current_workspace_name}")
-    return success(data=result_schema, msg="用户信息获取成功")
+
+    # 设置权限：如果用户来自 SSO Source，则使用该 Source 的 permissions；否则返回 "all" 表示拥有所有权限
+    if current_user.external_source:
+        try:
+            from premium.sso.models import SSOSource
+            source = db.query(SSOSource).filter(SSOSource.source_code == current_user.external_source).first()
+            if source and source.permissions:
+                result_schema.permissions = source.permissions
+            else:
+                result_schema.permissions = []
+        except ModuleNotFoundError:
+            result_schema.permissions = []
+    else:
+        result_schema.permissions = ["all"]
+
+    return success(data=result_schema, msg=t("users.info.get_success"))
 
 
 @router.get("/superusers", response_model=ApiResponse)
@@ -113,6 +134,7 @@ def get_tenant_superusers(
     include_inactive: bool = False,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_superuser),
+    t: Callable = Depends(get_translator)
 ):
     """获取当前租户下的超管账号列表（仅超级管理员可访问）"""
     api_logger.info(f"获取租户超管列表请求: {current_user.username}")
@@ -125,8 +147,7 @@ def get_tenant_superusers(
     api_logger.info(f"租户超管列表获取成功: count={len(superusers)}")
     
     superusers_schema = [user_schema.User.model_validate(u) for u in superusers]
-    return success(data=superusers_schema, msg="租户超管列表获取成功")
-
+    return success(data=superusers_schema, msg=t("users.list.superusers_success"))
 
 
 @router.get("/{user_id}", response_model=ApiResponse)
@@ -134,6 +155,7 @@ def get_user_info_by_id(
     user_id: uuid.UUID,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
+    t: Callable = Depends(get_translator)
 ):
     """根据用户ID获取用户信息"""
     api_logger.info(f"获取用户信息请求: user_id={user_id}, 操作者: {current_user.username}")
@@ -144,7 +166,7 @@ def get_user_info_by_id(
     api_logger.info(f"用户信息获取成功: {result.username}")
     
     result_schema = user_schema.User.model_validate(result)
-    return success(data=result_schema, msg="用户信息获取成功")
+    return success(data=result_schema, msg=t("users.info.get_success"))
 
 
 @router.put("/change-password", response_model=ApiResponse)
@@ -152,6 +174,7 @@ async def change_password(
     request: ChangePasswordRequest,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
+    t: Callable = Depends(get_translator)
 ):
     """修改当前用户密码"""
     api_logger.info(f"用户密码修改请求: {current_user.username}")
@@ -164,7 +187,7 @@ async def change_password(
         current_user=current_user
     )
     api_logger.info(f"用户密码修改成功: {current_user.username}")
-    return success(msg="密码修改成功")
+    return success(msg=t("auth.password.change_success"))
 
 
 @router.put("/admin/change-password", response_model=ApiResponse)
@@ -172,6 +195,7 @@ async def admin_change_password(
     request: AdminChangePasswordRequest,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_superuser),
+    t: Callable = Depends(get_translator)
 ):
     """超级管理员修改指定用户的密码"""
     api_logger.info(f"管理员密码修改请求: 管理员 {current_user.username} 修改用户 {request.user_id}")
@@ -186,16 +210,17 @@ async def admin_change_password(
     # 根据是否生成了随机密码来构造响应
     if request.new_password:
         api_logger.info(f"管理员密码修改成功: 用户 {request.user_id}")
-        return success(msg="密码修改成功")
+        return success(msg=t("auth.password.change_success"))
     else:
         api_logger.info(f"管理员密码重置成功: 用户 {request.user_id}, 随机密码已生成")
-        return success(data=generated_password, msg="密码重置成功")
+        return success(data=generated_password, msg=t("auth.password.reset_success"))
 
 
 @router.post("/verify_pwd", response_model=ApiResponse)
 def verify_pwd(
     request: VerifyPasswordRequest,
     current_user: User = Depends(get_current_user),
+    t: Callable = Depends(get_translator)
 ):
     """验证当前用户密码"""
     api_logger.info(f"用户验证密码请求: {current_user.username}")
@@ -203,8 +228,8 @@ def verify_pwd(
     is_valid = verify_password(request.password, current_user.hashed_password)
     api_logger.info(f"用户密码验证结果: {current_user.username}, valid={is_valid}")
     if not is_valid:
-        raise BusinessException("密码验证失败", code=BizCode.VALIDATION_FAILED)
-    return success(data={"valid": is_valid}, msg="验证完成")
+        raise BusinessException(t("users.errors.password_verification_failed"), code=BizCode.VALIDATION_FAILED)
+    return success(data={"valid": is_valid}, msg=t("common.success.retrieved"))
 
 
 @router.post("/send-email-code", response_model=ApiResponse)
@@ -212,6 +237,7 @@ async def send_email_code(
     request: SendEmailCodeRequest,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
+    t: Callable = Depends(get_translator)
 ):
     """发送邮箱验证码"""
     api_logger.info(f"用户请求发送邮箱验证码: {current_user.username}, email={request.email}")
@@ -219,7 +245,7 @@ async def send_email_code(
     await user_service.send_email_code_method(db=db, email=request.email, user_id=current_user.id)
     
     api_logger.info(f"邮箱验证码已发送: {current_user.username}")
-    return success(msg="验证码已发送到您的邮箱，请查收")
+    return success(msg=t("users.email.code_sent"))
 
 
 @router.put("/change-email", response_model=ApiResponse)
@@ -227,6 +253,7 @@ async def change_email(
     request: VerifyEmailCodeRequest,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
+    t: Callable = Depends(get_translator)
 ):
     """验证验证码并修改邮箱"""
     api_logger.info(f"用户修改邮箱: {current_user.username}, new_email={request.new_email}")
@@ -239,4 +266,51 @@ async def change_email(
     )
     
     api_logger.info(f"用户邮箱修改成功: {current_user.username}")
-    return success(msg="邮箱修改成功")
+    return success(msg=t("users.email.change_success"))
+
+
+
+@router.get("/me/language", response_model=ApiResponse)
+def get_current_user_language(
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+    t: Callable = Depends(get_translator)
+):
+    """获取当前用户的语言偏好"""
+    api_logger.info(f"获取用户语言偏好: {current_user.username}")
+    
+    language = user_service.get_user_language_preference(
+        db=db,
+        user_id=current_user.id,
+        current_user=current_user
+    )
+    
+    api_logger.info(f"用户语言偏好获取成功: {current_user.username}, language={language}")
+    return success(
+        data=user_schema.LanguagePreferenceResponse(language=language),
+        msg=t("users.language.get_success")
+    )
+
+
+@router.put("/me/language", response_model=ApiResponse)
+def update_current_user_language(
+    request: user_schema.LanguagePreferenceRequest,
+    db: Session = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+    t: Callable = Depends(get_translator)
+):
+    """设置当前用户的语言偏好"""
+    api_logger.info(f"更新用户语言偏好: {current_user.username}, language={request.language}")
+    
+    updated_user = user_service.update_user_language_preference(
+        db=db,
+        user_id=current_user.id,
+        language=request.language,
+        current_user=current_user
+    )
+    
+    api_logger.info(f"用户语言偏好更新成功: {current_user.username}, language={request.language}")
+    return success(
+        data=user_schema.LanguagePreferenceResponse(language=updated_user.preferred_language),
+        msg=t("users.language.update_success")
+    )

api/app/controllers/user_memory_controllers.py

@@ -5,7 +5,7 @@
 from typing import Optional
 import datetime
 from sqlalchemy.orm import Session
-from fastapi import APIRouter, Depends,Header
+from fastapi import APIRouter, Depends, Header
 
 from app.db import get_db
 from app.core.language_utils import get_language_from_header
@@ -17,14 +17,17 @@ from app.services.user_memory_service import (
     UserMemoryService,
     analytics_memory_types,
     analytics_graph_data,
+    analytics_community_graph_data,
 )
-from app.services.memory_entity_relationship_service import MemoryEntityService,MemoryEmotion,MemoryInteraction
+from app.services.memory_entity_relationship_service import MemoryEntityService, MemoryEmotion, MemoryInteraction
 from app.schemas.response_schema import ApiResponse
 from app.schemas.memory_storage_schema import GenerateCacheRequest
 from app.repositories.workspace_repository import WorkspaceRepository
-from app.schemas.end_user_schema import (
-    EndUserProfileResponse,
-    EndUserProfileUpdate,
+from app.repositories.end_user_repository import EndUserRepository
+from app.schemas.end_user_info_schema import (
+    EndUserInfoResponse,
+    EndUserInfoCreate,
+    EndUserInfoUpdate,
 )
 from app.models.end_user_model import EndUser
 from app.dependencies import get_current_user
@@ -44,9 +47,9 @@ router = APIRouter(
 
 @router.get("/analytics/memory_insight/report", response_model=ApiResponse)
 async def get_memory_insight_report_api(
-    end_user_id: str,
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db),
+        end_user_id: str,
+        current_user: User = Depends(get_current_user),
+        db: Session = Depends(get_db),
 ) -> dict:
     """
     获取缓存的记忆洞察报告
@@ -72,10 +75,10 @@ async def get_memory_insight_report_api(
 
 @router.get("/analytics/user_summary", response_model=ApiResponse)
 async def get_user_summary_api(
-    end_user_id: str,
-    language_type: str = Header(default=None, alias="X-Language-Type"),
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db),
+        end_user_id: str,
+        language_type: str = Header(default=None, alias="X-Language-Type"),
+        current_user: User = Depends(get_current_user),
+        db: Session = Depends(get_db),
 ) -> dict:
     """
     获取缓存的用户摘要
@@ -89,7 +92,7 @@ async def get_user_summary_api(
     """
     # 使用集中化的语言校验
     language = get_language_from_header(language_type)
-    
+
     workspace_id = current_user.current_workspace_id
     workspace_repo = WorkspaceRepository(db)
     workspace_models = workspace_repo.get_workspace_models_configs(workspace_id)
@@ -101,7 +104,7 @@ async def get_user_summary_api(
     api_logger.info(f"用户摘要查询请求: end_user_id={end_user_id}, user={current_user.username}")
     try:
         # 调用服务层获取缓存数据
-        result = await user_memory_service.get_cached_user_summary(db, end_user_id,model_id,language)
+        result = await user_memory_service.get_cached_user_summary(db, end_user_id, model_id, language)
 
         if result["is_cached"]:
             api_logger.info(f"成功返回缓存的用户摘要: end_user_id={end_user_id}")
@@ -116,10 +119,10 @@ async def get_user_summary_api(
 
 @router.post("/analytics/generate_cache", response_model=ApiResponse)
 async def generate_cache_api(
-    request: GenerateCacheRequest,
-    language_type: str = Header(default=None, alias="X-Language-Type"),
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db),
+        request: GenerateCacheRequest,
+        language_type: str = Header(default=None, alias="X-Language-Type"),
+        current_user: User = Depends(get_current_user),
+        db: Session = Depends(get_db),
 ) -> dict:
     """
     手动触发缓存生成
@@ -133,7 +136,7 @@ async def generate_cache_api(
     """
     # 使用集中化的语言校验
     language = get_language_from_header(language_type)
-    
+
     workspace_id = current_user.current_workspace_id
 
     # 检查用户是否已选择工作空间
@@ -154,10 +157,12 @@ async def generate_cache_api(
             api_logger.info(f"开始为单个用户生成缓存: end_user_id={end_user_id}")
 
             # 生成记忆洞察
-            insight_result = await user_memory_service.generate_and_cache_insight(db, end_user_id, workspace_id, language=language)
+            insight_result = await user_memory_service.generate_and_cache_insight(db, end_user_id, workspace_id,
+                                                                                  language=language)
 
             # 生成用户摘要
-            summary_result = await user_memory_service.generate_and_cache_summary(db, end_user_id, workspace_id, language=language)
+            summary_result = await user_memory_service.generate_and_cache_summary(db, end_user_id, workspace_id,
+                                                                                  language=language)
 
             # 构建响应
             result = {
@@ -208,9 +213,9 @@ async def generate_cache_api(
 
 @router.get("/analytics/node_statistics", response_model=ApiResponse)
 async def get_node_statistics_api(
-    end_user_id: str,
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db),
+        end_user_id: str,
+        current_user: User = Depends(get_current_user),
+        db: Session = Depends(get_db),
 ) -> dict:
     workspace_id = current_user.current_workspace_id
 
@@ -219,7 +224,8 @@ async def get_node_statistics_api(
         api_logger.warning(f"用户 {current_user.username} 尝试查询节点统计但未选择工作空间")
         return fail(BizCode.INVALID_PARAMETER, "请先切换到一个工作空间", "current_workspace_id is None")
 
-    api_logger.info(f"记忆类型统计请求: end_user_id={end_user_id}, user={current_user.username}, workspace={workspace_id}")
+    api_logger.info(
+        f"记忆类型统计请求: end_user_id={end_user_id}, user={current_user.username}, workspace={workspace_id}")
 
     try:
         # 调用新的记忆类型统计函数
@@ -227,21 +233,23 @@ async def get_node_statistics_api(
 
         # 计算总数用于日志
         total_count = sum(item["count"] for item in result)
-        api_logger.info(f"成功获取记忆类型统计: end_user_id={end_user_id}, 总记忆数={total_count}, 类型数={len(result)}")
+        api_logger.info(
+            f"成功获取记忆类型统计: end_user_id={end_user_id}, 总记忆数={total_count}, 类型数={len(result)}")
         return success(data=result, msg="查询成功")
     except Exception as e:
         api_logger.error(f"记忆类型查询失败: end_user_id={end_user_id}, error={str(e)}")
         return fail(BizCode.INTERNAL_ERROR, "记忆类型查询失败", str(e))
 
+
 @router.get("/analytics/graph_data", response_model=ApiResponse)
 async def get_graph_data_api(
-    end_user_id: str,
-    node_types: Optional[str] = None,
-    limit: int = 100,
-    depth: int = 1,
-    center_node_id: Optional[str] = None,
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db),
+        end_user_id: str,
+        node_types: Optional[str] = None,
+        limit: int = 100,
+        depth: int = 1,
+        center_node_id: Optional[str] = None,
+        current_user: User = Depends(get_current_user),
+        db: Session = Depends(get_db),
 ) -> dict:
     workspace_id = current_user.current_workspace_id
 
@@ -295,110 +303,165 @@ async def get_graph_data_api(
         return fail(BizCode.INTERNAL_ERROR, "图数据查询失败", str(e))
 
 
-@router.get("/read_end_user/profile", response_model=ApiResponse)
-async def get_end_user_profile(
-    end_user_id: str,
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db),
+@router.get("/analytics/community_graph", response_model=ApiResponse)
+async def get_community_graph_data_api(
+        end_user_id: str,
+        current_user: User = Depends(get_current_user),
+        db: Session = Depends(get_db),
 ) -> dict:
     workspace_id = current_user.current_workspace_id
-    workspace_repo = WorkspaceRepository(db)
-    workspace_models = workspace_repo.get_workspace_models_configs(workspace_id)
 
-    if workspace_models:
-        model_id = workspace_models.get("llm", None)
-    else:
-        model_id = None
-    # 检查用户是否已选择工作空间
     if workspace_id is None:
-        api_logger.warning(f"用户 {current_user.username} 尝试查询用户信息但未选择工作空间")
+        api_logger.warning(f"用户 {current_user.username} 尝试查询社区图谱但未选择工作空间")
         return fail(BizCode.INVALID_PARAMETER, "请先切换到一个工作空间", "current_workspace_id is None")
 
     api_logger.info(
-        f"用户信息查询请求: end_user_id={end_user_id}, user={current_user.username}, "
+        f"社区图谱查询请求: end_user_id={end_user_id}, user={current_user.username}, "
         f"workspace={workspace_id}"
     )
 
     try:
-        # 查询终端用户
-        end_user = db.query(EndUser).filter(EndUser.id == end_user_id).first()
+        result = await analytics_community_graph_data(db=db, end_user_id=end_user_id)
 
-        if not end_user:
-            api_logger.warning(f"终端用户不存在: end_user_id={end_user_id}")
-            return fail(BizCode.INVALID_PARAMETER, "终端用户不存在", f"end_user_id={end_user_id}")
-        # 构建响应数据
-        profile_data = EndUserProfileResponse(
-            id=end_user.id,
-            other_name=end_user.other_name,
-            position=end_user.position,
-            department=end_user.department,
-            contact=end_user.contact,
-            phone=end_user.phone,
-            hire_date=end_user.hire_date,
-            updatetime_profile=end_user.updatetime_profile
+        if "message" in result and result["statistics"]["total_nodes"] == 0:
+            api_logger.warning(f"社区图谱查询返回空结果: {result.get('message')}")
+            return success(data=result, msg=result.get("message", "查询成功"))
+
+        api_logger.info(
+            f"成功获取社区图谱: end_user_id={end_user_id}, "
+            f"nodes={result['statistics']['total_nodes']}, "
+            f"edges={result['statistics']['total_edges']}"
         )
-
-        api_logger.info(f"成功获取用户信息: end_user_id={end_user_id}")
-        return success(data=UserMemoryService.convert_profile_to_dict_with_timestamp(profile_data), msg="查询成功")
+        return success(data=result, msg="查询成功")
 
     except Exception as e:
-        api_logger.error(f"用户信息查询失败: end_user_id={end_user_id}, error={str(e)}")
-        return fail(BizCode.INTERNAL_ERROR, "用户信息查询失败", str(e))
+        api_logger.error(f"社区图谱查询失败: end_user_id={end_user_id}, error={str(e)}")
+        return fail(BizCode.INTERNAL_ERROR, "社区图谱查询失败", str(e))
 
+#=======================终端用户信息接口=======================
 
-@router.post("/updated_end_user/profile", response_model=ApiResponse)
-async def update_end_user_profile(
-    profile_update: EndUserProfileUpdate,
+@router.get("/end_user_info", response_model=ApiResponse)
+async def get_end_user_info(
+    end_user_id: str,
     current_user: User = Depends(get_current_user),
     db: Session = Depends(get_db),
 ) -> dict:
     """
-    更新终端用户的基本信息
+    查询终端用户信息记录
 
-    该接口可以更新用户的姓名、职位、部门、联系方式、电话和入职日期等信息。
-    所有字段都是可选的，只更新提供的字段。
+    根据 end_user_id 查询单条终端用户信息记录。
     """
     workspace_id = current_user.current_workspace_id
-    end_user_id = profile_update.end_user_id
 
-    # 验证工作空间
     if workspace_id is None:
-        api_logger.warning(f"用户 {current_user.username} 尝试更新用户信息但未选择工作空间")
+        api_logger.warning(f"用户 {current_user.username} 尝试查询终端用户信息但未选择工作空间")
         return fail(BizCode.INVALID_PARAMETER, "请先切换到一个工作空间", "current_workspace_id is None")
 
     api_logger.info(
-        f"用户信息更新请求: end_user_id={end_user_id}, user={current_user.username}, "
+        f"查询终端用户信息请求: end_user_id={end_user_id}, user={current_user.username}, "
         f"workspace={workspace_id}"
     )
 
-    # 调用 Service 层处理业务逻辑
-    result = user_memory_service.update_end_user_profile(db, end_user_id, profile_update)
+    # 校验 end_user 是否属于当前工作空间
+    end_user_repo = EndUserRepository(db)
+    end_user = end_user_repo.get_end_user_by_id(end_user_id)
+    if end_user is None:
+        return fail(BizCode.USER_NOT_FOUND, "终端用户不存在", "end_user not found")
+    if str(end_user.workspace_id) != str(workspace_id):
+        api_logger.warning(
+            f"用户 {current_user.username} 尝试查询不属于工作空间 {workspace_id} 的终端用户 {end_user_id}"
+        )
+        return fail(BizCode.PERMISSION_DENIED, "该终端用户不属于当前工作空间", "end_user workspace mismatch")
+
+    result = user_memory_service.get_end_user_info(db, end_user_id)
 
     if result["success"]:
-        api_logger.info(f"成功更新用户信息: end_user_id={end_user_id}")
+        api_logger.info(f"成功查询终端用户信息: end_user_id={end_user_id}")
+        return success(data=result["data"], msg="查询成功")
+    else:
+        error_msg = result["error"]
+        api_logger.error(f"查询终端用户信息失败: end_user_id={end_user_id}, error={error_msg}")
+        
+        if error_msg == "终端用户信息记录不存在":
+            return fail(BizCode.USER_NOT_FOUND, "终端用户信息记录不存在", error_msg)
+        elif error_msg == "无效的终端用户ID格式":
+            return fail(BizCode.INVALID_USER_ID, "无效的终端用户ID格式", error_msg)
+        else:
+            return fail(BizCode.INTERNAL_ERROR, "查询终端用户信息失败", error_msg)
+
+
+@router.post("/end_user_info/updated", response_model=ApiResponse)
+async def update_end_user_info(
+    info_update: EndUserInfoUpdate,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """
+    更新终端用户信息记录
+
+    根据 end_user_id 更新终端用户信息记录，支持批量更新多个别名。
+    
+    示例请求体：
+    {
+      "end_user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+      "other_name": "张三1",
+      "aliases": ["小张", "张工"],
+      "meta_data": {"position": "工程师", "department": "技术部"}
+    }
+    """
+    workspace_id = current_user.current_workspace_id
+    end_user_id = info_update.end_user_id
+
+    if workspace_id is None:
+        api_logger.warning(f"用户 {current_user.username} 尝试更新终端用户信息但未选择工作空间")
+        return fail(BizCode.INVALID_PARAMETER, "请先切换到一个工作空间", "current_workspace_id is None")
+
+    api_logger.info(
+        f"更新终端用户信息请求: end_user_id={end_user_id}, user={current_user.username}, "
+        f"workspace={workspace_id}"
+    )
+
+    # 校验 end_user 是否属于当前工作空间
+    end_user_repo = EndUserRepository(db)
+    end_user = end_user_repo.get_end_user_by_id(end_user_id)
+    if end_user is None:
+        return fail(BizCode.USER_NOT_FOUND, "终端用户不存在", "end_user not found")
+    if str(end_user.workspace_id) != str(workspace_id):
+        api_logger.warning(
+            f"用户 {current_user.username} 尝试更新不属于工作空间 {workspace_id} 的终端用户 {end_user_id}"
+        )
+        return fail(BizCode.PERMISSION_DENIED, "该终端用户不属于当前工作空间", "end_user workspace mismatch")
+
+    # 获取更新数据（排除 end_user_id）
+    update_data = info_update.model_dump(exclude_unset=True, exclude={'end_user_id'})
+    
+    result = user_memory_service.update_end_user_info(db, end_user_id, update_data)
+
+    if result["success"]:
+        api_logger.info(f"成功更新终端用户信息: end_user_id={end_user_id}")
         return success(data=result["data"], msg="更新成功")
     else:
         error_msg = result["error"]
-        api_logger.error(f"用户信息更新失败: end_user_id={end_user_id}, error={error_msg}")
+        api_logger.error(f"终端用户信息更新失败: end_user_id={end_user_id}, error={error_msg}")
         
-        # 根据错误类型映射到合适的业务错误码
-        if error_msg == "终端用户不存在":
-            return fail(BizCode.USER_NOT_FOUND, "终端用户不存在", error_msg)
-        elif error_msg == "无效的用户ID格式":
-            return fail(BizCode.INVALID_USER_ID, "无效的用户ID格式", error_msg)
+        if error_msg == "终端用户信息记录不存在":
+            return fail(BizCode.USER_NOT_FOUND, "终端用户信息记录不存在", error_msg)
+        elif error_msg == "无效的终端用户ID格式":
+            return fail(BizCode.INVALID_USER_ID, "无效的终端用户ID格式", error_msg)
         else:
-            # 只有未预期的错误才使用 INTERNAL_ERROR
-            return fail(BizCode.INTERNAL_ERROR, "用户信息更新失败", error_msg)
+            return fail(BizCode.INTERNAL_ERROR, "终端用户信息更新失败", error_msg)
 
 @router.get("/memory_space/timeline_memories", response_model=ApiResponse)
-async def memory_space_timeline_of_shared_memories(id: str, label: str,language_type: str = Header(default=None, alias="X-Language-Type"),
-                                      current_user: User = Depends(get_current_user),
-                                      db: Session = Depends(get_db),
-                                      ):
+async def memory_space_timeline_of_shared_memories(
+        id: str, label: str,
+        language_type: str = Header(default=None, alias="X-Language-Type"),
+        current_user: User = Depends(get_current_user),
+        db: Session = Depends(get_db),
+):
     # 使用集中化的语言校验
     language = get_language_from_header(language_type)
-    
-    workspace_id=current_user.current_workspace_id
+
+    workspace_id = current_user.current_workspace_id
     workspace_repo = WorkspaceRepository(db)
     workspace_models = workspace_repo.get_workspace_models_configs(workspace_id)
 
@@ -410,11 +473,13 @@ async def memory_space_timeline_of_shared_memories(id: str, label: str,language_
     timeline_memories_result = await MemoryEntity.get_timeline_memories_server(model_id, language)
 
     return success(data=timeline_memories_result, msg="共同记忆时间线")
+
+
 @router.get("/memory_space/relationship_evolution", response_model=ApiResponse)
 async def memory_space_relationship_evolution(id: str, label: str,
-                                      current_user: User = Depends(get_current_user),
-                                      db: Session = Depends(get_db),
-                                      ):
+                                              current_user: User = Depends(get_current_user),
+                                              db: Session = Depends(get_db),
+                                              ):
     try:
         api_logger.info(f"关系演变查询请求: id={id}, table={label}, user={current_user.username}")
 

api/app/controllers/workspace_controller.py

@@ -1,7 +1,7 @@
 import uuid
 from typing import List, Optional
 
-from fastapi import APIRouter, Depends, HTTPException, Query, status
+from fastapi import APIRouter, Depends, Header, HTTPException, Query, status
 from sqlalchemy.orm import Session
 
 from app.core.logging_config import get_api_logger
@@ -14,6 +14,12 @@ from app.dependencies import (
     get_current_user,
     workspace_access_guard,
 )
+from app.i18n.dependencies import get_current_language, get_translator
+from app.i18n.serializers import (
+    WorkspaceSerializer,
+    WorkspaceMemberSerializer,
+    WorkspaceInviteSerializer
+)
 from app.models.tenant_model import Tenants
 from app.models.user_model import User
 from app.models.workspace_model import InviteStatus
@@ -29,6 +35,7 @@ from app.schemas.workspace_schema import (
     WorkspaceUpdate,
 )
 from app.services import workspace_service
+from app.core.quota_stub import check_workspace_quota
 
 # 获取API专用日志器
 api_logger = get_api_logger()
@@ -65,7 +72,9 @@ def get_workspaces(
     include_current: bool = Query(True, description="是否包含当前工作空间"),
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
-    current_tenant: Tenants = Depends(get_current_tenant)
+    current_tenant: Tenants = Depends(get_current_tenant),
+    language: str = Depends(get_current_language),
+    t: callable = Depends(get_translator)
 ):
     """获取当前租户下用户参与的所有工作空间
 
@@ -88,25 +97,51 @@ def get_workspaces(
         )
 
     api_logger.info(f"成功获取 {len(workspaces)} 个工作空间")
-    workspaces_schema = [WorkspaceResponse.model_validate(w) for w in workspaces]
-    return success(data=workspaces_schema, msg="工作空间列表获取成功")
+    
+    # 使用序列化器添加国际化字段
+    serializer = WorkspaceSerializer()
+    workspaces_data = [WorkspaceResponse.model_validate(w).model_dump() for w in workspaces]
+    workspaces_i18n = serializer.serialize_list(workspaces_data, language)
+    
+    return success(data=workspaces_i18n, msg=t("workspace.list_retrieved"))
 
 
 @router.post("", response_model=ApiResponse)
+@check_workspace_quota
 def create_workspace(
     workspace: WorkspaceCreate,
+    language_type: str = Header(default="zh", alias="X-Language-Type"),
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_superuser),
+    language: str = Depends(get_current_language),
+    t: callable = Depends(get_translator)
 ):
     """创建新的工作空间"""
-    api_logger.info(f"用户 {current_user.username} 请求创建工作空间: {workspace.name}")
+    from app.core.language_utils import get_language_from_header
+    
+    # 验证并获取语言参数
+    language = get_language_from_header(language_type)
+    
+    api_logger.info(
+        f"用户 {current_user.username} 请求创建工作空间: {workspace.name}, "
+        f"language={language}"
+    )
 
     result = workspace_service.create_workspace(
-        db=db, workspace=workspace, user=current_user)
+        db=db, workspace=workspace, user=current_user, language=language
+    )
 
-    api_logger.info(f"工作空间创建成功 - 名称: {workspace.name}, ID: {result.id}, 创建者: {current_user.username}")
-    result_schema = WorkspaceResponse.model_validate(result)
-    return success(data=result_schema, msg="工作空间创建成功")
+    api_logger.info(
+        f"工作空间创建成功 - 名称: {workspace.name}, ID: {result.id}, "
+        f"创建者: {current_user.username}, language={language}"
+    )
+    
+    # 使用序列化器添加国际化字段
+    serializer = WorkspaceSerializer()
+    result_data = WorkspaceResponse.model_validate(result).model_dump()
+    result_i18n = serializer.serialize(result_data, language)
+    
+    return success(data=result_i18n, msg=t("workspace.created"))
 
 @router.put("", response_model=ApiResponse)
 @cur_workspace_access_guard()
@@ -114,6 +149,8 @@ def update_workspace(
     workspace: WorkspaceUpdate,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
+    language: str = Depends(get_current_language),
+    t: callable = Depends(get_translator)
 ):
     """更新工作空间"""
     workspace_id = current_user.current_workspace_id
@@ -126,14 +163,21 @@ def update_workspace(
         user=current_user,
     )
     api_logger.info(f"工作空间更新成功 - ID: {workspace_id}, 用户: {current_user.username}")
-    result_schema = WorkspaceResponse.model_validate(result)
-    return success(data=result_schema, msg="工作空间更新成功")
+    
+    # 使用序列化器添加国际化字段
+    serializer = WorkspaceSerializer()
+    result_data = WorkspaceResponse.model_validate(result).model_dump()
+    result_i18n = serializer.serialize(result_data, language)
+    
+    return success(data=result_i18n, msg=t("workspace.updated"))
 
 @router.get("/members", response_model=ApiResponse)
 @cur_workspace_access_guard()
 def get_cur_workspace_members(
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
+    language: str = Depends(get_current_language),
+    t: callable = Depends(get_translator)
 ):
     """获取工作空间成员列表（关系序列化）"""
     api_logger.info(f"用户 {current_user.username} 请求获取工作空间 {current_user.current_workspace_id} 的成员列表")
@@ -144,8 +188,14 @@ def get_cur_workspace_members(
         user=current_user,
     )
     api_logger.info(f"工作空间成员列表获取成功 - ID: {current_user.current_workspace_id}, 数量: {len(members)}")
+    
+    # 转换为表格项并使用序列化器添加国际化字段
     table_items = _convert_members_to_table_items(members)
-    return success(data=table_items, msg="工作空间成员列表获取成功")
+    serializer = WorkspaceMemberSerializer()
+    members_data = [item.model_dump() for item in table_items]
+    members_i18n = serializer.serialize_list(members_data, language)
+    
+    return success(data=members_i18n, msg=t("workspace.members.list_retrieved"))
 
 
 @router.put("/members", response_model=ApiResponse)
@@ -155,6 +205,7 @@ def update_workspace_members(
     updates: List[WorkspaceMemberUpdate],
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
+    t: callable = Depends(get_translator)
 ):
     workspace_id = current_user.current_workspace_id
     api_logger.info(f"用户 {current_user.username} 请求更新工作空间 {workspace_id} 的成员角色")
@@ -165,27 +216,28 @@ def update_workspace_members(
         user=current_user,
     )
     api_logger.info(f"工作空间成员角色更新成功 - ID: {workspace_id}, 数量: {len(members)}")
-    return success(msg="成员角色更新成功")
+    return success(msg=t("workspace.members.role_updated"))
 
 
 @router.delete("/members/{member_id}", response_model=ApiResponse)
 @cur_workspace_access_guard()
-def delete_workspace_member(
+async def delete_workspace_member(
     member_id: uuid.UUID,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
+    t: callable = Depends(get_translator)
 ):
     workspace_id = current_user.current_workspace_id
     api_logger.info(f"用户 {current_user.username} 请求删除工作空间 {workspace_id} 的成员 {member_id}")
 
-    workspace_service.delete_workspace_member(
+    await workspace_service.delete_workspace_member(
         db=db,
         workspace_id=workspace_id,
         member_id=member_id,
         user=current_user,
     )
     api_logger.info(f"工作空间成员删除成功 - ID: {workspace_id}, 成员: {member_id}")
-    return success(msg="成员删除成功")
+    return success(msg=t("workspace.members.deleted"))
 
 
 # 创建空间协作邀请
@@ -195,6 +247,8 @@ def create_workspace_invite(
     invite_data: WorkspaceInviteCreate,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
+    language: str = Depends(get_current_language),
+    t: callable = Depends(get_translator)
 ):
     """创建工作空间邀请"""
     workspace_id = current_user.current_workspace_id
@@ -207,7 +261,12 @@ def create_workspace_invite(
         user=current_user
     )
     api_logger.info(f"工作空间邀请创建成功 - 工作空间: {workspace_id}, 邮箱: {invite_data.email}")
-    return success(data=result, msg="邀请创建成功")
+    
+    # 使用序列化器添加国际化字段
+    serializer = WorkspaceInviteSerializer()
+    result_i18n = serializer.serialize(result, language)
+    
+    return success(data=result_i18n, msg=t("workspace.invites.created"))
 
 
 @router.get("/invites", response_model=ApiResponse)
@@ -219,6 +278,8 @@ def get_workspace_invites(
     offset: int = Query(0, ge=0),
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
+    language: str = Depends(get_current_language),
+    t: callable = Depends(get_translator)
 ):
     """获取工作空间邀请列表"""
     workspace_id = current_user.current_workspace_id
@@ -233,18 +294,30 @@ def get_workspace_invites(
         offset=offset
     )
     api_logger.info(f"成功获取 {len(invites)} 个邀请记录")
-    return success(data=invites, msg="邀请列表获取成功")
+    
+    # 使用序列化器添加国际化字段
+    serializer = WorkspaceInviteSerializer()
+    invites_i18n = serializer.serialize_list(invites, language)
+    
+    return success(data=invites_i18n, msg=t("workspace.invites.list_retrieved"))
 
 
 @public_router.get("/invites/validate/{token}", response_model=ApiResponse)
 def get_workspace_invite_info(
     token: str,
     db: Session = Depends(get_db),
+    language: str = Depends(get_current_language),
+    t: callable = Depends(get_translator)
 ):
     """获取工作空间邀请用户信息（无需认证）"""
     result = workspace_service.validate_invite_token(db=db, token=token)
     api_logger.info(f"工作空间邀请验证成功 - 邀请: {token}")
-    return success(data=result, msg="邀请验证成功")
+    
+    # 使用序列化器添加国际化字段
+    serializer = WorkspaceInviteSerializer()
+    result_i18n = serializer.serialize(result, language)
+    
+    return success(data=result_i18n, msg=t("workspace.invites.validated"))
 
 
 @router.delete("/invites/{invite_id}", response_model=ApiResponse)
@@ -254,6 +327,8 @@ def revoke_workspace_invite(
     invite_id: uuid.UUID,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
+    language: str = Depends(get_current_language),
+    t: callable = Depends(get_translator)
 ):
     """撤销工作空间邀请"""
     workspace_id = current_user.current_workspace_id
@@ -266,7 +341,12 @@ def revoke_workspace_invite(
         user=current_user
     )
     api_logger.info(f"工作空间邀请撤销成功 - 邀请: {invite_id}")
-    return success(data=result, msg="邀请撤销成功")
+    
+    # 使用序列化器添加国际化字段
+    serializer = WorkspaceInviteSerializer()
+    result_i18n = serializer.serialize(result, language)
+    
+    return success(data=result_i18n, msg=t("workspace.invites.revoked"))
 
 # ==================== 公开邀请接口（无需认证） ====================
 
@@ -289,6 +369,7 @@ def switch_workspace(
     workspace_id: uuid.UUID,
     db: Session = Depends(get_db),
     current_user: User = Depends(get_current_user),
+    t: callable = Depends(get_translator)
 ):
     """切换工作空间"""
     api_logger.info(f"用户 {current_user.username} 请求切换工作空间为 {workspace_id}")
@@ -299,7 +380,7 @@ def switch_workspace(
         user=current_user,
     )
     api_logger.info(f"成功切换工作空间为 {workspace_id}")
-    return success(msg="工作空间切换成功")
+    return success(msg=t("workspace.switched"))
 
 
 @router.get("/storage", response_model=ApiResponse)
@@ -307,6 +388,7 @@ def switch_workspace(
 def get_workspace_storage_type(
         db: Session = Depends(get_db),
         current_user: User = Depends(get_current_user),
+        t: callable = Depends(get_translator)
 ):
     """获取当前工作空间的存储类型"""
     workspace_id = current_user.current_workspace_id
@@ -318,7 +400,7 @@ def get_workspace_storage_type(
         user=current_user
     )
     api_logger.info(f"成功获取工作空间 {workspace_id} 的存储类型: {storage_type}")
-    return success(data={"storage_type": storage_type}, msg="存储类型获取成功")
+    return success(data={"storage_type": storage_type}, msg=t("workspace.storage.type_retrieved"))
 
 
 @router.get("/workspace_models", response_model=ApiResponse)
@@ -326,6 +408,8 @@ def get_workspace_storage_type(
 def workspace_models_configs(
         db: Session = Depends(get_db),
         current_user: User = Depends(get_current_user),
+        language: str = Depends(get_current_language),
+        t: callable = Depends(get_translator)
 ):
     """获取当前工作空间的模型配置（llm, embedding, rerank）"""
     workspace_id = current_user.current_workspace_id
@@ -341,14 +425,14 @@ def workspace_models_configs(
         api_logger.warning(f"工作空间 {workspace_id} 不存在或无权访问")
         raise HTTPException(
             status_code=status.HTTP_404_NOT_FOUND,
-            detail="工作空间不存在或无权访问"
+            detail=t("workspace.not_found")
         )
 
     api_logger.info(
         f"成功获取工作空间 {workspace_id} 的模型配置: "
         f"llm={configs.get('llm')}, embedding={configs.get('embedding')}, rerank={configs.get('rerank')}"
     )
-    return success(data=WorkspaceModelsConfig.model_validate(configs), msg="模型配置获取成功")
+    return success(data=WorkspaceModelsConfig.model_validate(configs), msg=t("workspace.models.config_retrieved"))
 
 
 @router.put("/workspace_models", response_model=ApiResponse)
@@ -357,6 +441,7 @@ def update_workspace_models_configs(
         models_update: WorkspaceModelsUpdate,
         db: Session = Depends(get_db),
         current_user: User = Depends(get_current_user),
+        t: callable = Depends(get_translator)
 ):
     """更新当前工作空间的模型配置（llm, embedding, rerank）"""
     workspace_id = current_user.current_workspace_id
@@ -373,5 +458,5 @@ def update_workspace_models_configs(
         f"成功更新工作空间 {workspace_id} 的模型配置: "
         f"llm={updated_workspace.llm}, embedding={updated_workspace.embedding}, rerank={updated_workspace.rerank}"
     )
-    return success(data=WorkspaceModelsConfig.model_validate(updated_workspace), msg="模型配置更新成功")
+    return success(data=WorkspaceModelsConfig.model_validate(updated_workspace), msg=t("workspace.models.config_updated"))
 

api/app/core/agent/langchain_agent.py

@@ -11,35 +11,38 @@ LangChain Agent 封装
 import time
 from typing import Any, AsyncGenerator, Dict, List, Optional, Sequence
 
-from app.core.memory.agent.langgraph_graph.write_graph import  write_long_term
-from app.db import get_db
+from langchain.agents import create_agent
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage
+from langchain_core.tools import BaseTool
+from langgraph.errors import GraphRecursionError
+
 from app.core.logging_config import get_business_logger
 from app.core.models import RedBearLLM, RedBearModelConfig
 from app.models.models_model import ModelType
-from app.services.memory_agent_service import (
-    get_end_user_connected_config,
-)
-from langchain.agents import create_agent
-from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, SystemMessage
-from langchain_core.tools import BaseTool
+
 logger = get_business_logger()
 
 
 class LangChainAgent:
 
     def __init__(
-        self,
-        model_name: str,
-        api_key: str,
-        provider: str = "openai",
-        api_base: Optional[str] = None,
-        temperature: float = 0.7,
-        max_tokens: int = 2000,
-        system_prompt: Optional[str] = None,
-        tools: Optional[Sequence[BaseTool]] = None,
-        streaming: bool = False,
-        max_iterations: Optional[int] = None,  # 最大迭代次数（None 表示自动计算）
-        max_tool_consecutive_calls: int = 3  # 单个工具最大连续调用次数
+            self,
+            model_name: str,
+            api_key: str,
+            provider: str = "openai",
+            api_base: Optional[str] = None,
+            is_omni: bool = False,
+            temperature: float = 0.7,
+            max_tokens: int = 2000,
+            system_prompt: Optional[str] = None,
+            tools: Optional[Sequence[BaseTool]] = None,
+            streaming: bool = False,
+            max_iterations: Optional[int] = None,  # 最大迭代次数（None 表示自动计算）
+            max_tool_consecutive_calls: int = 3,  # 单个工具最大连续调用次数
+            deep_thinking: bool = False,  # 是否启用深度思考模式
+            thinking_budget_tokens: Optional[int] = None,  # 深度思考 token 预算
+            json_output: bool = False,  # 是否强制 JSON 输出
+            capability: Optional[List[str]] = None  # 模型能力列表，用于校验是否支持深度思考
     ):
         """初始化 LangChain Agent
 
@@ -60,12 +63,13 @@ class LangChainAgent:
         self.provider = provider
         self.tools = tools or []
         self.streaming = streaming
+        self.is_omni = is_omni
         self.max_tool_consecutive_calls = max_tool_consecutive_calls
-        
+
         # 工具调用计数器：记录每个工具的连续调用次数
         self.tool_call_counter: Dict[str, int] = {}
         self.last_tool_called: Optional[str] = None
-        
+
         # 根据工具数量动态调整最大迭代次数
         # 基础值 + 每个工具额外的调用机会
         if max_iterations is None:
@@ -73,9 +77,20 @@ class LangChainAgent:
             self.max_iterations = 5 + len(self.tools) * 2
         else:
             self.max_iterations = max_iterations
-        
+
         self.system_prompt = system_prompt or "你是一个专业的AI助手"
-        
+
+        # ChatTongyi 要求 messages 含 'json' 字样才能使用 response_format
+        # 在 system prompt 中注入 JSON 要求
+        from app.models.models_model import ModelProvider
+        if json_output and (
+            (provider.lower() == ModelProvider.DASHSCOPE and not is_omni)
+            or provider.lower() == ModelProvider.VOLCANO
+            # 有工具时 response_format 会被移除，所有 provider 都需要 system prompt 注入保证 JSON 输出
+            or bool(tools)
+        ):
+            self.system_prompt += "\n请以JSON格式输出。"
+
         logger.debug(
             f"Agent 迭代次数配置: max_iterations={self.max_iterations}, "
             f"tool_count={len(self.tools)}, "
@@ -83,20 +98,28 @@ class LangChainAgent:
             f"auto_calculated={max_iterations is None}"
         )
 
-        # 创建 RedBearLLM（支持多提供商）
+        # 创建 RedBearLLM，capability 校验由 RedBearModelConfig 统一处理
         model_config = RedBearModelConfig(
             model_name=model_name,
             provider=provider,
             api_key=api_key,
             base_url=api_base,
+            is_omni=is_omni,
+            capability=capability,
+            deep_thinking=deep_thinking,
+            thinking_budget_tokens=thinking_budget_tokens,
+            json_output=json_output,
             extra_params={
                 "temperature": temperature,
                 "max_tokens": max_tokens,
-                "streaming": streaming  # 使用参数控制流式
+                "streaming": streaming
             }
         )
 
         self.llm = RedBearLLM(model_config, type=ModelType.CHAT)
+        # 从经过校验的 config 读取实际生效的能力开关
+        self.deep_thinking = model_config.deep_thinking
+        self.json_output = model_config.json_output
 
         # 获取底层模型用于真正的流式调用
         self._underlying_llm = self.llm._model if hasattr(self.llm, '_model') else self.llm
@@ -143,21 +166,22 @@ class LangChainAgent:
         """
         from langchain_core.tools import StructuredTool
         from functools import wraps
-        
+
         wrapped_tools = []
-        
+
         for original_tool in tools:
             tool_name = original_tool.name
             original_func = original_tool.func if hasattr(original_tool, 'func') else None
-            
+
             if not original_func:
                 # 如果无法获取原始函数，直接使用原工具
                 wrapped_tools.append(original_tool)
                 continue
-            
+
             # 创建包装函数
             def make_wrapped_func(tool_name, original_func):
                 """创建包装函数的工厂函数，避免闭包问题"""
+
                 @wraps(original_func)
                 def wrapped_func(*args, **kwargs):
                     """包装后的工具函数，跟踪连续调用次数"""
@@ -168,13 +192,13 @@ class LangChainAgent:
                         # 切换到新工具，重置计数器
                         self.tool_call_counter[tool_name] = 1
                         self.last_tool_called = tool_name
-                    
+
                     current_count = self.tool_call_counter[tool_name]
-                    
+
                     logger.debug(
                         f"工具调用: {tool_name}, 连续调用次数: {current_count}/{self.max_tool_consecutive_calls}"
                     )
-                    
+
                     # 检查是否超过最大连续调用次数
                     if current_count > self.max_tool_consecutive_calls:
                         logger.warning(
@@ -185,12 +209,12 @@ class LangChainAgent:
                             f"工具 '{tool_name}' 已连续调用 {self.max_tool_consecutive_calls} 次，"
                             f"未找到有效结果。请尝试其他方法或直接回答用户的问题。"
                         )
-                    
+
                     # 调用原始工具函数
                     return original_func(*args, **kwargs)
-                
+
                 return wrapped_func
-            
+
             # 使用 StructuredTool 创建新工具
             wrapped_tool = StructuredTool(
                 name=original_tool.name,
@@ -198,17 +222,17 @@ class LangChainAgent:
                 func=make_wrapped_func(tool_name, original_func),
                 args_schema=original_tool.args_schema if hasattr(original_tool, 'args_schema') else None
             )
-            
+
             wrapped_tools.append(wrapped_tool)
-        
+
         return wrapped_tools
 
     def _prepare_messages(
-        self,
-        message: str,
-        history: Optional[List[Dict[str, str]]] = None,
-        context: Optional[str] = None,
-        files: Optional[List[Dict[str, Any]]] = None
+            self,
+            message: str,
+            history: Optional[List[Dict[str, str]]] = None,
+            context: Optional[str] = None,
+            files: Optional[List[Dict[str, Any]]] = None
     ) -> List[BaseMessage]:
         """准备消息列表
 
@@ -221,10 +245,7 @@ class LangChainAgent:
         Returns:
             List[BaseMessage]: 消息列表
         """
-        messages = []
-
-        # 添加系统提示词
-        messages.append(SystemMessage(content=self.system_prompt))
+        messages: list = []
 
         # 添加历史消息
         if history:
@@ -248,7 +269,34 @@ class LangChainAgent:
             messages.append(HumanMessage(content=user_content))
 
         return messages
-    
+
+    @staticmethod
+    def _extract_tokens_from_message(msg) -> int:
+        """从 AIMessage 或类似对象中提取 total_tokens，兼容多种 provider 格式
+
+        支持的格式：
+        - response_metadata.token_usage.total_tokens (OpenAI/ChatOpenAI)
+        - response_metadata.usage.total_tokens (部分 provider)
+        - usage_metadata.total_tokens (LangChain 新版)
+        """
+        total = 0
+        # 1. response_metadata
+        response_meta = getattr(msg, "response_metadata", None)
+        if response_meta and isinstance(response_meta, dict):
+            # 尝试 token_usage 路径
+            token_usage = response_meta.get("token_usage") or response_meta.get("usage", {})
+            if isinstance(token_usage, dict):
+                total = token_usage.get("total_tokens", 0)
+        # 2. usage_metadata（LangChain 新版 AIMessage 属性）
+        if not total:
+            usage_meta = getattr(msg, "usage_metadata", None)
+            if usage_meta:
+                if isinstance(usage_meta, dict):
+                    total = usage_meta.get("total_tokens", 0)
+                else:
+                    total = getattr(usage_meta, "total_tokens", 0)
+        return total or 0
+
     def _build_multimodal_content(self, text: str, files: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
         """
         构建多模态消息内容
@@ -261,36 +309,45 @@ class LangChainAgent:
             List[Dict]: 消息内容列表
         """
         # 根据 provider 使用不同的文本格式
-        if self.provider.lower() in ["bedrock", "anthropic"]:
-            # Anthropic/Bedrock: {"type": "text", "text": "..."}
-            content_parts = [{"type": "text", "text": text}]
-        else:
-            # 通义千问等: {"text": "..."}
-            content_parts = [{"text": text}]
-        
+        # if (self.provider.lower() in [ModelProvider.BEDROCK, ModelProvider.OPENAI, ModelProvider.XINFERENCE,
+        #                               ModelProvider.GPUSTACK] or (
+        #         self.provider.lower() == ModelProvider.DASHSCOPE and self.is_omni)):
+        #     # Anthropic/Bedrock/Xinference/Gpustack/Openai: {"type": "text", "text": "..."}
+        #     content_parts = [{"type": "text", "text": text}]
+        # else:
+        #     # 通义千问等: {"text": "..."}
+        #     content_parts = [{"type": "text", "text": text}]
+        content_parts = [{"type": "text", "text": text}]
+
         # 添加文件内容
         # MultimodalService 已经根据 provider 返回了正确格式，直接使用
         content_parts.extend(files)
-        
+
         logger.debug(
             f"构建多模态消息: provider={self.provider}, "
             f"parts={len(content_parts)}, "
             f"files={len(files)}"
         )
-        
+
         return content_parts
 
+    @staticmethod
+    def _extract_reasoning_content(msg) -> str:
+        """从 AIMessage 中提取深度思考内容（reasoning_content）
+
+        所有 provider 统一通过 additional_kwargs.reasoning_content 传递：
+        - DeepSeek-R1 / QwQ: 原生字段
+        - Volcano (Doubao-thinking): 由 VolcanoChatOpenAI 从 delta.reasoning_content 注入
+        """
+        additional = getattr(msg, "additional_kwargs", None) or {}
+        return additional.get("reasoning_content") or additional.get("reasoning", "")
+
     async def chat(
             self,
             message: str,
             history: Optional[List[Dict[str, str]]] = None,
             context: Optional[str] = None,
-            end_user_id: Optional[str] = None,
-            config_id: Optional[str] = None,  # 添加这个参数
-            storage_type: Optional[str] = None,
-            user_rag_memory_id: Optional[str] = None,
-            memory_flag: Optional[bool] = True,
-            files: Optional[List[Dict[str, Any]]] = None  # 新增：多模态文件
+            files: Optional[List[Dict[str, Any]]] = None
     ) -> Dict[str, Any]:
         """执行对话
 
@@ -298,32 +355,12 @@ class LangChainAgent:
             message: 用户消息
             history: 历史消息列表 [{"role": "user/assistant", "content": "..."}]
             context: 上下文信息（如知识库检索结果）
+            files: 多模态文件
 
         Returns:
             Dict: 包含 content 和元数据的字典
         """
-        message_chat= message
         start_time = time.time()
-        actual_config_id = config_id
-        # If config_id is None, try to get from end_user's connected config
-        if actual_config_id is None and end_user_id:
-            try:
-                from app.services.memory_agent_service import (
-                    get_end_user_connected_config,
-                )
-                db = next(get_db())
-                try:
-                    connected_config = get_end_user_connected_config(end_user_id, db)
-                    actual_config_id = connected_config.get("memory_config_id")
-                except Exception as e:
-                    logger.warning(f"Failed to get connected config for end_user {end_user_id}: {e}")
-                finally:
-                    db.close()
-            except Exception as e:
-                logger.warning(f"Failed to get db session: {e}")
-        actual_end_user_id = end_user_id if end_user_id is not None else "unknown"
-        logger.info(f'写入类型{storage_type,str(end_user_id), message, str(user_rag_memory_id)}')
-        print(f'写入类型{storage_type,str(end_user_id), message, str(user_rag_memory_id)}')
         try:
             # 准备消息列表（支持多模态）
             messages = self._prepare_messages(message, history, context, files)
@@ -347,7 +384,7 @@ class LangChainAgent:
                     {"messages": messages},
                     config={"recursion_limit": self.max_iterations}
                 )
-            except RecursionError as e:
+            except (RecursionError, GraphRecursionError) as e:
                 logger.warning(
                     f"Agent 达到最大迭代次数限制 ({self.max_iterations})，可能存在工具调用循环",
                     extra={"error": str(e)}
@@ -367,14 +404,15 @@ class LangChainAgent:
             # 获取最后的 AI 消息
             output_messages = result.get("messages", [])
             content = ""
-            
+
             logger.debug(f"输出消息数量: {len(output_messages)}")
             total_tokens = 0
+            reasoning_content = ""
             for msg in reversed(output_messages):
                 if isinstance(msg, AIMessage):
                     logger.debug(f"找到 AI 消息，content 类型: {type(msg.content)}")
                     logger.debug(f"AI 消息内容: {msg.content}")
-                    
+
                     # 处理多模态响应：content 可能是字符串或列表
                     if isinstance(msg.content, str):
                         content = msg.content
@@ -404,15 +442,13 @@ class LangChainAgent:
                     else:
                         content = str(msg.content)
                         logger.debug(f"转换为字符串: {content[:100]}...")
-                    response_meta = msg.response_metadata if hasattr(msg, 'response_metadata') else None
-                    total_tokens = response_meta.get("token_usage", {}).get("total_tokens", 0) if response_meta else 0
+                    total_tokens = self._extract_tokens_from_message(msg)
+                    reasoning_content = self._extract_reasoning_content(msg) if self.deep_thinking else ""
                     break
-            
+
             logger.info(f"最终提取的内容长度: {len(content)}")
 
             elapsed_time = time.time() - start_time
-            if memory_flag:
-                await write_long_term(storage_type, end_user_id, message_chat, content, user_rag_memory_id, actual_config_id)
             response = {
                 "content": content,
                 "model": self.model_name,
@@ -423,6 +459,8 @@ class LangChainAgent:
                     "total_tokens": total_tokens
                 }
             }
+            if reasoning_content:
+                response["reasoning_content"] = reasoning_content
 
             logger.debug(
                 "Agent 调用完成",
@@ -439,26 +477,24 @@ class LangChainAgent:
             raise
 
     async def chat_stream(
-        self,
-        message: str,
-        history: Optional[List[Dict[str, str]]] = None,
-        context: Optional[str] = None,
-        end_user_id:Optional[str] = None,
-        config_id: Optional[str] = None,
-        storage_type:Optional[str] = None,
-        user_rag_memory_id:Optional[str] = None,
-        memory_flag: Optional[bool] = True,
-        files: Optional[List[Dict[str, Any]]] = None  # 新增：多模态文件
-    ) -> AsyncGenerator[str, None]:
+            self,
+            message: str,
+            history: Optional[List[Dict[str, str]]] = None,
+            context: Optional[str] = None,
+            files: Optional[List[Dict[str, Any]]] = None
+    ) -> AsyncGenerator[str | int | dict[str, str], None]:
         """执行流式对话
 
         Args:
             message: 用户消息
             history: 历史消息列表
             context: 上下文信息
+            files: 多模态文件
 
         Yields:
             str: 消息内容块
+            int: token 统计
+            Dict: 深度思考内容 {"type": "reasoning", "content": "..."}
         """
         logger.info("=" * 80)
         logger.info(" chat_stream 方法开始执行")
@@ -466,24 +502,6 @@ class LangChainAgent:
         logger.info(f"  Has tools: {bool(self.tools)}")
         logger.info(f"  Tool count: {len(self.tools) if self.tools else 0}")
         logger.info("=" * 80)
-        message_chat = message
-        actual_config_id = config_id
-        # If config_id is None, try to get from end_user's connected config
-        if actual_config_id is None and end_user_id:
-            try:
-                db = next(get_db())
-                try:
-                    connected_config = get_end_user_connected_config(end_user_id, db)
-                    actual_config_id = connected_config.get("memory_config_id")
-                except Exception as e:
-                    logger.warning(f"Failed to get connected config for end_user {end_user_id}: {e}")
-                finally:
-                    db.close()
-            except Exception as e:
-                logger.warning(f"Failed to get db session: {e}")
-
-
-            # 注意：不在这里写入用户消息，等 AI 回复后一起写入
         try:
             # 准备消息列表（支持多模态）
             messages = self._prepare_messages(message, history, context, files)
@@ -493,31 +511,39 @@ class LangChainAgent:
             )
 
             chunk_count = 0
-            yielded_content = False
 
             # 统一使用 agent 的 astream_events 实现流式输出
             logger.debug("使用 Agent astream_events 实现流式输出")
             full_content = ''
+            full_reasoning = ''
             try:
+                last_event = {}
                 async for event in self.agent.astream_events(
-                    {"messages": messages},
-                    version="v2",
-                    config={"recursion_limit": self.max_iterations}
+                        {"messages": messages},
+                        version="v2",
+                        config={"recursion_limit": self.max_iterations}
                 ):
+                    last_event = event
                     chunk_count += 1
                     kind = event.get("event")
-                    
+
                     # 处理所有可能的流式事件
                     if kind == "on_chat_model_stream":
                         # LLM 流式输出
                         chunk = event.get("data", {}).get("chunk")
                         if chunk and hasattr(chunk, "content"):
+                            # 提取深度思考内容（仅在启用深度思考时）
+                            if self.deep_thinking:
+                                reasoning_chunk = self._extract_reasoning_content(chunk)
+                                if reasoning_chunk:
+                                    full_reasoning += reasoning_chunk
+                                    yield {"type": "reasoning", "content": reasoning_chunk}
+
                             # 处理多模态响应：content 可能是字符串或列表
                             chunk_content = chunk.content
                             if isinstance(chunk_content, str) and chunk_content:
                                 full_content += chunk_content
                                 yield chunk_content
-                                yielded_content = True
                             elif isinstance(chunk_content, list):
                                 # 多模态响应：提取文本部分
                                 for item in chunk_content:
@@ -528,29 +554,32 @@ class LangChainAgent:
                                             if text:
                                                 full_content += text
                                                 yield text
-                                                yielded_content = True
                                         # OpenAI 格式: {"type": "text", "text": "..."}
                                         elif item.get("type") == "text":
                                             text = item.get("text", "")
                                             if text:
                                                 full_content += text
                                                 yield text
-                                                yielded_content = True
                                     elif isinstance(item, str):
                                         full_content += item
                                         yield item
-                                        yielded_content = True
-                    
+
                     elif kind == "on_llm_stream":
                         # 另一种 LLM 流式事件
                         chunk = event.get("data", {}).get("chunk")
                         if chunk:
                             if hasattr(chunk, "content"):
+                                # 提取深度思考内容（仅在启用深度思考时）
+                                if self.deep_thinking:
+                                    reasoning_chunk = self._extract_reasoning_content(chunk)
+                                    if reasoning_chunk:
+                                        full_reasoning += reasoning_chunk
+                                        yield {"type": "reasoning", "content": reasoning_chunk}
+
                                 chunk_content = chunk.content
                                 if isinstance(chunk_content, str) and chunk_content:
                                     full_content += chunk_content
                                     yield chunk_content
-                                    yielded_content = True
                                 elif isinstance(chunk_content, list):
                                     # 多模态响应：提取文本部分
                                     for item in chunk_content:
@@ -561,41 +590,41 @@ class LangChainAgent:
                                                 if text:
                                                     full_content += text
                                                     yield text
-                                                    yielded_content = True
                                             # OpenAI 格式: {"type": "text", "text": "..."}
                                             elif item.get("type") == "text":
                                                 text = item.get("text", "")
                                                 if text:
                                                     full_content += text
                                                     yield text
-                                                    yielded_content = True
                                         elif isinstance(item, str):
                                             full_content += item
                                             yield item
-                                            yielded_content = True
                             elif isinstance(chunk, str):
                                 full_content += chunk
                                 yield chunk
-                                yielded_content = True
-                    
+
                     # 记录工具调用（可选）
                     elif kind == "on_tool_start":
                         logger.debug(f"工具调用开始: {event.get('name')}")
                     elif kind == "on_tool_end":
                         logger.debug(f"工具调用结束: {event.get('name')}")
-                
+
                 logger.debug(f"Agent 流式完成，共 {chunk_count} 个事件")
                 # 统计token消耗
-                output_messages = event.get("data", {}).get("output", {}).get("messages", [])
+                output_messages = last_event.get("data", {}).get("output", {}).get("messages", [])
                 for msg in reversed(output_messages):
                     if isinstance(msg, AIMessage):
-                        response_meta = msg.response_metadata if hasattr(msg, 'response_metadata') else None
-                        total_tokens = response_meta.get("token_usage", {}).get("total_tokens",
-                                                                                0) if response_meta else 0
-                        yield total_tokens
+                        stream_total_tokens = self._extract_tokens_from_message(msg)
+                        logger.info(f"流式 token 统计: total_tokens={stream_total_tokens}")
+                        yield stream_total_tokens
                         break
-                if memory_flag:
-                    await write_long_term(storage_type, end_user_id, message_chat, full_content, user_rag_memory_id, actual_config_id)
+
+            except GraphRecursionError:
+                logger.warning(
+                    f"Agent 达到最大迭代次数限制 ({self.max_iterations})，模型可能不支持正确的工具调用停止判断"
+                )
+                if not full_content:
+                    yield "抱歉，我在处理您的请求时遇到了问题（已达最大处理步骤限制）。请尝试简化问题或更换模型后重试。"
             except Exception as e:
                 logger.error(f"Agent astream_events 失败: {str(e)}", exc_info=True)
                 raise
@@ -609,5 +638,3 @@ class LangChainAgent:
             logger.info("=" * 80)
             logger.info("chat_stream 方法执行结束")
             logger.info("=" * 80)
-
-

api/app/core/api_key_auth.py

@@ -70,6 +70,8 @@ def require_api_key(
                 })
                 raise BusinessException("API Key 无效或已过期", BizCode.API_KEY_INVALID)
 
+            ApiKeyAuthService.check_app_published(db, api_key_obj)
+
             if scopes:
                 missing_scopes = []
                 for scope in scopes:
@@ -97,7 +99,7 @@ def require_api_key(
             )
 
             rate_limiter = RateLimiterService()
-            is_allowed, error_msg, rate_headers = await rate_limiter.check_all_limits(api_key_obj)
+            is_allowed, error_msg, rate_headers = await rate_limiter.check_all_limits(api_key_obj, db=db)
             if not is_allowed:
                 logger.warning("API Key 限流触发", extra={
                     "api_key_id": str(api_key_obj.id),
@@ -106,10 +108,12 @@ def require_api_key(
                     "error_msg": error_msg
                 })
                 # 根据错误消息判断限流类型
-                if "QPS" in error_msg:
-                    code = BizCode.API_KEY_QPS_LIMIT_EXCEEDED
-                elif "Daily" in error_msg:
+                if "Daily" in error_msg:
                     code = BizCode.API_KEY_DAILY_LIMIT_EXCEEDED
+                elif "Tenant" in error_msg:
+                    code = BizCode.API_KEY_QPS_LIMIT_EXCEEDED  # 租户套餐速率超限，同属 QPS 类
+                elif "QPS" in error_msg:
+                    code = BizCode.API_KEY_QPS_LIMIT_EXCEEDED
                 else:
                     code = BizCode.API_KEY_QUOTA_EXCEEDED
 

api/app/core/api_key_utils.py

@@ -1,8 +1,15 @@
 """API Key 工具函数"""
 import secrets
+import uuid as _uuid
 from typing import Optional, Union
 from datetime import datetime
 
+from sqlalchemy.orm import Session as _Session
+from app.core.error_codes import BizCode as _BizCode
+from app.core.exceptions import BusinessException as _BusinessException
+from app.models.end_user_model import EndUser as _EndUser
+from app.repositories.end_user_repository import EndUserRepository as _EndUserRepository
+
 from app.models.api_key_model import ApiKeyType
 from fastapi import Response
 from fastapi.responses import JSONResponse
@@ -65,3 +72,72 @@ def datetime_to_timestamp(dt: Optional[datetime]) -> Optional[int]:
         return None
 
     return int(dt.timestamp() * 1000)
+
+
+def get_current_user_from_api_key(db: _Session, api_key_auth):
+    """通过 API Key 构造 current_user 对象。
+
+    从 API Key 反查创建者（管理员用户），并设置其 workspace 上下文。
+    与内部接口的 Depends(get_current_user) (JWT) 等价。
+
+    Args:
+        db: 数据库会话
+        api_key_auth: API Key 认证信息（ApiKeyAuth）
+
+    Returns:
+        User ORM 对象，已设置 current_workspace_id
+    """
+    from app.services import api_key_service
+
+    api_key = api_key_service.ApiKeyService.get_api_key(
+        db, api_key_auth.api_key_id, api_key_auth.workspace_id
+    )
+    current_user = api_key.creator
+    current_user.current_workspace_id = api_key_auth.workspace_id
+    return current_user
+
+
+def validate_end_user_in_workspace(
+    db: _Session,
+    end_user_id: str,
+    workspace_id,
+) -> _EndUser:
+    """校验 end_user 是否存在且属于指定 workspace。
+
+    Args:
+        db: 数据库会话
+        end_user_id: 终端用户 ID
+        workspace_id: 工作空间 ID（UUID 或字符串均可）
+
+    Returns:
+        EndUser ORM 对象（校验通过时）
+
+    Raises:
+        BusinessException(INVALID_PARAMETER): end_user_id 格式无效
+        BusinessException(USER_NOT_FOUND): end_user 不存在
+        BusinessException(PERMISSION_DENIED): end_user 不属于该 workspace
+    """
+    try:
+        _uuid.UUID(end_user_id)
+    except (ValueError, AttributeError):
+        raise _BusinessException(
+            f"Invalid end_user_id format: {end_user_id}",
+            _BizCode.INVALID_PARAMETER,
+        )
+
+    end_user_repo = _EndUserRepository(db)
+    end_user = end_user_repo.get_end_user_by_id(end_user_id)
+
+    if end_user is None:
+        raise _BusinessException(
+            "End user not found",
+            _BizCode.USER_NOT_FOUND,
+        )
+
+    if str(end_user.workspace_id) != str(workspace_id):
+        raise _BusinessException(
+            "End user does not belong to this workspace",
+            _BizCode.PERMISSION_DENIED,
+        )
+
+    return end_user

api/app/core/config.py

@@ -1,9 +1,9 @@
-import json
 import os
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Annotated, Optional
 
 from dotenv import load_dotenv
+from pydantic import Field, TypeAdapter
 
 load_dotenv()
 
@@ -16,18 +16,18 @@ class Settings:
     # cloud: SaaS 云服务版（全功能，按量计费）
     # enterprise: 企业私有化版（License 控制）
     DEPLOYMENT_MODE: str = os.getenv("DEPLOYMENT_MODE", "community")
-    
+
     # License 配置（企业版）
     LICENSE_FILE: str = os.getenv("LICENSE_FILE", "/etc/app/license.json")
     LICENSE_SERVER_URL: str = os.getenv("LICENSE_SERVER_URL", "https://license.yourcompany.com")
-    
+
     # 计费服务配置（SaaS 版）
     BILLING_SERVICE_URL: str = os.getenv("BILLING_SERVICE_URL", "")
-    
+
     # 基础 URL（用于 SSO 回调等）
     BASE_URL: str = os.getenv("BASE_URL", "http://localhost:8000")
     FRONTEND_URL: str = os.getenv("FRONTEND_URL", "http://localhost:3000")
-    
+
     ENABLE_SINGLE_WORKSPACE: bool = os.getenv("ENABLE_SINGLE_WORKSPACE", "true").lower() == "true"
     # API Keys Configuration
     OPENAI_API_KEY: str = os.getenv("OPENAI_API_KEY", "")
@@ -57,7 +57,6 @@ class Settings:
     REDIS_PORT: int = int(os.getenv("REDIS_PORT", "6379"))
     REDIS_DB: int = int(os.getenv("REDIS_DB", "1"))
     REDIS_PASSWORD: str = os.getenv("REDIS_PASSWORD", "")
-    
 
     # ElasticSearch configuration
     ELASTICSEARCH_HOST: str = os.getenv("ELASTICSEARCH_HOST", "https://127.0.0.1")
@@ -91,13 +90,15 @@ class Settings:
 
     # Single Sign-On configuration
     ENABLE_SINGLE_SESSION: bool = os.getenv("ENABLE_SINGLE_SESSION", "false").lower() == "true"
-    
+
     # SSO 免登配置
     SSO_TOKEN_EXPIRE_SECONDS: int = int(os.getenv("SSO_TOKEN_EXPIRE_SECONDS", "300"))
     SSO_TRUSTED_SOURCES_CONFIG: str = os.getenv("SSO_TRUSTED_SOURCES_CONFIG", "{}")
 
     # File Upload
     MAX_FILE_SIZE: int = int(os.getenv("MAX_FILE_SIZE", "52428800"))
+    MAX_FILE_COUNT: int = int(os.getenv("MAX_FILE_COUNT", "20"))
+    MAX_CHUNK_BATCH_SIZE: int = int(os.getenv("MAX_CHUNK_BATCH_SIZE", "8"))
     FILE_PATH: str = os.getenv("FILE_PATH", "/files")
     FILE_URL_EXPIRES: int = int(os.getenv("FILE_URL_EXPIRES", "3600"))
 
@@ -115,6 +116,7 @@ class Settings:
     S3_ACCESS_KEY_ID: str = os.getenv("S3_ACCESS_KEY_ID", "")
     S3_SECRET_ACCESS_KEY: str = os.getenv("S3_SECRET_ACCESS_KEY", "")
     S3_BUCKET_NAME: str = os.getenv("S3_BUCKET_NAME", "")
+    S3_ENDPOINT_URL: str = os.getenv("S3_ENDPOINT_URL", "")
 
     # VOLC ASR settings
     VOLC_APP_KEY: str = os.getenv("VOLC_APP_KEY", "")
@@ -130,7 +132,7 @@ class Settings:
 
     # Server Configuration
     SERVER_IP: str = os.getenv("SERVER_IP", "127.0.0.1")
-    FILE_LOCAL_SERVER_URL : str = os.getenv("FILE_LOCAL_SERVER_URL", "http://localhost:8000/api")
+    FILE_LOCAL_SERVER_URL: str = os.getenv("FILE_LOCAL_SERVER_URL", "http://localhost:8000/api")
 
     # ========================================================================
     # Internal Configuration (not in .env, used by application code)
@@ -162,6 +164,44 @@ class Settings:
     # This controls the language used for memory summary titles and other generated content
     DEFAULT_LANGUAGE: str = os.getenv("DEFAULT_LANGUAGE", "zh")
 
+    # ========================================================================
+    # Internationalization (i18n) Configuration
+    # ========================================================================
+    # Default language for API responses
+    I18N_DEFAULT_LANGUAGE: str = os.getenv("I18N_DEFAULT_LANGUAGE", "zh")
+    
+    # Supported languages (comma-separated)
+    I18N_SUPPORTED_LANGUAGES: list[str] = [
+        lang.strip()
+        for lang in os.getenv("I18N_SUPPORTED_LANGUAGES", "zh,en").split(",")
+        if lang.strip()
+    ]
+    
+    # Core locales directory (community edition)
+    # Use absolute path to work from any working directory
+    I18N_CORE_LOCALES_DIR: str = os.getenv(
+        "I18N_CORE_LOCALES_DIR",
+        os.path.join(os.path.dirname(os.path.dirname(__file__)), "locales")
+    )
+    
+    # Premium locales directory (enterprise edition, optional)
+    I18N_PREMIUM_LOCALES_DIR: Optional[str] = os.getenv("I18N_PREMIUM_LOCALES_DIR", None)
+    
+    # Enable translation cache
+    I18N_ENABLE_TRANSLATION_CACHE: bool = os.getenv("I18N_ENABLE_TRANSLATION_CACHE", "true").lower() == "true"
+    
+    # LRU cache size for hot translations
+    I18N_LRU_CACHE_SIZE: int = int(os.getenv("I18N_LRU_CACHE_SIZE", "1000"))
+    
+    # Enable hot reload of translation files
+    I18N_ENABLE_HOT_RELOAD: bool = os.getenv("I18N_ENABLE_HOT_RELOAD", "false").lower() == "true"
+    
+    # Fallback language when translation is missing
+    I18N_FALLBACK_LANGUAGE: str = os.getenv("I18N_FALLBACK_LANGUAGE", "zh")
+    
+    # Log missing translations
+    I18N_LOG_MISSING_TRANSLATIONS: bool = os.getenv("I18N_LOG_MISSING_TRANSLATIONS", "true").lower() == "true"
+
     # Logging settings
     LOG_LEVEL: str = os.getenv("LOG_LEVEL", "INFO")
     LOG_FORMAT: str = os.getenv("LOG_FORMAT", "%(asctime)s - %(name)s - %(levelname)s - %(message)s")
@@ -190,25 +230,47 @@ class Settings:
     LOG_FILE_MAX_SIZE_MB: int = int(os.getenv("LOG_FILE_MAX_SIZE_MB", "10"))  # 10MB
 
     # Celery configuration (internal)
-    CELERY_BROKER: int = int(os.getenv("CELERY_BROKER", "1"))
-    CELERY_BACKEND: int = int(os.getenv("CELERY_BACKEND", "2"))
+    # NOTE: 变量名不以 CELERY_ 开头，避免被 Celery CLI 的前缀匹配机制劫持
+    # 详见 docs/celery-env-bug-report.md
+    # 默认使用 Redis 作为 broker 和 backend，与业务缓存隔离
+    # 如需使用 RabbitMQ，在 .env 中设置 CELERY_BROKER_URL=amqp://user:pass@host:5672/vhost
+    REDIS_DB_CELERY_BROKER: int = int(os.getenv("REDIS_DB_CELERY_BROKER", "3"))
+    REDIS_DB_CELERY_BACKEND: int = int(os.getenv("REDIS_DB_CELERY_BACKEND", "4"))
 
     # SMTP Email Configuration
     SMTP_SERVER: str = os.getenv("SMTP_SERVER", "smtp.gmail.com")
     SMTP_PORT: int = int(os.getenv("SMTP_PORT", "587"))
     SMTP_USER: str = os.getenv("SMTP_USER", "")
     SMTP_PASSWORD: str = os.getenv("SMTP_PASSWORD", "")
+    
+    SANDBOX_URL: str = os.getenv("SANDBOX_URL", "")
 
     REFLECTION_INTERVAL_SECONDS: float = float(os.getenv("REFLECTION_INTERVAL_SECONDS", "300"))
     HEALTH_CHECK_SECONDS: float = float(os.getenv("HEALTH_CHECK_SECONDS", "600"))
-    MEMORY_INCREMENT_INTERVAL_HOURS: float = float(os.getenv("MEMORY_INCREMENT_INTERVAL_HOURS", "24"))
-    DEFAULT_WORKSPACE_ID: Optional[str] = os.getenv("DEFAULT_WORKSPACE_ID", None)
     REFLECTION_INTERVAL_TIME: Optional[str] = int(os.getenv("REFLECTION_INTERVAL_TIME", 30))
 
     # Memory Cache Regeneration Configuration
     MEMORY_CACHE_REGENERATION_HOURS: int = int(os.getenv("MEMORY_CACHE_REGENERATION_HOURS", "24"))
 
+    # Celery Beat Schedule Configuration (定时任务执行频率)
+    MEMORY_INCREMENT_HOUR: int = TypeAdapter(
+        Annotated[int, Field(ge=0, le=23, description="cron hour [0, 23]")]
+    ).validate_python(int(os.getenv("MEMORY_INCREMENT_HOUR", "2")))
+    MEMORY_INCREMENT_MINUTE: int = TypeAdapter(
+        Annotated[int, Field(ge=0, le=59, description="cron minute [0, 59]")]
+    ).validate_python(int(os.getenv("MEMORY_INCREMENT_MINUTE", "0")))
+    WORKSPACE_REFLECTION_INTERVAL_SECONDS: int = TypeAdapter(
+        Annotated[int, Field(ge=1, description="reflection interval in seconds, must be >= 1")]
+    ).validate_python(int(os.getenv("WORKSPACE_REFLECTION_INTERVAL_SECONDS", "30")))
+    FORGETTING_CYCLE_INTERVAL_HOURS: int = TypeAdapter(
+        Annotated[int, Field(ge=1, description="forgetting cycle interval in hours, must be >= 1")]
+    ).validate_python(int(os.getenv("FORGETTING_CYCLE_INTERVAL_HOURS", "24")))
+    
+    IMPLICIT_EMOTIONS_UPDATE_HOUR: int = int(os.getenv("IMPLICIT_EMOTIONS_UPDATE_HOUR", "2"))
+    # implicit_emotions_update: 每天几分执行（分钟，0-59）
+    IMPLICIT_EMOTIONS_UPDATE_MINUTE: int = int(os.getenv("IMPLICIT_EMOTIONS_UPDATE_MINUTE", "0"))  
     # Memory Module Configuration (internal)
+    
     MEMORY_OUTPUT_DIR: str = os.getenv("MEMORY_OUTPUT_DIR", "logs/memory-output")
     MEMORY_CONFIG_DIR: str = os.getenv("MEMORY_CONFIG_DIR", "app/core/memory")
 
@@ -225,27 +287,28 @@ class Settings:
     LOAD_MODEL: bool = os.getenv("LOAD_MODEL", "false").lower() == "true"
 
     # workflow config
+    WORKFLOW_IMPORT_CACHE_TIMEOUT: int = int(os.getenv("WORKFLOW_IMPORT_CACHE_TIMEOUT", 1800))
     WORKFLOW_NODE_TIMEOUT: int = int(os.getenv("WORKFLOW_NODE_TIMEOUT", 600))
 
     # ========================================================================
     # General Ontology Type Configuration
     # ========================================================================
     # 通用本体文件路径列表（逗号分隔）
-    GENERAL_ONTOLOGY_FILES: str = os.getenv("GENERAL_ONTOLOGY_FILES", "General_purpose_entity.ttl")
-    
+    GENERAL_ONTOLOGY_FILES: str = os.getenv("GENERAL_ONTOLOGY_FILES", "api/app/core/memory/ontology_services/General_purpose_entity.ttl")
+
     # 是否启用通用本体类型功能
     ENABLE_GENERAL_ONTOLOGY_TYPES: bool = os.getenv("ENABLE_GENERAL_ONTOLOGY_TYPES", "true").lower() == "true"
-    
+
     # Prompt 中最大类型数量
     MAX_ONTOLOGY_TYPES_IN_PROMPT: int = int(os.getenv("MAX_ONTOLOGY_TYPES_IN_PROMPT", "50"))
-    
+
     # 核心通用类型列表（逗号分隔）
     CORE_GENERAL_TYPES: str = os.getenv(
         "CORE_GENERAL_TYPES",
         "Person,Organization,Company,GovernmentAgency,Place,Location,City,Country,Building,"
         "Event,SportsEvent,SocialEvent,Work,Book,Film,Software,Concept,TopicalConcept,AcademicSubject"
     )
-    
+
     # 实验模式开关（允许通过 API 动态切换本体配置）
     ONTOLOGY_EXPERIMENT_MODE: bool = os.getenv("ONTOLOGY_EXPERIMENT_MODE", "true").lower() == "true"
 

api/app/core/error_codes.py

@@ -19,6 +19,7 @@ class BizCode(IntEnum):
     TENANT_NOT_FOUND = 3002
     WORKSPACE_NO_ACCESS = 3003
     WORKSPACE_INVITE_NOT_FOUND = 3004
+    WORKSPACE_ACCESS_DENIED = 3005
     # API Key 管理（3xxx）
     API_KEY_NOT_FOUND = 3007
     API_KEY_DUPLICATE_NAME = 3008
@@ -30,6 +31,9 @@ class BizCode(IntEnum):
     API_KEY_QPS_LIMIT_EXCEEDED = 3014
     API_KEY_DAILY_LIMIT_EXCEEDED = 3015
     API_KEY_QUOTA_EXCEEDED = 3016
+    API_KEY_RATE_LIMIT_EXCEEDED = 3017
+    QUOTA_EXCEEDED = 3018
+    RATE_LIMIT_EXCEEDED = 3019
     # 资源（4xxx）
     NOT_FOUND = 4000
     USER_NOT_FOUND = 4001
@@ -40,6 +44,7 @@ class BizCode(IntEnum):
     FILE_NOT_FOUND = 4006
     APP_NOT_FOUND = 4007
     RELEASE_NOT_FOUND = 4008
+    USER_NO_ACCESS = 4009
 
     # 冲突/状态（5xxx）
     DUPLICATE_NAME = 5001
@@ -61,6 +66,7 @@ class BizCode(IntEnum):
     PERMISSION_DENIED = 6010
     INVALID_CONVERSATION = 6011
     CONFIG_MISSING = 6012
+    APP_NOT_PUBLISHED = 6013
 
     # 模型（7xxx）
     MODEL_CONFIG_INVALID = 7001
@@ -113,8 +119,11 @@ HTTP_MAPPING = {
     BizCode.FORBIDDEN: 403,
     BizCode.TENANT_NOT_FOUND: 400,
     BizCode.WORKSPACE_NO_ACCESS: 403,
+    BizCode.WORKSPACE_INVITE_NOT_FOUND: 400,
+    BizCode.WORKSPACE_ACCESS_DENIED: 403,
     BizCode.NOT_FOUND: 400,
     BizCode.USER_NOT_FOUND: 200,
+    BizCode.USER_NO_ACCESS: 401,
     BizCode.WORKSPACE_NOT_FOUND: 400,
     BizCode.MODEL_NOT_FOUND: 400,
     BizCode.KNOWLEDGE_NOT_FOUND: 400,
@@ -150,7 +159,8 @@ HTTP_MAPPING = {
     BizCode.API_KEY_QPS_LIMIT_EXCEEDED: 429,
     BizCode.API_KEY_DAILY_LIMIT_EXCEEDED: 429,
     BizCode.API_KEY_QUOTA_EXCEEDED: 429,
-    
+    BizCode.QUOTA_EXCEEDED: 402,
+
     BizCode.MODEL_CONFIG_INVALID: 400,
     BizCode.API_KEY_MISSING: 400,
     BizCode.PROVIDER_NOT_SUPPORTED: 400,
@@ -179,4 +189,21 @@ HTTP_MAPPING = {
     BizCode.DB_ERROR: 500,
     BizCode.SERVICE_UNAVAILABLE: 503,
     BizCode.RATE_LIMITED: 429,
+    BizCode.RATE_LIMIT_EXCEEDED: 429,
+}
+
+ERROR_CODE_TO_BIZ_CODE = {
+    "QUOTA_EXCEEDED": BizCode.QUOTA_EXCEEDED,
+    "RATE_LIMIT_EXCEEDED": BizCode.RATE_LIMIT_EXCEEDED,
+    "API_KEY_NOT_FOUND": BizCode.API_KEY_NOT_FOUND,
+    "API_KEY_INVALID": BizCode.API_KEY_INVALID,
+    "API_KEY_EXPIRED": BizCode.API_KEY_EXPIRED,
+    "WORKSPACE_NOT_FOUND": BizCode.WORKSPACE_NOT_FOUND,
+    "WORKSPACE_NO_ACCESS": BizCode.WORKSPACE_NO_ACCESS,
+    "PERMISSION_DENIED": BizCode.PERMISSION_DENIED,
+    "TOKEN_EXPIRED": BizCode.TOKEN_EXPIRED,
+    "TOKEN_INVALID": BizCode.TOKEN_INVALID,
+    "VALIDATION_FAILED": BizCode.VALIDATION_FAILED,
+    "INVALID_PARAMETER": BizCode.INVALID_PARAMETER,
+    "MISSING_PARAMETER": BizCode.MISSING_PARAMETER,
 }

api/app/core/logging_config.py

@@ -529,8 +529,9 @@ def log_time(step_name: str, duration: float, log_file: str = "logs/time.log") -
         # Fallback to console only if file write fails
         print(f"Warning: Could not write to timing log: {e}")
     
-    # Always print to console (backward compatible behavior)
-    print(f"✓ {step_name}: {duration:.2f}s")
+    # Always log at INFO level (avoids Celery treating stdout as WARNING)
+    _timing_logger = logging.getLogger(__name__)
+    _timing_logger.info(f"✓ {step_name}: {duration:.2f}s")
 
 
 def get_agent_logger(name: str = "agent_service", 

api/app/core/memory/agent/langgraph_graph/nodes/data_nodes.py

@@ -1,16 +1,45 @@
 from app.core.memory.agent.utils.llm_tools import ReadState, WriteState
+from app.schemas.memory_agent_schema import AgentMemoryDataset
 
 
 def content_input_node(state: ReadState) -> ReadState:
-    """开始节点 - 提取内容并保持状态信息"""
+    """
+    Start node - Extract content and maintain state information
+
+    Extracts the content from the first message in the state and returns it
+    as the data field while preserving all other state information.
+
+    Args:
+        state: ReadState containing messages and other state data
+
+    Returns:
+        ReadState: Updated state with extracted content in data field
+    """
 
     content = state['messages'][0].content if state.get('messages') else ''
-    # 返回内容并保持所有状态信息
+    # Return content and maintain all state information
+    for pronoun in AgentMemoryDataset.PRONOUN:
+        content = content.replace(pronoun, AgentMemoryDataset.NAME)
+
     return {"data": content}
 
+
 def content_input_write(state: WriteState) -> WriteState:
-    """开始节点 - 提取内容并保持状态信息"""
+    """
+    Start node - Extract content and maintain state information for write operations
+
+    Extracts the content from the first message in the state for write operations.
+
+    Args:
+        state: WriteState containing messages and other state data
+
+    Returns:
+        WriteState: Updated state with extracted content in data field
+    """
 
     content = state['messages'][0].content if state.get('messages') else ''
-    # 返回内容并保持所有状态信息
-    return {"data": content}
+    # Return content and maintain all state information
+    for pronoun in AgentMemoryDataset.PRONOUN:
+        content = content.replace(pronoun, AgentMemoryDataset.NAME)
+
+    return {"data": content}

api/app/core/memory/agent/langgraph_graph/nodes/perceptual_retrieve_node.py

@@ -0,0 +1,408 @@
+"""
+Perceptual Memory Retrieval Node & Service
+
+Provides PerceptualSearchService for searching perceptual memories (vision, audio,
+text, conversation) from Neo4j using keyword fulltext + embedding semantic search
+with BM25+embedding fusion reranking.
+
+Also provides the perceptual_retrieve_node for use as a LangGraph node.
+"""
+import asyncio
+import math
+from typing import List, Dict, Any, Optional
+
+from app.core.logging_config import get_agent_logger
+from app.core.memory.agent.utils.llm_tools import ReadState
+from app.core.memory.utils.data.text_utils import escape_lucene_query
+from app.repositories.neo4j.graph_search import (
+    search_perceptual_by_fulltext,
+    search_perceptual_by_embedding,
+)
+from app.repositories.neo4j.neo4j_connector import Neo4jConnector
+
+logger = get_agent_logger(__name__)
+
+
+class PerceptualSearchService:
+    """
+    感知记忆检索服务。
+
+    封装关键词全文检索 + 向量语义检索 + BM25/embedding 融合排序的完整流程。
+    调用方只需提供 query / keywords、end_user_id、memory_config，即可获得
+    格式化并排序后的感知记忆列表和拼接文本。
+
+    Usage:
+        service = PerceptualSearchService(end_user_id=..., memory_config=...)
+        results = await service.search(query="...", keywords=[...], limit=10)
+        # results = {"memories": [...], "content": "...", "keyword_raw": N, "embedding_raw": M}
+    """
+
+    DEFAULT_ALPHA = 0.6
+    DEFAULT_CONTENT_SCORE_THRESHOLD = 0.5
+
+    def __init__(
+            self,
+            end_user_id: str,
+            memory_config: Any,
+            alpha: float = DEFAULT_ALPHA,
+            content_score_threshold: float = DEFAULT_CONTENT_SCORE_THRESHOLD,
+    ):
+        self.end_user_id = end_user_id
+        self.memory_config = memory_config
+        self.alpha = alpha
+        self.content_score_threshold = content_score_threshold
+
+    async def search(
+            self,
+            query: str,
+            keywords: Optional[List[str]] = None,
+            limit: int = 10,
+    ) -> Dict[str, Any]:
+        """
+        执行感知记忆检索（关键词 + 向量并行），融合排序后返回结果。
+
+        对 embedding 命中但 keyword 未命中的结果，补查全文索引获取 BM25 分数，
+        确保所有结果都同时具备 BM25 和 embedding 两个维度的评分。
+
+        Args:
+            query: 原始用户查询（用于向量检索和 BM25 补查）
+            keywords: 关键词列表（用于全文检索），为 None 时使用 [query]
+            limit: 最大返回数量
+
+        Returns:
+            {
+                "memories": [格式化后的记忆 dict, ...],
+                "content": "拼接的纯文本摘要",
+                "keyword_raw": int,
+                "embedding_raw": int,
+            }
+        """
+        if keywords is None:
+            keywords = [query] if query else []
+
+        connector = Neo4jConnector()
+        try:
+            kw_task = self._keyword_search(connector, keywords, limit)
+            emb_task = self._embedding_search(connector, query, limit)
+
+            kw_results, emb_results = await asyncio.gather(
+                kw_task, emb_task, return_exceptions=True
+            )
+            if isinstance(kw_results, Exception):
+                logger.warning(f"[PerceptualSearch] keyword search error: {kw_results}")
+                kw_results = []
+            if isinstance(emb_results, Exception):
+                logger.warning(f"[PerceptualSearch] embedding search error: {emb_results}")
+                emb_results = []
+
+            # 补查 BM25：找出 embedding 命中但 keyword 未命中的 id，
+            # 用原始 query 对这些节点补查全文索引拿 BM25 score
+            kw_ids = {r.get("id") for r in kw_results if r.get("id")}
+            emb_only_ids = {r.get("id") for r in emb_results if r.get("id") and r.get("id") not in kw_ids}
+
+            if emb_only_ids and query:
+                backfill = await self._bm25_backfill(connector, query, emb_only_ids, limit)
+                # 把补查到的 BM25 score 注入到 embedding 结果中
+                backfill_map = {r["id"]: r.get("score", 0) for r in backfill}
+                for r in emb_results:
+                    rid = r.get("id", "")
+                    if rid in backfill_map:
+                        r["bm25_backfill_score"] = backfill_map[rid]
+                logger.info(
+                    f"[PerceptualSearch] BM25 backfill: {len(emb_only_ids)} embedding-only ids, "
+                    f"{len(backfill_map)} got BM25 scores"
+                )
+
+            reranked = self._rerank(kw_results, emb_results, limit)
+
+            memories = []
+            content_parts = []
+            for record in reranked:
+                fmt = self._format_result(record)
+                fmt["score"] = round(record.get("content_score", 0), 4)
+                memories.append(fmt)
+                content_parts.append(self._build_content_text(fmt))
+
+            logger.info(
+                f"[PerceptualSearch] {len(memories)} results after rerank "
+                f"(keyword_raw={len(kw_results)}, embedding_raw={len(emb_results)})"
+            )
+            return {
+                "memories": memories,
+                "content": "\n\n".join(content_parts),
+                "keyword_raw": len(kw_results),
+                "embedding_raw": len(emb_results),
+            }
+        finally:
+            await connector.close()
+
+    async def _bm25_backfill(
+            self,
+            connector: Neo4jConnector,
+            query: str,
+            target_ids: set,
+            limit: int,
+    ) -> List[dict]:
+        """
+        对指定 id 集合补查全文索引 BM25 score。
+
+        用原始 query 查全文索引，只保留 id 在 target_ids 中的结果。
+        """
+        escaped = escape_lucene_query(query)
+        if not escaped.strip():
+            return []
+        try:
+            r = await search_perceptual_by_fulltext(
+                connector=connector, query=escaped,
+                end_user_id=self.end_user_id,
+                limit=limit * 5,  # 多查一些以提高命中率
+            )
+            all_hits = r.get("perceptuals", [])
+            return [h for h in all_hits if h.get("id") in target_ids]
+        except Exception as e:
+            logger.warning(f"[PerceptualSearch] BM25 backfill failed: {e}")
+            return []
+
+    async def _keyword_search(
+            self,
+            connector: Neo4jConnector,
+            keywords: List[str],
+            limit: int,
+    ) -> List[dict]:
+        """并发对每个关键词做全文检索，去重后按 score 降序返回 top N 原始结果。"""
+        seen_ids: set = set()
+        all_results: List[dict] = []
+
+        async def _one(kw: str):
+            escaped = escape_lucene_query(kw)
+            if not escaped.strip():
+                return []
+            r = await search_perceptual_by_fulltext(
+                connector=connector, query=escaped,
+                end_user_id=self.end_user_id, limit=limit,
+            )
+            return r.get("perceptuals", [])
+
+        tasks = [_one(kw) for kw in keywords[:10]]
+        batch = await asyncio.gather(*tasks, return_exceptions=True)
+
+        for result in batch:
+            if isinstance(result, Exception):
+                logger.warning(f"[PerceptualSearch] keyword sub-query error: {result}")
+                continue
+            for rec in result:
+                rid = rec.get("id", "")
+                if rid and rid not in seen_ids:
+                    seen_ids.add(rid)
+                    all_results.append(rec)
+
+        all_results.sort(key=lambda x: float(x.get("score", 0)), reverse=True)
+        return all_results[:limit]
+
+    async def _embedding_search(
+            self,
+            connector: Neo4jConnector,
+            query_text: str,
+            limit: int,
+    ) -> List[dict]:
+        """向量语义检索，返回原始结果（不做阈值过滤）。"""
+        try:
+            from app.core.memory.llm_tools.openai_embedder import OpenAIEmbedderClient
+            from app.core.models.base import RedBearModelConfig
+            from app.db import get_db_context
+            from app.services.memory_config_service import MemoryConfigService
+
+            with get_db_context() as db:
+                cfg = MemoryConfigService(db).get_embedder_config(
+                    str(self.memory_config.embedding_model_id)
+                )
+            client = OpenAIEmbedderClient(RedBearModelConfig(**cfg))
+
+            r = await search_perceptual_by_embedding(
+                connector=connector, embedder_client=client,
+                query_text=query_text, end_user_id=self.end_user_id,
+                limit=limit,
+            )
+            return r.get("perceptuals", [])
+        except Exception as e:
+            logger.warning(f"[PerceptualSearch] embedding search failed: {e}")
+            return []
+
+    def _rerank(
+            self,
+            keyword_results: List[dict],
+            embedding_results: List[dict],
+            limit: int,
+    ) -> List[dict]:
+        """BM25 + embedding 融合排序。
+
+        对 embedding 结果中带有 bm25_backfill_score 的条目，
+        将其与 keyword 结果合并后统一归一化，确保 BM25 分数在同一尺度上。
+        """
+        # 把补查的 BM25 score 合并到 keyword_results 中统一归一化
+        emb_backfill_items = []
+        for item in embedding_results:
+            backfill_score = item.get("bm25_backfill_score")
+            if backfill_score is not None and item.get("id"):
+                emb_backfill_items.append({"id": item["id"], "score": backfill_score})
+
+        # 合并后统一归一化 BM25 scores
+        all_bm25_items = keyword_results + emb_backfill_items
+        all_bm25_items = self._normalize_scores(all_bm25_items)
+
+        # 建立 id -> normalized BM25 score 的映射
+        bm25_norm_map: Dict[str, float] = {}
+        for item in all_bm25_items:
+            item_id = item.get("id", "")
+            if item_id:
+                bm25_norm_map[item_id] = float(item.get("normalized_score", 0))
+
+        # 归一化 embedding scores
+        embedding_results = self._normalize_scores(embedding_results)
+
+        # 合并
+        combined: Dict[str, dict] = {}
+        for item in keyword_results:
+            item_id = item.get("id", "")
+            if not item_id:
+                continue
+            combined[item_id] = item.copy()
+            combined[item_id]["bm25_score"] = bm25_norm_map.get(item_id, 0)
+            combined[item_id]["embedding_score"] = 0.0
+
+        for item in embedding_results:
+            item_id = item.get("id", "")
+            if not item_id:
+                continue
+            if item_id in combined:
+                combined[item_id]["embedding_score"] = item.get("normalized_score", 0)
+            else:
+                combined[item_id] = item.copy()
+                combined[item_id]["bm25_score"] = bm25_norm_map.get(item_id, 0)
+                combined[item_id]["embedding_score"] = item.get("normalized_score", 0)
+
+        for item in combined.values():
+            bm25 = float(item.get("bm25_score", 0) or 0)
+            emb = float(item.get("embedding_score", 0) or 0)
+            item["content_score"] = self.alpha * bm25 + (1 - self.alpha) * emb
+
+        results = list(combined.values())
+        before = len(results)
+        results = [r for r in results if r["content_score"] >= self.content_score_threshold]
+        results.sort(key=lambda x: x["content_score"], reverse=True)
+        results = results[:limit]
+
+        logger.info(
+            f"[PerceptualSearch] rerank: merged={before}, after_threshold={len(results)} "
+            f"(alpha={self.alpha}, threshold={self.content_score_threshold})"
+        )
+        return results
+
+    @staticmethod
+    def _normalize_scores(items: List[dict], field: str = "score") -> List[dict]:
+        """Z-score + sigmoid 归一化。"""
+        if not items:
+            return items
+        scores = [float(it.get(field, 0) or 0) for it in items]
+        if len(scores) <= 1:
+            for it in items:
+                it[f"normalized_{field}"] = 1.0
+            return items
+        mean = sum(scores) / len(scores)
+        var = sum((s - mean) ** 2 for s in scores) / len(scores)
+        std = math.sqrt(var)
+        if std == 0:
+            for it in items:
+                it[f"normalized_{field}"] = 1.0
+        else:
+            for it, s in zip(items, scores):
+                z = (s - mean) / std
+                it[f"normalized_{field}"] = 1 / (1 + math.exp(-z))
+        return items
+
+    @staticmethod
+    def _format_result(record: dict) -> dict:
+        return {
+            "id": record.get("id", ""),
+            "perceptual_type": record.get("perceptual_type", ""),
+            "file_name": record.get("file_name", ""),
+            "file_path": record.get("file_path", ""),
+            "summary": record.get("summary", ""),
+            "topic": record.get("topic", ""),
+            "domain": record.get("domain", ""),
+            "keywords": record.get("keywords", []),
+            "created_at": str(record.get("created_at", "")),
+            "file_type": record.get("file_type", ""),
+            "score": record.get("score", 0),
+        }
+
+    @staticmethod
+    def _build_content_text(formatted: dict) -> str:
+        parts = []
+        if formatted["summary"]:
+            parts.append(formatted["summary"])
+        if formatted["topic"]:
+            parts.append(f"[主题: {formatted['topic']}]")
+        if formatted["keywords"]:
+            kw_list = formatted["keywords"]
+            if isinstance(kw_list, list):
+                parts.append(f"[关键词: {', '.join(kw_list)}]")
+        if formatted["file_name"]:
+            parts.append(f"[文件: {formatted['file_name']}]")
+        return " ".join(parts)
+
+
+def _extract_keywords_from_problems(problem_extension: dict) -> List[str]:
+    """Extract search keywords from problem extension results."""
+    keywords = []
+    context = problem_extension.get("context", {})
+    if isinstance(context, dict):
+        for original_q, extended_qs in context.items():
+            keywords.append(original_q)
+            if isinstance(extended_qs, list):
+                keywords.extend(extended_qs)
+    return keywords
+
+
+async def perceptual_retrieve_node(state: ReadState) -> ReadState:
+    """
+    LangGraph node: perceptual memory retrieval.
+
+    Uses PerceptualSearchService to run keyword + embedding search with
+    BM25 fusion reranking, then writes results to state['perceptual_data'].
+    """
+    end_user_id = state.get("end_user_id", "")
+    problem_extension = state.get("problem_extension", {})
+    original_query = state.get("data", "")
+    memory_config = state.get("memory_config", None)
+
+    logger.info(f"Perceptual_Retrieve: start, end_user_id={end_user_id}")
+
+    keywords = _extract_keywords_from_problems(problem_extension)
+    if not keywords:
+        keywords = [original_query] if original_query else []
+
+    logger.info(f"Perceptual_Retrieve: {len(keywords)} keywords extracted")
+
+    service = PerceptualSearchService(
+        end_user_id=end_user_id,
+        memory_config=memory_config,
+    )
+    search_result = await service.search(
+        query=original_query,
+        keywords=keywords,
+        limit=10,
+    )
+
+    result = {
+        "memories": search_result["memories"],
+        "content": search_result["content"],
+        "_intermediate": {
+            "type": "perceptual_retrieve",
+            "title": "感知记忆检索",
+            "data": search_result["memories"],
+            "query": original_query,
+            "result_count": len(search_result["memories"]),
+        },
+    }
+    return {"perceptual_data": result}

api/app/core/memory/agent/langgraph_graph/nodes/problem_nodes.py

@@ -1,10 +1,10 @@
-import os
 import json
+import os
 import time
-from app.core.logging_config import get_agent_logger
-from app.db import get_db
 
+from app.core.logging_config import get_agent_logger
 from app.core.memory.agent.models.problem_models import ProblemExtensionResponse
+from app.core.memory.agent.services.optimized_llm_service import LLMServiceMixin
 from app.core.memory.agent.utils.llm_tools import (
     PROJECT_ROOT_,
     ReadState,
@@ -12,27 +12,46 @@ from app.core.memory.agent.utils.llm_tools import (
 from app.core.memory.agent.utils.redis_tool import store
 from app.core.memory.agent.utils.session_tools import SessionService
 from app.core.memory.agent.utils.template_tools import TemplateService
-from app.core.memory.agent.services.optimized_llm_service import LLMServiceMixin
+from app.db import get_db_context
 
 template_root = os.path.join(PROJECT_ROOT_, 'memory', 'agent', 'utils', 'prompt')
-db_session = next(get_db())
 logger = get_agent_logger(__name__)
 
 
 class ProblemNodeService(LLMServiceMixin):
-    """问题处理节点服务类"""
+    """
+    Problem processing node service class
+    
+    Handles problem decomposition and extension operations using LLM services.
+    Inherits from LLMServiceMixin to provide structured LLM calling capabilities.
+    
+    Attributes:
+        template_service: Service for rendering Jinja2 templates
+    """
 
     def __init__(self):
         super().__init__()
         self.template_service = TemplateService(template_root)
 
 
-# 创建全局服务实例
+# Create global service instance
 problem_service = ProblemNodeService()
 
 
 async def Split_The_Problem(state: ReadState) -> ReadState:
-    """问题分解节点"""
+    """
+    Problem decomposition node
+    
+    Breaks down complex user queries into smaller, more manageable sub-problems.
+    Uses LLM to analyze the input and generate structured problem decomposition
+    with question types and reasoning.
+    
+    Args:
+        state: ReadState containing user input and configuration
+        
+    Returns:
+        ReadState: Updated state with problem decomposition results
+    """
     # 从状态中获取数据
     content = state.get('data', '')
     end_user_id = state.get('end_user_id', '')
@@ -53,18 +72,19 @@ async def Split_The_Problem(state: ReadState) -> ReadState:
 
     try:
         # 使用优化的LLM服务
-        structured = await problem_service.call_llm_structured(
-            state=state,
-            db_session=db_session,
-            system_prompt=system_prompt,
-            response_model=ProblemExtensionResponse,
-            fallback_value=[]
-        )
+        with get_db_context() as db_session:
+            structured = await problem_service.call_llm_structured(
+                state=state,
+                db_session=db_session,
+                system_prompt=system_prompt,
+                response_model=ProblemExtensionResponse,
+                fallback_value=[]
+            )
 
         # 添加更详细的日志记录
         logger.info(f"Split_The_Problem: 开始处理问题分解，内容长度: {len(content)}")
 
-        # 验证结构化响应
+        # Validate structured response
         if not structured or not hasattr(structured, 'root'):
             logger.warning("Split_The_Problem: 结构化响应为空或格式不正确")
             split_result = json.dumps([], ensure_ascii=False)
@@ -106,17 +126,17 @@ async def Split_The_Problem(state: ReadState) -> ReadState:
             exc_info=True
         )
 
-        # 提供更详细的错误信息
+        # Provide more detailed error information
         error_details = {
             "error_type": type(e).__name__,
             "error_message": str(e),
             "content_length": len(content),
-            "llm_model_id": memory_config.llm_model_id if memory_config else None
+            "llm_model_id": str(memory_config.llm_model_id) if memory_config else None
         }
 
         logger.error(f"Split_The_Problem error details: {error_details}")
 
-        # 创建默认的空结果
+        # Create default empty result
         result = {
             "context": json.dumps([], ensure_ascii=False),
             "original": content,
@@ -130,13 +150,25 @@ async def Split_The_Problem(state: ReadState) -> ReadState:
             }
         }
 
-    # 返回更新后的状态，包含spit_context字段
+    # Return updated state including spit_context field
     return {"spit_data": result}
 
 
 async def Problem_Extension(state: ReadState) -> ReadState:
-    """问题扩展节点"""
-    # 获取原始数据和分解结果
+    """
+    Problem extension node
+    
+    Extends the decomposed problems from Split_The_Problem node by generating
+    additional related questions and organizing them by original question.
+    Uses LLM to create comprehensive question extensions for better memory retrieval.
+    
+    Args:
+        state: ReadState containing decomposed problems and configuration
+        
+    Returns:
+        ReadState: Updated state with extended problem results
+    """
+    # Get original data and decomposition results
     start = time.time()
     content = state.get('data', '')
     data = state.get('spit_data', '')['context']
@@ -171,17 +203,18 @@ async def Problem_Extension(state: ReadState) -> ReadState:
 
     try:
         # 使用优化的LLM服务
-        response_content = await problem_service.call_llm_structured(
-            state=state,
-            db_session=db_session,
-            system_prompt=system_prompt,
-            response_model=ProblemExtensionResponse,
-            fallback_value=[]
-        )
+        with get_db_context() as db_session:
+            response_content = await problem_service.call_llm_structured(
+                state=state,
+                db_session=db_session,
+                system_prompt=system_prompt,
+                response_model=ProblemExtensionResponse,
+                fallback_value=[]
+            )
 
         logger.info(f"Problem_Extension: 开始处理问题扩展，问题数量: {len(databasets)}")
 
-        # 验证结构化响应
+        # Validate structured response
         if not response_content or not hasattr(response_content, 'root'):
             logger.warning("Problem_Extension: 结构化响应为空或格式不正确")
             aggregated_dict = {}
@@ -215,12 +248,12 @@ async def Problem_Extension(state: ReadState) -> ReadState:
             exc_info=True
         )
 
-        # 提供更详细的错误信息
+        # Provide more detailed error information
         error_details = {
             "error_type": type(e).__name__,
             "error_message": str(e),
             "questions_count": len(databasets),
-            "llm_model_id": memory_config.llm_model_id if memory_config else None
+            "llm_model_id": str(memory_config.llm_model_id) if memory_config else None
         }
 
         logger.error(f"Problem_Extension error details: {error_details}")
@@ -230,7 +263,6 @@ async def Problem_Extension(state: ReadState) -> ReadState:
     logger.info(f"Problem extension result: {aggregated_dict}")
 
     # Emit intermediate output for frontend
-    print(time.time() - start)
     result = {
         "context": aggregated_dict,
         "original": data,

api/app/core/memory/agent/langgraph_graph/nodes/retrieve_nodes.py

@@ -6,34 +6,41 @@ import os
 # ===== 第三方库 =====
 from langchain.agents import create_agent
 from langchain_openai import ChatOpenAI
+
 from app.core.logging_config import get_agent_logger
-from app.db import get_db, get_db_context
-
-from app.schemas import model_schema
-from app.services.memory_config_service import MemoryConfigService
-from app.services.model_service import ModelConfigService
-
-from app.core.memory.agent.services.search_service import SearchService
-from app.core.memory.agent.utils.llm_tools import (
-    COUNTState,
-    ReadState,
-    deduplicate_entries,
-    merge_to_key_value_pairs,
-)
 from app.core.memory.agent.langgraph_graph.tools.tool import (
     create_hybrid_retrieval_tool_sync,
     create_time_retrieval_tool,
     extract_tool_message_content,
 )
-
+from app.core.memory.agent.services.search_service import SearchService
+from app.core.memory.agent.utils.llm_tools import (
+    ReadState,
+    deduplicate_entries,
+    merge_to_key_value_pairs,
+)
 from app.core.rag.nlp.search import knowledge_retrieval
+from app.db import get_db_context
+from app.schemas import model_schema
+from app.services.memory_config_service import MemoryConfigService
+from app.services.model_service import ModelConfigService
 
 logger = get_agent_logger(__name__)
-db = next(get_db())
-
 
 
 async def rag_config(state):
+    """
+    Configure RAG (Retrieval-Augmented Generation) settings
+    
+    Creates configuration for knowledge base retrieval including similarity thresholds,
+    weights, and reranker settings.
+    
+    Args:
+        state: Current state containing user_rag_memory_id
+        
+    Returns:
+        dict: RAG configuration dictionary
+    """
     user_rag_memory_id = state.get('user_rag_memory_id', '')
     kb_config = {
         "knowledge_bases": [
@@ -50,10 +57,25 @@ async def rag_config(state):
         "reranker_top_k": 10
     }
     return kb_config
-async def rag_knowledge(state,question):
+
+
+async def rag_knowledge(state, question):
+    """
+    Retrieve knowledge using RAG approach
+    
+    Performs knowledge retrieval from configured knowledge bases using the
+    provided question and returns formatted results.
+    
+    Args:
+        state: Current state containing configuration
+        question: Question to search for
+        
+    Returns:
+        tuple: (retrieval_knowledge, clean_content, cleaned_query, raw_results)
+    """
     kb_config = await rag_config(state)
     end_user_id = state.get('end_user_id', '')
-    user_rag_memory_id=state.get("user_rag_memory_id",'')
+    user_rag_memory_id = state.get("user_rag_memory_id", '')
     retrieve_chunks_result = knowledge_retrieval(question, kb_config, [str(end_user_id)])
     try:
         retrieval_knowledge = [i.page_content for i in retrieve_chunks_result]
@@ -61,22 +83,34 @@ async def rag_knowledge(state,question):
         cleaned_query = question
         raw_results = clean_content
         logger.info(f" Using RAG storage with memory_id={user_rag_memory_id}")
-    except  Exception :
-        retrieval_knowledge=[]
+    except Exception:
+        retrieval_knowledge = []
         clean_content = ''
         raw_results = ''
         cleaned_query = question
         logger.info(f"No content retrieved from knowledge base: {user_rag_memory_id}")
-    return retrieval_knowledge,clean_content,cleaned_query,raw_results
+    return retrieval_knowledge, clean_content, cleaned_query, raw_results
 
 
 async def llm_infomation(state: ReadState) -> ReadState:
+    """
+    Get LLM configuration information from state
+    
+    Retrieves model configuration details including model ID and tenant ID
+    from the memory configuration in the current state.
+    
+    Args:
+        state: ReadState containing memory configuration
+        
+    Returns:
+        ReadState: Model configuration as Pydantic model
+    """
     memory_config = state.get('memory_config', None)
     model_id = memory_config.llm_model_id
     tenant_id = memory_config.tenant_id
 
-    # 使用现有的 memory_config 而不是重新查询数据库
-    # 或者使用线程安全的数据库访问
+    # Use existing memory_config instead of re-querying database
+    # or use thread-safe database access
     with get_db_context() as db:
         result_orm = ModelConfigService.get_model_by_id(db=db, model_id=model_id, tenant_id=tenant_id)
         result_pydantic = model_schema.ModelConfig.model_validate(result_orm)
@@ -85,16 +119,20 @@ async def llm_infomation(state: ReadState) -> ReadState:
 
 async def clean_databases(data) -> str:
     """
-    简化的数据库搜索结果清理函数
+    Simplified database search result cleaning function
+    
+    Processes and cleans search results from various sources including
+    reranked results and time-based search results. Extracts text content
+    from structured data and returns as formatted string.
     
     Args:
-        data: 搜索结果数据
+        data: Search result data (can be string, dict, or other types)
         
     Returns:
-        清理后的内容字符串
+        str: Cleaned content string
     """
     try:
-        # 解析JSON字符串
+        # Parse JSON string
         if isinstance(data, str):
             try:
                 data = json.loads(data)
@@ -104,24 +142,24 @@ async def clean_databases(data) -> str:
         if not isinstance(data, dict):
             return str(data)
 
-        # 获取结果数据
+        # Get result data
         # with open("搜索结果.json","w",encoding='utf-8') as f:
         #     f.write(json.dumps(data, indent=4, ensure_ascii=False))
         results = data.get('results', data)
         if not isinstance(results, dict):
             return str(results)
 
-        # 收集所有内容
+        # Collect all content
         content_list = []
-        
-        # 处理重排序结果
+
+        # Process reranked results
         reranked = results.get('reranked_results', {})
         if reranked:
-            for category in ['summaries', 'statements', 'chunks', 'entities']:
+            for category in ['summaries', 'communities', 'statements', 'chunks', 'entities']:
                 items = reranked.get(category, [])
                 if isinstance(items, list):
                     content_list.extend(items)
-        # 处理时间搜索结果
+        # Process time search results
         time_search = results.get('time_search', {})
         if time_search:
             if isinstance(time_search, dict):
@@ -131,17 +169,23 @@ async def clean_databases(data) -> str:
             elif isinstance(time_search, list):
                 content_list.extend(time_search)
 
-        # 提取文本内容
+        # Extract text content，对 community 按 name 去重（多次 tool 调用会产生重复）
         text_parts = []
+        seen_community_names = set()
         for item in content_list:
             if isinstance(item, dict):
-                text = item.get('statement') or item.get('content', '')
+                # community 节点用 name 去重
+                if 'member_count' in item or 'core_entities' in item:
+                    community_name = item.get('name') or item.get('id', '')
+                    if community_name in seen_community_names:
+                        continue
+                    seen_community_names.add(community_name)
+                text = item.get('statement') or item.get('content') or item.get('summary', '')
                 if text:
                     text_parts.append(text)
             elif isinstance(item, str):
                 text_parts.append(item)
 
-
         return '\n'.join(text_parts).strip()
 
     except Exception as e:
@@ -150,24 +194,33 @@ async def clean_databases(data) -> str:
 
 
 async def retrieve_nodes(state: ReadState) -> ReadState:
+    """
+    Retrieve information using simplified search approach
+    
+    Processes extended problems from previous nodes and performs retrieval
+    using either RAG or hybrid search based on storage type. Handles concurrent
+    processing of multiple questions and deduplicates results.
+    
+    Args:
+        state: ReadState containing problem extensions and configuration
+        
+    Returns:
+        ReadState: Updated state with retrieval results and intermediate outputs
+    """
 
-    '''
-
-    模型信息
-    '''
-
-    problem_extension=state.get('problem_extension', '')['context']
-    storage_type=state.get('storage_type', '')
-    user_rag_memory_id=state.get('user_rag_memory_id', '')
-    end_user_id=state.get('end_user_id', '')
+    problem_extension = state.get('problem_extension', '')['context']
+    storage_type = state.get('storage_type', '')
+    user_rag_memory_id = state.get('user_rag_memory_id', '')
+    end_user_id = state.get('end_user_id', '')
     memory_config = state.get('memory_config', None)
-    original=state.get('data', '')
-    problem_list=[]
-    for key,values in problem_extension.items():
+    original = state.get('data', '')
+    problem_list = []
+    for key, values in problem_extension.items():
         for data in values:
             problem_list.append(data)
     logger.info(f"Retrieve: storage_type={storage_type}, user_rag_memory_id={user_rag_memory_id}")
-    # 创建异步任务处理单个问题
+
+    # Create async task to process individual questions
     async def process_question_nodes(idx, question):
         try:
             # Prepare search parameters based on storage type
@@ -213,7 +266,7 @@ async def retrieve_nodes(state: ReadState) -> ReadState:
                 }
             }
 
-    # 并发处理所有问题
+    # Process all questions concurrently
     tasks = [process_question_nodes(idx, question) for idx, question in enumerate(problem_list)]
     databases_anser = await asyncio.gather(*tasks)
     databases_data = {
@@ -244,7 +297,7 @@ async def retrieve_nodes(state: ReadState) -> ReadState:
 
     send_verify = []
     for i, j in zip(keys, val, strict=False):
-        if j!=['']:
+        if j != ['']:
             send_verify.append({
                 "Query_small": i,
                 "Answer_Small": j
@@ -257,15 +310,26 @@ async def retrieve_nodes(state: ReadState) -> ReadState:
     }
 
     logger.info(f"Collected {len(intermediate_outputs)} intermediate outputs from search results")
-    return {'retrieve':dup_databases}
-
-
+    return {'retrieve': dup_databases}
 
 
 async def retrieve(state: ReadState) -> ReadState:
-    # 从state中获取end_user_id
+    """
+    Advanced retrieve function using LangChain agents and tools
+    
+    Uses LangChain agents with specialized retrieval tools (time-based and hybrid)
+    to perform sophisticated information retrieval. Supports both RAG and traditional
+    memory storage approaches with concurrent processing and result deduplication.
+    
+    Args:
+        state: ReadState containing problem extensions and configuration
+        
+    Returns:
+        ReadState: Updated state with retrieval results and intermediate outputs
+    """
+    # Get end_user_id from state
     import time
-    start=time.time()
+    start = time.time()
     problem_extension = state.get('problem_extension', '')['context']
     storage_type = state.get('storage_type', '')
     user_rag_memory_id = state.get('user_rag_memory_id', '')
@@ -283,6 +347,7 @@ async def retrieve(state: ReadState) -> ReadState:
         with get_db_context() as db:  # 使用同步数据库上下文管理器
             config_service = MemoryConfigService(db)
             return await llm_infomation(state)
+
     llm_config = await get_llm_info()
     api_key_obj = llm_config.api_keys[0]
     api_key = api_key_obj.api_key
@@ -296,28 +361,33 @@ async def retrieve(state: ReadState) -> ReadState:
     )
 
     time_retrieval_tool = create_time_retrieval_tool(end_user_id)
-    search_params = { "end_user_id": end_user_id, "return_raw_results": True }
-    hybrid_retrieval=create_hybrid_retrieval_tool_sync(memory_config, **search_params)
+    search_params = {
+        "end_user_id": end_user_id,
+        "return_raw_results": True,
+        "include": ["summaries", "statements", "chunks", "entities", "communities"],
+    }
+    hybrid_retrieval = create_hybrid_retrieval_tool_sync(memory_config, **search_params)
     agent = create_agent(
         llm,
-        tools=[time_retrieval_tool,hybrid_retrieval],
+        tools=[time_retrieval_tool, hybrid_retrieval],
         system_prompt=f"我是检索专家，可以根据适合的工具进行检索。当前使用的end_user_id是: {end_user_id}"
     )
 
-    # 创建异步任务处理单个问题
+    # Create async task to process individual questions
     import asyncio
 
-    # 在模块级别定义信号量，限制最大并发数
-    SEMAPHORE = asyncio.Semaphore(5)  # 限制最多5个并发数据库操作
+    # Define semaphore at module level to limit maximum concurrency
+    SEMAPHORE = asyncio.Semaphore(5)  # Limit to maximum 5 concurrent database operations
 
     async def process_question(idx, question):
-        async with SEMAPHORE:  # 限制并发
+        async with SEMAPHORE:  # Limit concurrency
             try:
                 if storage_type == "rag" and user_rag_memory_id:
-                    retrieval_knowledge, clean_content, cleaned_query, raw_results = await rag_knowledge(state, question)
+                    retrieval_knowledge, clean_content, cleaned_query, raw_results = await rag_knowledge(state,
+                                                                                                         question)
                 else:
                     cleaned_query = question
-                    # 使用 asyncio 在线程池中运行同步的 agent.invoke
+                    # Use asyncio to run synchronous agent.invoke in thread pool
                     import asyncio
                     response = await asyncio.get_event_loop().run_in_executor(
                         None,
@@ -331,8 +401,32 @@ async def retrieve(state: ReadState) -> ReadState:
                         raw_results = tool_results['content']
                         clean_content = await clean_databases(raw_results)
 
+                        # 社区展开：从 tool 返回结果中提取命中的 community，
+                        # 沿 BELONGS_TO_COMMUNITY 关系拉取关联 Statement 追加到 clean_content
+                        _expanded_stmts_to_write = []
+                        try:
+                            results_dict = raw_results.get('results', {}) if isinstance(raw_results, dict) else {}
+                            reranked = results_dict.get('reranked_results', {})
+                            community_hits = reranked.get('communities', [])
+                            if not community_hits:
+                                community_hits = results_dict.get('communities', [])
+                            if community_hits:
+                                from app.core.memory.agent.services.search_service import expand_communities_to_statements
+                                _expanded_stmts_to_write, new_texts = await expand_communities_to_statements(
+                                    community_results=community_hits,
+                                    end_user_id=end_user_id,
+                                    existing_content=clean_content,
+                                )
+                                if new_texts:
+                                    clean_content = clean_content + '\n' + '\n'.join(new_texts)
+                        except Exception as parse_err:
+                            logger.warning(f"[Retrieve] 解析社区命中结果失败，跳过展开: {parse_err}")
+
                         try:
                             raw_results = raw_results['results']
+                            # 写回展开结果，接口返回中可见（已在 helper 中清洗过字段）
+                            if _expanded_stmts_to_write and isinstance(raw_results, dict):
+                                raw_results.setdefault('reranked_results', {})['expanded_statements'] = _expanded_stmts_to_write
                         except Exception:
                             raw_results = []
 
@@ -366,7 +460,7 @@ async def retrieve(state: ReadState) -> ReadState:
                     }
                 }
 
-    # 并发处理所有问题
+    # Process all questions concurrently
     import asyncio
     tasks = [process_question(idx, question) for idx, question in enumerate(problem_list)]
     databases_anser = await asyncio.gather(*tasks)
@@ -413,5 +507,3 @@ async def retrieve(state: ReadState) -> ReadState:
     #     json.dump(dup_databases, f, indent=4)
     logger.info(f"Collected {len(intermediate_outputs)} intermediate outputs from search results")
     return {'retrieve': dup_databases}
-
-

api/app/core/memory/agent/langgraph_graph/nodes/summary_nodes.py

@@ -1,9 +1,11 @@
-
-
+import asyncio
 import os
 import time
 
 from app.core.logging_config import get_agent_logger, log_time
+from app.core.memory.agent.langgraph_graph.nodes.perceptual_retrieve_node import (
+    PerceptualSearchService,
+)
 from app.core.memory.agent.models.summary_models import (
     RetrieveSummaryResponse,
     SummaryResponse,
@@ -17,34 +19,144 @@ from app.core.memory.agent.utils.llm_tools import (
 from app.core.memory.agent.utils.redis_tool import store
 from app.core.memory.agent.utils.session_tools import SessionService
 from app.core.memory.agent.utils.template_tools import TemplateService
-from app.db import get_db
+from app.core.memory.enums import Neo4jNodeType
+from app.core.rag.nlp.search import knowledge_retrieval
+from app.db import get_db_context
 
 template_root = os.path.join(PROJECT_ROOT_, 'memory', 'agent', 'utils', 'prompt')
 logger = get_agent_logger(__name__)
-db_session = next(get_db())
+
 
 class SummaryNodeService(LLMServiceMixin):
-    """总结节点服务类"""
+    """
+    Summary node service class
     
+    Handles summary generation operations using LLM services. Inherits from 
+    LLMServiceMixin to provide structured LLM calling capabilities for 
+    generating summaries from retrieved information.
+    
+    Attributes:
+        template_service: Service for rendering Jinja2 templates
+    """
+
     def __init__(self):
         super().__init__()
         self.template_service = TemplateService(template_root)
 
-# 创建全局服务实例
+
+# Create global service instance
 summary_service = SummaryNodeService()
 
+
+async def rag_config(state):
+    """
+    Configure RAG (Retrieval-Augmented Generation) settings for summary operations
+    
+    Creates configuration for knowledge base retrieval including similarity thresholds,
+    weights, and reranker settings specifically for summary generation.
+    
+    Args:
+        state: Current state containing user_rag_memory_id
+        
+    Returns:
+        dict: RAG configuration dictionary with knowledge base settings
+    """
+    user_rag_memory_id = state.get('user_rag_memory_id', '')
+    kb_config = {
+        "knowledge_bases": [
+            {
+                "kb_id": user_rag_memory_id,
+                "similarity_threshold": 0.7,
+                "vector_similarity_weight": 0.5,
+                "top_k": 10,
+                "retrieve_type": "participle"
+            }
+        ],
+        "merge_strategy": "weight",
+        "reranker_id": os.getenv('reranker_id'),
+        "reranker_top_k": 10
+    }
+    return kb_config
+
+
+async def rag_knowledge(state, question):
+    """
+    Retrieve knowledge using RAG approach for summary generation
+    
+    Performs knowledge retrieval from configured knowledge bases using the
+    provided question and returns formatted results for summary processing.
+    
+    Args:
+        state: Current state containing configuration
+        question: Question to search for in knowledge base
+        
+    Returns:
+        tuple: (retrieval_knowledge, clean_content, cleaned_query, raw_results)
+            - retrieval_knowledge: List of retrieved knowledge chunks
+            - clean_content: Formatted content string
+            - cleaned_query: Processed query string
+            - raw_results: Raw retrieval results
+    """
+    kb_config = await rag_config(state)
+    end_user_id = state.get('end_user_id', '')
+    user_rag_memory_id = state.get("user_rag_memory_id", '')
+    retrieve_chunks_result = knowledge_retrieval(question, kb_config, [str(end_user_id)])
+    try:
+        retrieval_knowledge = [i.page_content for i in retrieve_chunks_result]
+        clean_content = '\n\n'.join(retrieval_knowledge)
+        cleaned_query = question
+        raw_results = clean_content
+        logger.info(f" Using RAG storage with memory_id={user_rag_memory_id}")
+    except  Exception:
+        retrieval_knowledge = []
+        clean_content = ''
+        raw_results = ''
+        cleaned_query = question
+        logger.info(f"No content retrieved from knowledge base: {user_rag_memory_id}")
+    return retrieval_knowledge, clean_content, cleaned_query, raw_results
+
+
 async def summary_history(state: ReadState) -> ReadState:
+    """
+    Retrieve conversation history for summary context
+    
+    Gets the conversation history for the current user to provide context
+    for summary generation operations.
+    
+    Args:
+        state: ReadState containing end_user_id
+        
+    Returns:
+        ReadState: Conversation history data
+    """
     end_user_id = state.get("end_user_id", '')
     history = await SessionService(store).get_history(end_user_id, end_user_id, end_user_id)
     return history
 
-async def summary_llm(state: ReadState, history, retrieve_info, template_name, operation_name, response_model,search_mode) -> str:
+
+async def summary_llm(state: ReadState, history, retrieve_info, template_name, operation_name, response_model,
+                      search_mode) -> str:
     """
-    增强的summary_llm函数，包含更好的错误处理和数据验证
+    Enhanced summary_llm function with better error handling and data validation
+    
+    Generates summaries using LLM with structured output. Includes fallback mechanisms
+    for handling LLM failures and provides robust error recovery.
+    
+    Args:
+        state: ReadState containing current context
+        history: Conversation history for context
+        retrieve_info: Retrieved information to summarize
+        template_name: Jinja2 template name for prompt generation
+        operation_name: Type of operation (summary, input_summary, retrieve_summary)
+        response_model: Pydantic model for structured output
+        search_mode: Search mode flag ("0" for simple, "1" for complex)
+        
+    Returns:
+        str: Generated summary text or fallback message
     """
     data = state.get("data", '')
-    
-    # 构建系统提示词
+
+    # Build system prompt
     if str(search_mode) == "0":
         system_prompt = await summary_service.template_service.render_template(
             template_name=template_name,
@@ -61,40 +173,41 @@ async def summary_llm(state: ReadState, history, retrieve_info, template_name, o
             retrieve_info=retrieve_info
         )
     try:
-        # 使用优化的LLM服务进行结构化输出
-        structured = await summary_service.call_llm_structured(
-            state=state,
-            db_session=db_session,
-            system_prompt=system_prompt,
-            response_model=response_model,
-            fallback_value=None
-        )
-        # 验证结构化响应
+        # Use optimized LLM service for structured output
+        with get_db_context() as db_session:
+            structured = await summary_service.call_llm_structured(
+                state=state,
+                db_session=db_session,
+                system_prompt=system_prompt,
+                response_model=response_model,
+                fallback_value=None
+            )
+        # Validate structured response
         if structured is None:
-            logger.warning(f"LLM返回None，使用默认回答")
+            logger.warning("LLM返回None，使用默认回答")
             return "信息不足，无法回答"
-        
-        # 根据操作类型提取答案
+
+        # Extract answer based on operation type
         if operation_name == "summary":
             aimessages = getattr(structured, 'query_answer', None) or "信息不足，无法回答"
         else:
-            # 处理RetrieveSummaryResponse
+            # Handle RetrieveSummaryResponse
             if hasattr(structured, 'data') and structured.data:
                 aimessages = getattr(structured.data, 'query_answer', None) or "信息不足，无法回答"
             else:
-                logger.warning(f"结构化响应缺少data字段")
+                logger.warning("结构化响应缺少data字段")
                 aimessages = "信息不足，无法回答"
-        
-        # 验证答案不为空
+
+        # Validate answer is not empty
         if not aimessages or aimessages.strip() == "":
             aimessages = "信息不足，无法回答"
-            
+
         return aimessages
-        
+
     except Exception as e:
         logger.error(f"结构化输出失败: {e}", exc_info=True)
-        
-        # 尝试非结构化输出作为fallback
+
+        # Try unstructured output as fallback
         try:
             logger.info("尝试非结构化输出作为fallback")
             response = await summary_service.call_llm_simple(
@@ -103,24 +216,38 @@ async def summary_llm(state: ReadState, history, retrieve_info, template_name, o
                 system_prompt=system_prompt,
                 fallback_message="信息不足，无法回答"
             )
-            
+
             if response and response.strip():
-                # 简单清理响应
+                # Simple response cleaning
                 cleaned_response = response.strip()
-                # 移除可能的JSON标记
+                # Remove possible JSON markers
                 if cleaned_response.startswith('```'):
                     lines = cleaned_response.split('\n')
                     cleaned_response = '\n'.join(lines[1:-1])
-                
+
                 return cleaned_response
             else:
                 return "信息不足，无法回答"
-                
+
         except Exception as fallback_error:
             logger.error(f"Fallback也失败: {fallback_error}")
             return "信息不足，无法回答"
 
-async def summary_redis_save(state: ReadState,aimessages) -> ReadState:
+
+async def summary_redis_save(state: ReadState, aimessages) -> ReadState:
+    """
+    Save summary results to Redis session storage
+    
+    Stores the generated summary and user query in Redis for session management
+    and conversation history tracking.
+    
+    Args:
+        state: ReadState containing user and query information
+        aimessages: Generated summary message to save
+        
+    Returns:
+        ReadState: Updated state after saving to Redis
+    """
     data = state.get("data", '')
     end_user_id = state.get("end_user_id", '')
     await SessionService(store).save_session(
@@ -132,10 +259,26 @@ async def summary_redis_save(state: ReadState,aimessages) -> ReadState:
     )
     await SessionService(store).cleanup_duplicates()
     logger.info(f"sessionid: {aimessages} 写入成功")
-async def summary_prompt(state: ReadState,aimessages,raw_results) -> ReadState:
-    storage_type=state.get("storage_type",'')
-    user_rag_memory_id=state.get("user_rag_memory_id",'')
-    data=state.get("data", '')
+
+
+async def summary_prompt(state: ReadState, aimessages, raw_results) -> ReadState:
+    """
+    Format summary results for different output types
+    
+    Creates structured output formats for both input summary and retrieval summary
+    operations, including metadata and intermediate results for frontend display.
+    
+    Args:
+        state: ReadState containing storage and user information
+        aimessages: Generated summary message
+        raw_results: Raw search/retrieval results
+        
+    Returns:
+        tuple: (input_summary, retrieve_summary) formatted result dictionaries
+    """
+    storage_type = state.get("storage_type", '')
+    user_rag_memory_id = state.get("user_rag_memory_id", '')
+    data = state.get("data", '')
     input_summary = {
         "status": "success",
         "summary_result": aimessages,
@@ -152,14 +295,14 @@ async def summary_prompt(state: ReadState,aimessages,raw_results) -> ReadState:
             "user_rag_memory_id": user_rag_memory_id
         }
     }
-    retrieve={
+    retrieve = {
         "status": "success",
         "summary_result": aimessages,
         "storage_type": storage_type,
         "user_rag_memory_id": user_rag_memory_id,
         "_intermediate": {
             "type": "retrieval_summary",
-            "title":"快速检索",
+            "title": "快速检索",
             "summary": aimessages,
             "query": data,
             "storage_type": storage_type,
@@ -167,31 +310,90 @@ async def summary_prompt(state: ReadState,aimessages,raw_results) -> ReadState:
         }
     }
 
-    return input_summary,retrieve
+    return input_summary, retrieve
+
 
 async def Input_Summary(state: ReadState) -> ReadState:
-    start=time.time()
-    storage_type=state.get("storage_type",'')
+    """
+    Generate quick input summary from retrieved information
+    
+    Performs fast retrieval and generates a quick summary response for user queries.
+    This function prioritizes speed by only searching summary nodes and provides
+    immediate feedback to users.
+    
+    Args:
+        state: ReadState containing user query, storage configuration, and context
+        
+    Returns:
+        ReadState: Dictionary containing summary results with status and metadata
+    """
+    start = time.time()
+    storage_type = state.get("storage_type", '')
     memory_config = state.get('memory_config', None)
-    user_rag_memory_id=state.get("user_rag_memory_id",'')
-    data=state.get("data", '')
-    end_user_id=state.get("end_user_id", '')
+    user_rag_memory_id = state.get("user_rag_memory_id", '')
+    data = state.get("data", '')
+    end_user_id = state.get("end_user_id", '')
     logger.info(f"Input_Summary: storage_type={storage_type}, user_rag_memory_id={user_rag_memory_id}")
-    history = await summary_history( state)
+    history = await summary_history(state)
     search_params = {
         "end_user_id": end_user_id,
         "question": data,
         "return_raw_results": True,
-        "include": ["summaries"]  # Only search summary nodes for faster performance
+        "include": [Neo4jNodeType.MEMORYSUMMARY, Neo4jNodeType.COMMUNITY]  # MemorySummary 和 Community 同为高维度概括节点
     }
 
     try:
-        retrieve_info, question, raw_results = await SearchService().execute_hybrid_search(**search_params, memory_config=memory_config)
+        if storage_type != "rag":
+
+            async def _perceptual_search():
+                service = PerceptualSearchService(
+                    end_user_id=end_user_id,
+                    memory_config=memory_config,
+                )
+                return await service.search(query=data, limit=5)
+
+            hybrid_task = SearchService().execute_hybrid_search(
+                **search_params,
+                memory_config=memory_config,
+                expand_communities=False,
+            )
+            perceptual_task = _perceptual_search()
+
+            gather_results = await asyncio.gather(
+                hybrid_task, perceptual_task, return_exceptions=True
+            )
+            hybrid_result = gather_results[0]
+            perceptual_results = gather_results[1]
+
+            # 处理 hybrid search 异常
+            if isinstance(hybrid_result, Exception):
+                raise hybrid_result
+            retrieve_info, question, raw_results = hybrid_result
+
+            # 处理感知记忆结果
+            if isinstance(perceptual_results, Exception):
+                logger.warning(f"[Input_Summary] perceptual search failed: {perceptual_results}")
+                perceptual_results = []
+
+            # 拼接感知记忆内容到 retrieve_info
+            if perceptual_results and isinstance(perceptual_results, dict):
+                perceptual_content = perceptual_results.get("content", "")
+                if perceptual_content:
+                    retrieve_info = f"{retrieve_info}\n\n<history-files>\n{perceptual_content}"
+                    count = len(perceptual_results.get("memories", []))
+                    logger.info(f"[Input_Summary] appended {count} perceptual memories (reranked)")
+
+            # 调试：打印 community 检索结果数量
+            if raw_results and isinstance(raw_results, dict):
+                reranked = raw_results.get('reranked_results', {})
+                community_hits = reranked.get('communities', [])
+                logger.debug(f"[Input_Summary] community 命中数: {len(community_hits)}, "
+                             f"summary 命中数: {len(reranked.get('summaries', []))}")
+        else:
+            retrieval_knowledge, retrieve_info, question, raw_results = await rag_knowledge(state, data)
     except Exception as e:
-        logger.error( f"Input_Summary: hybrid_search failed, using empty results: {e}",  exc_info=True )
+        logger.error(f"Input_Summary: hybrid_search failed, using empty results: {e}", exc_info=True)
         retrieve_info, question, raw_results = "", data, []
-
-
     try:
         # aimessages=await summary_llm(state,history,retrieve_info,'Retrieve_Summary_prompt.jinja2',
         #                              'input_summary',RetrieveSummaryResponse)
@@ -199,8 +401,8 @@ async def Input_Summary(state: ReadState) -> ReadState:
         summary_result = await summary_prompt(state, retrieve_info, retrieve_info)
         summary = summary_result[0]
     except Exception as e:
-        logger.error( f"Input_Summary failed: {e}", exc_info=True )
-        summary= {
+        logger.error(f"Input_Summary failed: {e}", exc_info=True)
+        summary = {
             "status": "fail",
             "summary_result": "信息不足，无法回答",
             "storage_type": storage_type,
@@ -208,35 +410,58 @@ async def Input_Summary(state: ReadState) -> ReadState:
             "error": str(e)
         }
     end = time.time()
-    try:
-        duration = end - start
-    except Exception:
-        duration = 0.0
+    duration = end - start
     log_time('检索', duration)
-    return {"summary":summary}
+    return {"summary": summary}
 
-async def Retrieve_Summary(state: ReadState)-> ReadState:
-    retrieve=state.get("retrieve", '')
-    history = await summary_history( state)
+
+async def Retrieve_Summary(state: ReadState) -> ReadState:
+    """
+    Generate comprehensive summary from retrieved expansion issues
+    
+    Processes retrieved expansion issues and generates a detailed summary using LLM.
+    This function handles complex retrieval results and provides comprehensive answers
+    based on expanded query results.
+    
+    Args:
+        state: ReadState containing retrieve data with expansion issues
+        
+    Returns:
+        ReadState: Dictionary containing comprehensive summary results
+    """
+    retrieve = state.get("retrieve", '')
+    history = await summary_history(state)
     import json
-    with open("检索.json","w",encoding='utf-8') as f:
+    with open("检索.json", "w", encoding='utf-8') as f:
         f.write(json.dumps(retrieve, indent=4, ensure_ascii=False))
-    retrieve=retrieve.get("Expansion_issue", [])
-    start=time.time()
-    retrieve_info_str=[]
+    retrieve = retrieve.get("Expansion_issue", [])
+    start = time.time()
+    retrieve_info_str = []
     for data in retrieve:
-        if data=='':
-            retrieve_info_str=''
+        if data == '':
+            retrieve_info_str = ''
         else:
             for key, value in data.items():
-                if key=='Answer_Small':
+                if key == 'Answer_Small':
                     for i in value:
                         retrieve_info_str.append(i)
-    retrieve_info_str=list(set(retrieve_info_str))
-    retrieve_info_str='\n'.join(retrieve_info_str)
+    retrieve_info_str = list(set(retrieve_info_str))
+    retrieve_info_str = '\n'.join(retrieve_info_str)
 
-    aimessages=await  summary_llm(state,history,retrieve_info_str,
-                                  'direct_summary_prompt.jinja2','retrieve_summary',RetrieveSummaryResponse,"1")
+    # Merge perceptual memory content
+    perceptual_data = state.get("perceptual_data", {})
+    perceptual_content = perceptual_data.get("content", "") if isinstance(perceptual_data, dict) else ""
+    if perceptual_content:
+        retrieve_info_str = f"{retrieve_info_str}\n\n<history-file-input>\n{perceptual_content}</history-file-input>"
+
+    aimessages = await summary_llm(
+        state,
+        history,
+        retrieve_info_str,
+        'direct_summary_prompt.jinja2',
+        'retrieve_summary', RetrieveSummaryResponse,
+        "1"
+    )
     if '信息不足，无法回答' not in str(aimessages) or str(aimessages) != "":
         await summary_redis_save(state, aimessages)
     if aimessages == '':
@@ -248,33 +473,52 @@ async def Retrieve_Summary(state: ReadState)-> ReadState:
     except Exception:
         duration = 0.0
     log_time('Retrieval summary', duration)
-    
-    # 修复协程调用 - 先await，然后访问返回值
+
+    # Fixed coroutine call - await first, then access return value
     summary_result = await summary_prompt(state, aimessages, retrieve_info_str)
     summary = summary_result[1]
-    return {"summary":summary}
+    return {"summary": summary}
 
 
-async def Summary(state: ReadState)-> ReadState:
-    start=time.time()
+async def Summary(state: ReadState) -> ReadState:
+    """
+    Generate final comprehensive summary from verified data
+    
+    Creates the final summary using verified expansion issues and conversation history.
+    This function processes verified data to generate the most comprehensive and
+    accurate response to user queries.
+    
+    Args:
+        state: ReadState containing verified data and query information
+        
+    Returns:
+        ReadState: Dictionary containing final summary results
+    """
+    start = time.time()
     query = state.get("data", '')
-    verify=state.get("verify", '')
-    verify_expansion_issue=verify.get("verified_data", '')
-    retrieve_info_str=''
+    verify = state.get("verify", '')
+    verify_expansion_issue = verify.get("verified_data", '')
+    retrieve_info_str = ''
     for data in verify_expansion_issue:
         for key, value in data.items():
-            if key=='answer_small':
+            if key == 'answer_small':
                 for i in value:
-                    retrieve_info_str+=i+'\n'
-    history=await summary_history(state)
+                    retrieve_info_str += i + '\n'
+    history = await summary_history(state)
+
+    # Merge perceptual memory content
+    perceptual_data = state.get("perceptual_data", {})
+    perceptual_content = perceptual_data.get("content", "") if isinstance(perceptual_data, dict) else ""
+    if perceptual_content:
+        retrieve_info_str = f"{retrieve_info_str}\n\n<history-file-input>\n{perceptual_content}</history-file-input>"
 
     data = {
         "query": query,
         "history": history,
         "retrieve_info": retrieve_info_str
     }
-    aimessages=await  summary_llm(state,history,data,
-                                  'summary_prompt.jinja2','summary',SummaryResponse,0)
+    aimessages = await  summary_llm(state, history, data,
+                                    'summary_prompt.jinja2', 'summary', SummaryResponse, 0)
 
     if '信息不足，无法回答' not in str(aimessages) or str(aimessages) != "":
         await summary_redis_save(state, aimessages)
@@ -286,14 +530,28 @@ async def Summary(state: ReadState)-> ReadState:
         duration = 0.0
     log_time('Retrieval summary', duration)
 
-    # 修复协程调用 - 先await，然后访问返回值
+    # Fixed coroutine call - await first, then access return value
     summary_result = await summary_prompt(state, aimessages, retrieve_info_str)
     summary = summary_result[1]
-    return {"summary":summary}
+    return {"summary": summary}
 
-async def Summary_fails(state: ReadState)-> ReadState:
-    storage_type=state.get("storage_type", '')
-    user_rag_memory_id=state.get("user_rag_memory_id", '')
+
+async def Summary_fails(state: ReadState) -> ReadState:
+    """
+    Generate fallback summary when normal summary process fails
+    
+    Provides a fallback summary generation mechanism when the standard summary
+    process encounters errors or fails to produce satisfactory results. Uses
+    a specialized failure template to handle edge cases.
+    
+    Args:
+        state: ReadState containing verified data and failure context
+        
+    Returns:
+        ReadState: Dictionary containing fallback summary results
+    """
+    storage_type = state.get("storage_type", '')
+    user_rag_memory_id = state.get("user_rag_memory_id", '')
     history = await summary_history(state)
     query = state.get("data", '')
     verify = state.get("verify", '')
@@ -304,17 +562,24 @@ async def Summary_fails(state: ReadState)-> ReadState:
             if key == 'answer_small':
                 for i in value:
                     retrieve_info_str += i + '\n'
+
+    # Merge perceptual memory content
+    perceptual_data = state.get("perceptual_data", {})
+    perceptual_content = perceptual_data.get("content", "") if isinstance(perceptual_data, dict) else ""
+    if perceptual_content:
+        retrieve_info_str = f"{retrieve_info_str}\n\n<history-file-input>\n{perceptual_content}</history-file-input>"
+
     data = {
         "query": query,
         "history": history,
         "retrieve_info": retrieve_info_str
     }
-    aimessages = await  summary_llm(state, history, data,
-                                 'fail_summary_prompt.jinja2', 'summary', SummaryResponse, 0)
-    result= {
+    aimessages = await summary_llm(state, history, data,
+                                   'fail_summary_prompt.jinja2', 'summary', SummaryResponse, 0)
+    result = {
         "status": "success",
         "summary_result": aimessages,
         "storage_type": storage_type,
         "user_rag_memory_id": user_rag_memory_id
     }
-    return {"summary":result}
+    return {"summary": result}

api/app/core/memory/agent/langgraph_graph/nodes/verification_nodes.py

@@ -1,8 +1,9 @@
+import asyncio
 import os
-from app.core.logging_config import get_agent_logger
-from app.db import get_db
 
+from app.core.logging_config import get_agent_logger
 from app.core.memory.agent.models.verification_models import VerificationResult
+from app.core.memory.agent.services.optimized_llm_service import LLMServiceMixin
 from app.core.memory.agent.utils.llm_tools import (
     PROJECT_ROOT_,
     ReadState,
@@ -10,29 +11,53 @@ from app.core.memory.agent.utils.llm_tools import (
 from app.core.memory.agent.utils.redis_tool import store
 from app.core.memory.agent.utils.session_tools import SessionService
 from app.core.memory.agent.utils.template_tools import TemplateService
-from app.core.memory.agent.services.optimized_llm_service import LLMServiceMixin
+from app.db import get_db_context
 
 template_root = os.path.join(PROJECT_ROOT_, 'memory', 'agent', 'utils', 'prompt')
-db_session = next(get_db())
 logger = get_agent_logger(__name__)
 
+
 class VerificationNodeService(LLMServiceMixin):
-    """验证节点服务类"""
+    """
+    Verification node service class
     
+    Handles data verification operations using LLM services. Inherits from 
+    LLMServiceMixin to provide structured LLM calling capabilities for 
+    verifying and validating retrieved information.
+    
+    Attributes:
+        template_service: Service for rendering Jinja2 templates
+    """
+
     def __init__(self):
         super().__init__()
         self.template_service = TemplateService(template_root)
 
-# 创建全局服务实例
+
+# Create global service instance
 verification_service = VerificationNodeService()
 
+
 async def Verify_prompt(state: ReadState, messages_deal: VerificationResult):
-    """处理验证结果并生成输出格式"""
+    """
+    Process verification results and generate output format
+    
+    Transforms VerificationResult objects into structured output format suitable
+    for frontend consumption. Handles conversion of VerificationItem objects to
+    dictionary format and adds metadata for tracking.
+    
+    Args:
+        state: ReadState containing storage and user configuration
+        messages_deal: VerificationResult containing verification outcomes
+        
+    Returns:
+        dict: Formatted verification result with status and metadata
+    """
     storage_type = state.get('storage_type', '')
     user_rag_memory_id = state.get('user_rag_memory_id', '')
     data = state.get('data', '')
-    
-    # 将 VerificationItem 对象转换为字典列表
+
+    # Convert VerificationItem objects to dictionary list
     verified_data = []
     if messages_deal.expansion_issue:
         for item in messages_deal.expansion_issue:
@@ -40,7 +65,7 @@ async def Verify_prompt(state: ReadState, messages_deal: VerificationResult):
                 verified_data.append(item.model_dump())
             elif isinstance(item, dict):
                 verified_data.append(item)
-    
+
     Verify_result = {
         "status": messages_deal.split_result,
         "verified_data": verified_data,
@@ -58,34 +83,37 @@ async def Verify_prompt(state: ReadState, messages_deal: VerificationResult):
         }
     }
     return Verify_result
+
+
 async def Verify(state: ReadState):
     logger.info("=== Verify 节点开始执行 ===")
     try:
         content = state.get('data', '')
         end_user_id = state.get('end_user_id', '')
         memory_config = state.get('memory_config', None)
-        
+
         logger.info(f"Verify: content={content[:50] if content else 'empty'}..., end_user_id={end_user_id}")
 
         history = await SessionService(store).get_history(end_user_id, end_user_id, end_user_id)
         logger.info(f"Verify: 获取历史记录完成，history length={len(history)}")
 
         retrieve = state.get("retrieve", {})
-        logger.info(f"Verify: retrieve data type={type(retrieve)}, keys={retrieve.keys() if isinstance(retrieve, dict) else 'N/A'}")
-        
+        logger.info(
+            f"Verify: retrieve data type={type(retrieve)}, keys={retrieve.keys() if isinstance(retrieve, dict) else 'N/A'}")
+
         retrieve_expansion = retrieve.get("Expansion_issue", []) if isinstance(retrieve, dict) else []
         logger.info(f"Verify: Expansion_issue length={len(retrieve_expansion)}")
-        
+
         messages = {
             "Query": content,
             "Expansion_issue": retrieve_expansion
         }
 
         logger.info("Verify: 开始渲染模板")
-        
-        # 生成 JSON schema 以指导 LLM 输出正确格式
+
+        # Generate JSON schema to guide LLM output format
         json_schema = VerificationResult.model_json_schema()
-        
+
         system_prompt = await verification_service.template_service.render_template(
             template_name='split_verify_prompt.jinja2',
             operation_name='split_verify_prompt',
@@ -94,29 +122,30 @@ async def Verify(state: ReadState):
             json_schema=json_schema
         )
         logger.info(f"Verify: 模板渲染完成，prompt length={len(system_prompt)}")
-        
+
         # 使用优化的LLM服务，添加超时保护
         logger.info("Verify: 开始调用 LLM")
         try:
-            # 添加 asyncio.wait_for 超时包裹，防止无限等待
-            # 超时时间设置为 150 秒（比 LLM 配置的 120 秒稍长）
-            import asyncio
-            structured = await asyncio.wait_for(
-                verification_service.call_llm_structured(
-                    state=state,
-                    db_session=db_session,
-                    system_prompt=system_prompt,
-                    response_model=VerificationResult,
-                    fallback_value={
-                        "query": content,
-                        "history": history if isinstance(history, list) else [],
-                        "expansion_issue": [],
-                        "split_result": "failed",
-                        "reason": "验证失败或超时"
-                    }
-                ),
-                timeout=150.0  # 150秒超时
-            )
+            # Add asyncio.wait_for timeout wrapper to prevent infinite waiting
+            # Timeout set to 150 seconds (slightly longer than LLM config's 120 seconds)
+
+            with get_db_context() as db_session:
+                structured = await asyncio.wait_for(
+                    verification_service.call_llm_structured(
+                        state=state,
+                        db_session=db_session,
+                        system_prompt=system_prompt,
+                        response_model=VerificationResult,
+                        fallback_value={
+                            "query": content,
+                            "history": history if isinstance(history, list) else [],
+                            "expansion_issue": [],
+                            "split_result": "failed",
+                            "reason": "验证失败或超时"
+                        }
+                    ),
+                    timeout=150.0  # 150 second timeout
+                )
             logger.info(f"Verify: LLM 调用完成，result={structured}")
         except asyncio.TimeoutError:
             logger.error("Verify: LLM 调用超时（150秒），使用 fallback 值")
@@ -127,11 +156,11 @@ async def Verify(state: ReadState):
                 split_result="failed",
                 reason="LLM调用超时"
             )
-        
+
         result = await Verify_prompt(state, structured)
         logger.info("=== Verify 节点执行完成 ===")
         return {"verify": result}
-        
+
     except Exception as e:
         logger.error(f"Verify 节点执行失败: {e}", exc_info=True)
         # 返回失败的验证结果
@@ -152,4 +181,4 @@ async def Verify(state: ReadState):
                     "user_rag_memory_id": state.get('user_rag_memory_id', '')
                 }
             }
-        }
+        }

api/app/core/memory/agent/langgraph_graph/nodes/write_nodes.py

@@ -1,3 +1,4 @@
+from app.cache.memory.interest_memory import InterestMemoryCache
 from app.core.memory.agent.utils.llm_tools import WriteState
 from app.core.memory.agent.utils.write_tools import write
 from app.core.logging_config import get_agent_logger
@@ -40,6 +41,15 @@ async def write_node(state: WriteState) -> WriteState:
         )
         logger.info(f"Write completed successfully! Config: {memory_config.config_name}")
 
+        # 写入 neo4j 成功后，删除该用户的兴趣分布缓存，确保下次请求重新生成
+        for lang in ["zh", "en"]:
+            deleted = await InterestMemoryCache.delete_interest_distribution(
+                end_user_id=end_user_id,
+                language=lang,
+            )
+            if deleted:
+                logger.info(f"Invalidated interest distribution cache: end_user_id={end_user_id}, language={lang}")
+
         write_result = {
             "status": "success",
             "data": structured_messages,

api/app/core/memory/agent/langgraph_graph/read_graph.py

@@ -1,22 +1,20 @@
 #!/usr/bin/env python3
+import logging
 from contextlib import asynccontextmanager
 
-from langchain_core.messages import HumanMessage
 from langgraph.constants import START, END
 from langgraph.graph import StateGraph
 
-
-from app.db import get_db
-from app.services.memory_config_service import MemoryConfigService
-
-from app.core.memory.agent.utils.llm_tools import ReadState
 from app.core.memory.agent.langgraph_graph.nodes.data_nodes import content_input_node
+from app.core.memory.agent.langgraph_graph.nodes.perceptual_retrieve_node import (
+    perceptual_retrieve_node,
+)
 from app.core.memory.agent.langgraph_graph.nodes.problem_nodes import (
     Split_The_Problem,
     Problem_Extension,
 )
 from app.core.memory.agent.langgraph_graph.nodes.retrieve_nodes import (
-    retrieve,
+    retrieve_nodes,
 )
 from app.core.memory.agent.langgraph_graph.nodes.summary_nodes import (
     Input_Summary,
@@ -30,12 +28,26 @@ from app.core.memory.agent.langgraph_graph.routing.routers import (
     Retrieve_continue,
     Verify_continue,
 )
+from app.core.memory.agent.utils.llm_tools import ReadState
 
+logger = logging.getLogger(__name__)
 
 
 @asynccontextmanager
 async def make_read_graph():
-    """创建并返回 LangGraph 工作流"""
+    """
+    Create and return a LangGraph workflow for memory reading operations
+    
+    Builds a state graph workflow that handles memory retrieval, problem analysis,
+    verification, and summarization. The workflow includes nodes for content input,
+    problem splitting, retrieval, verification, and various summary operations.
+    
+    Yields:
+        StateGraph: Compiled LangGraph workflow for memory reading
+        
+    Raises:
+        Exception: If workflow creation fails
+    """
     try:
         # Build workflow graph
         workflow = StateGraph(ReadState)
@@ -43,135 +55,34 @@ async def make_read_graph():
         workflow.add_node("Split_The_Problem", Split_The_Problem)
         workflow.add_node("Problem_Extension", Problem_Extension)
         workflow.add_node("Input_Summary", Input_Summary)
-        # workflow.add_node("Retrieve", retrieve_nodes)
-        workflow.add_node("Retrieve", retrieve)
+        workflow.add_node("Retrieve", retrieve_nodes)
+        # workflow.add_node("Retrieve", retrieve)
+        workflow.add_node("Perceptual_Retrieve", perceptual_retrieve_node)
         workflow.add_node("Verify", Verify)
         workflow.add_node("Retrieve_Summary", Retrieve_Summary)
         workflow.add_node("Summary", Summary)
         workflow.add_node("Summary_fails", Summary_fails)
-        
-        # 添加边
+
+        # Add edges to define workflow flow
         workflow.add_edge(START, "content_input")
         workflow.add_conditional_edges("content_input", Split_continue)
         workflow.add_edge("Input_Summary", END)
         workflow.add_edge("Split_The_Problem", "Problem_Extension")
-        workflow.add_edge("Problem_Extension", "Retrieve")
+        # After Problem_Extension, retrieve perceptual memory first, then main Retrieve
+        workflow.add_edge("Problem_Extension", "Perceptual_Retrieve")
+        workflow.add_edge("Perceptual_Retrieve", "Retrieve")
         workflow.add_conditional_edges("Retrieve", Retrieve_continue)
         workflow.add_edge("Retrieve_Summary", END)
         workflow.add_conditional_edges("Verify", Verify_continue)
         workflow.add_edge("Summary_fails", END)
         workflow.add_edge("Summary", END)
 
-
-        '''-----'''
         # workflow.add_edge("Retrieve", END)
-        
-        # 编译工作流
+
+        # Compile workflow
         graph = workflow.compile()
         yield graph
-        
+
     except Exception as e:
-        print(f"创建工作流失败: {e}")
+        logger.error(f"创建工作流失败: {e}")
         raise
-    finally:
-        print("工作流创建完成")
-
-async def main():
-    """主函数 - 运行工作流"""
-    message = "昨天有什么好看的电影"
-    end_user_id = '88a459f5_text09'  # 组ID
-    storage_type = 'neo4j'  # 存储类型
-    search_switch = '1'  # 搜索开关
-    user_rag_memory_id = 'wwwwwwww'  # 用户RAG记忆ID
-
-    # 获取数据库会话
-    db_session = next(get_db())
-    config_service = MemoryConfigService(db_session)
-    memory_config = config_service.load_memory_config(
-        config_id=17,  # 改为整数
-        service_name="MemoryAgentService"
-    )
-    import time
-    start=time.time()
-    try:
-        async with make_read_graph() as graph:
-            config = {"configurable": {"thread_id": end_user_id}}
-            # 初始状态 - 包含所有必要字段
-            initial_state = {"messages": [HumanMessage(content=message)] ,"search_switch":search_switch,"end_user_id":end_user_id
-                             ,"storage_type":storage_type,"user_rag_memory_id":user_rag_memory_id,"memory_config":memory_config}
-            # 获取节点更新信息
-            _intermediate_outputs = []
-            summary = ''
-            
-            async for update_event in graph.astream(
-                    initial_state,
-                    stream_mode="updates",
-                    config=config
-            ):
-                for node_name, node_data in update_event.items():
-                    print(f"处理节点: {node_name}")
-                    
-                    # 处理不同Summary节点的返回结构
-                    if 'Summary' in node_name:
-                        if 'InputSummary' in node_data and 'summary_result' in node_data['InputSummary']:
-                            summary = node_data['InputSummary']['summary_result']
-                        elif 'RetrieveSummary' in node_data and 'summary_result' in node_data['RetrieveSummary']:
-                            summary = node_data['RetrieveSummary']['summary_result']
-                        elif 'summary' in node_data and 'summary_result' in node_data['summary']:
-                            summary = node_data['summary']['summary_result']
-                        elif 'SummaryFails' in node_data and 'summary_result' in node_data['SummaryFails']:
-                            summary = node_data['SummaryFails']['summary_result']
-
-                    spit_data = node_data.get('spit_data', {}).get('_intermediate', None)
-                    if spit_data and spit_data != [] and spit_data != {}:
-                        _intermediate_outputs.append(spit_data)
-                    
-                    # Problem_Extension 节点
-                    problem_extension = node_data.get('problem_extension', {}).get('_intermediate', None)
-                    if problem_extension and problem_extension != [] and problem_extension != {}:
-                        _intermediate_outputs.append(problem_extension)
-                    
-                    # Retrieve 节点
-                    retrieve_node = node_data.get('retrieve', {}).get('_intermediate_outputs', None)
-                    if retrieve_node and retrieve_node != [] and retrieve_node != {}:
-                        _intermediate_outputs.extend(retrieve_node)
-                    
-                    # Verify 节点
-                    verify_n = node_data.get('verify', {}).get('_intermediate', None)
-                    if verify_n and verify_n != [] and verify_n != {}:
-                        _intermediate_outputs.append(verify_n)
-
-                    
-                    # Summary 节点
-                    summary_n = node_data.get('summary', {}).get('_intermediate', None)
-                    if summary_n and summary_n != [] and summary_n != {}:
-                        _intermediate_outputs.append(summary_n)
-
-            # # 过滤掉空值
-            # _intermediate_outputs = [item for item in _intermediate_outputs if item and item != [] and item != {}]
-            #
-            # # 优化搜索结果
-            # print("=== 开始优化搜索结果 ===")
-            # optimized_outputs = merge_multiple_search_results(_intermediate_outputs)
-            # result=reorder_output_results(optimized_outputs)
-            # # 保存优化后的结果到文件
-            # with open('_intermediate_outputs_optimized.json', 'w', encoding='utf-8') as f:
-            #     import json
-            #     f.write(json.dumps(result, indent=4, ensure_ascii=False))
-            #
-            print(f"=== 最终摘要 ===")
-            print(summary)
-                
-    except Exception as e:
-        import traceback
-        traceback.print_exc()
-
-    end=time.time()
-    print(100*'y')
-    print(f"总耗时: {end-start}s")
-    print(100*'y')
-
-
-if __name__ == "__main__":
-    import asyncio
-    asyncio.run(main())

api/app/core/memory/agent/langgraph_graph/routing/routers.py

@@ -1,13 +1,13 @@
-
 from typing import Literal
 
 from app.core.logging_config import get_agent_logger
 from app.core.memory.agent.utils.llm_tools import ReadState, COUNTState
 
-
 logger = get_agent_logger(__name__)
 counter = COUNTState(limit=3)
-def Split_continue(state:ReadState) -> Literal["Split_The_Problem", "Input_Summary"]:
+
+
+def Split_continue(state: ReadState) -> Literal["Split_The_Problem", "Input_Summary"]:
     """
     Determine routing based on search_switch value.
 
@@ -25,6 +25,7 @@ def Split_continue(state:ReadState) -> Literal["Split_The_Problem", "Input_Summa
             return 'Input_Summary'
     return 'Split_The_Problem'  # 默认情况
 
+
 def Retrieve_continue(state) -> Literal["Verify", "Retrieve_Summary"]:
     """
     Determine routing based on search_switch value.
@@ -43,8 +44,10 @@ def Retrieve_continue(state) -> Literal["Verify", "Retrieve_Summary"]:
         elif search_switch == '1':
             return 'Retrieve_Summary'
     return 'Retrieve_Summary'  # Default based on business logic
+
+
 def Verify_continue(state: ReadState) -> Literal["Summary", "Summary_fails", "content_input"]:
-    status=state.get('verify', '')['status']
+    status = state.get('verify', '')['status']
     # loop_count = counter.get_total()
     if "success" in status:
         # counter.reset()
@@ -53,7 +56,7 @@ def Verify_continue(state: ReadState) -> Literal["Summary", "Summary_fails", "co
         # if loop_count < 2:  # Maximum loop count is 3
         #     return "content_input"
         # else:
-            # counter.reset()
+        # counter.reset()
         return "Summary_fails"
     else:
         # Add default return value to avoid returning None

api/app/core/memory/agent/langgraph_graph/routing/write_router.py

@@ -1,108 +1,139 @@
 import json
 import os
 
+from app.celery_task_scheduler import scheduler
 from app.core.logging_config import get_agent_logger
-from app.core.memory.agent.langgraph_graph.tools.write_tool import  format_parsing,  messages_parse
-from app.core.memory.agent.langgraph_graph.write_graph import make_write_graph, long_term_storage
-
+from app.core.memory.agent.langgraph_graph.tools.write_tool import format_parsing, messages_parse
 from app.core.memory.agent.models.write_aggregate_model import WriteAggregateModel
 from app.core.memory.agent.utils.llm_tools import PROJECT_ROOT_
-from app.core.memory.agent.utils.redis_tool import write_store
 from app.core.memory.agent.utils.redis_tool import count_store
+from app.core.memory.agent.utils.redis_tool import write_store
 from app.core.memory.agent.utils.template_tools import TemplateService
 from app.core.memory.utils.llm.llm_utils import MemoryClientFactory
-from app.db import get_db_context, get_db
+from app.db import get_db_context
 from app.repositories.memory_short_repository import LongTermMemoryRepository
 from app.schemas.memory_agent_schema import AgentMemory_Long_Term
-from app.services.memory_konwledges_server import write_rag
-from app.services.task_service import get_task_memory_write_result
-from app.tasks import write_message_task
 from app.utils.config_utils import resolve_config_id
+
 logger = get_agent_logger(__name__)
 template_root = os.path.join(PROJECT_ROOT_, 'memory', 'agent', 'utils', 'prompt')
 
-async def write_rag_agent(end_user_id, user_message, ai_message, user_rag_memory_id):
-    # RAG 模式：组合消息为字符串格式（保持原有逻辑）
-    combined_message = f"user: {user_message}\nassistant: {ai_message}"
-    await write_rag(end_user_id, combined_message, user_rag_memory_id)
-    logger.info(f'RAG_Agent:{end_user_id};{user_rag_memory_id}')
-async def write(storage_type, end_user_id, user_message, ai_message, user_rag_memory_id, actual_end_user_id,
-                actual_config_id, long_term_messages=[]):
+
+async def write(
+        storage_type,
+        end_user_id,
+        user_message,
+        ai_message,
+        user_rag_memory_id,
+        actual_end_user_id,
+        actual_config_id,
+        long_term_messages=None
+):
     """
-    写入记忆（支持结构化消息）
+    Write memory with structured message support
+
+    Handles memory writing operations for different storage types (Neo4j/RAG).
+    Supports both individual message pairs and batch long-term message processing.
 
     Args:
-        storage_type: 存储类型 (neo4j/rag)
-        end_user_id: 终端用户ID
-        user_message: 用户消息内容
-        ai_message: AI 回复内容
-        user_rag_memory_id: RAG 记忆ID
-        actual_end_user_id: 实际用户ID
-        actual_config_id: 配置ID
+        storage_type: Storage type identifier ("neo4j" or "rag")
+        end_user_id: Terminal user identifier
+        user_message: User message content
+        ai_message: AI response content
+        user_rag_memory_id: RAG memory identifier
+        actual_end_user_id: Actual user identifier for storage
+        actual_config_id: Configuration identifier
+        long_term_messages: Optional list of structured messages for batch processing
 
-    逻辑说明：
-    - RAG 模式：组合 user_message 和 ai_message 为字符串格式，保持原有逻辑不变
-    - Neo4j 模式：使用结构化消息列表
-      1. 如果 user_message 和 ai_message 都不为空：创建配对消息 [user, assistant]
-      2. 如果只有 user_message：创建单条用户消息 [user]（用于历史记忆场景）
-      3. 每条消息会被转换为独立的 Chunk，保留 speaker 字段
+    Logic explanation:
+    - RAG mode: Combines user_message and ai_message into string format, maintains original logic
+    - Neo4j mode: Uses structured message lists
+      1. If both user_message and ai_message are not empty: Creates paired messages [user, assistant]
+      2. If only user_message exists: Creates single user message [user] (for historical memory scenarios)
+      3. Each message is converted to independent Chunk, preserving speaker field
     """
 
-    db = next(get_db())
-    try:
+    if long_term_messages is None:
+        long_term_messages = []
+    with get_db_context() as db:
         actual_config_id = resolve_config_id(actual_config_id, db)
-        # Neo4j 模式：使用结构化消息列表
+        # Neo4j mode: Use structured message lists
         structured_messages = []
 
-        # 始终添加用户消息（如果不为空）
+        # Always add user message (if not empty)
         if isinstance(user_message, str) and user_message.strip() != "":
             structured_messages.append({"role": "user", "content": user_message})
 
-        # 只有当 AI 回复不为空时才添加 assistant 消息
+        # Only add assistant message when AI reply is not empty
         if isinstance(ai_message, str) and ai_message.strip() != "":
             structured_messages.append({"role": "assistant", "content": ai_message})
 
-        # 如果提供了 long_term_messages，使用它替代 structured_messages
+        # If long_term_messages provided, use it to replace structured_messages
         if long_term_messages and isinstance(long_term_messages, list):
             structured_messages = long_term_messages
         elif long_term_messages and isinstance(long_term_messages, str):
-            # 如果是 JSON 字符串，先解析
+            # If it's a JSON string, parse it first
             try:
                 structured_messages = json.loads(long_term_messages)
             except json.JSONDecodeError:
                 logger.error(f"Failed to parse long_term_messages as JSON: {long_term_messages}")
 
-        # 如果没有消息，直接返回
+        # If no messages, return directly
         if not structured_messages:
             logger.warning(f"No messages to write for user {actual_end_user_id}")
             return
 
         logger.info(
             f"[WRITE] Submitting Celery task - user={actual_end_user_id}, messages={len(structured_messages)}, config={actual_config_id}")
-        write_id = write_message_task.delay(
-            actual_end_user_id,  # end_user_id: 用户ID
-            structured_messages,  # message: JSON 字符串格式的消息列表
-            str(actual_config_id),  # config_id: 配置ID字符串
-            storage_type,  # storage_type: "neo4j"
-            user_rag_memory_id or ""  # user_rag_memory_id: RAG记忆ID（Neo4j模式下不使用）
+        # write_id = write_message_task.delay(
+        #     actual_end_user_id,  # end_user_id: User ID
+        #     structured_messages,  # message: JSON string format message list
+        #     str(actual_config_id),  # config_id: Configuration ID string
+        #     storage_type,  # storage_type: "neo4j"
+        #     user_rag_memory_id or ""  # user_rag_memory_id: RAG memory ID (not used in Neo4j mode)
+        # )
+        scheduler.push_task(
+            "app.core.memory.agent.write_message",
+            str(actual_end_user_id),
+            {
+                "end_user_id": str(actual_end_user_id),
+                "message": structured_messages,
+                "config_id": str(actual_config_id),
+                "storage_type": storage_type,
+                "user_rag_memory_id": user_rag_memory_id or ""
+            }
         )
-        logger.info(f"[WRITE] Celery task submitted - task_id={write_id}")
-        write_status = get_task_memory_write_result(str(write_id))
-        logger.info(f'[WRITE] Task result - user={actual_end_user_id}, status={write_status}')
-    finally:
-        db.close()
 
-async def term_memory_save(long_term_messages,actual_config_id,end_user_id,type,scope):
+        # logger.info(f"[WRITE] Celery task submitted - task_id={write_id}")
+        # write_status = get_task_memory_write_result(str(write_id))
+        # logger.info(f'[WRITE] Task result - user={actual_end_user_id}')
+
+
+async def term_memory_save(end_user_id, strategy_type, scope):
+    """
+    Save long-term memory data to database
+
+    Handles the storage of long-term memory data based on different strategies
+    (chunk-based or aggregate-based) and manages the transition from short-term
+    to long-term memory storage.
+
+    Args:
+        end_user_id: User identifier for memory association
+        strategy_type: Memory storage strategy type (STRATEGY_CHUNK or STRATEGY_AGGREGATE)
+        scope: Scope/window size for memory processing
+    """
     with get_db_context() as db_session:
         repo = LongTermMemoryRepository(db_session)
 
-
         from app.core.memory.agent.utils.redis_tool import write_store
         result = write_store.get_session_by_userid(end_user_id)
-        if type==AgentMemory_Long_Term.STRATEGY_CHUNK or AgentMemory_Long_Term.STRATEGY_AGGREGATE:
+        if not result:
+            logger.warning(f"No write data found for user {end_user_id}")
+            return
+        if strategy_type in [AgentMemory_Long_Term.STRATEGY_CHUNK, AgentMemory_Long_Term.STRATEGY_AGGREGATE]:
             data = await format_parsing(result, "dict")
             chunk_data = data[:scope]
-            if len(chunk_data)==scope:
+            if len(chunk_data) == scope:
                 repo.upsert(end_user_id, chunk_data)
                 logger.info(f'---------写入短长期-----------')
         else:
@@ -112,73 +143,101 @@ async def term_memory_save(long_term_messages,actual_config_id,end_user_id,type,
             logger.info(f'写入短长期：')
 
 
+async def window_dialogue(end_user_id, langchain_messages, memory_config, scope):
+    """
+    Process dialogue based on window size and write to Neo4j
 
-'''根据窗口'''
-async def window_dialogue(end_user_id,langchain_messages,memory_config,scope):
-    '''
-    根据窗口获取redis数据,写入neo4j：
-     Args:
-        end_user_id: 终端用户ID
-        memory_config: 内存配置对象
-        langchain_messages：原始数据LIST
-        scope：窗口大小
-    '''
-    scope=scope
-    is_end_user_id = count_store.get_sessions_count(end_user_id)
-    if is_end_user_id is not False:
-        is_end_user_id = count_store.get_sessions_count(end_user_id)[0]
-        redis_messages = count_store.get_sessions_count(end_user_id)[1]
-    if is_end_user_id and int(is_end_user_id) != int(scope):
-        is_end_user_id += 1
-        langchain_messages += redis_messages
-        count_store.update_sessions_count(end_user_id, is_end_user_id, langchain_messages)
-    elif int(is_end_user_id) == int(scope):
+    Manages conversation data based on a sliding window approach. When the window
+    reaches the specified scope size, it triggers long-term memory storage to Neo4j.
+
+    Args:
+        end_user_id: Terminal user identifier
+        memory_config: Memory configuration object containing settings
+        langchain_messages: Original message data list
+        scope: Window size determining when to trigger long-term storage
+    """
+    is_end_user_has_history = count_store.get_sessions_count(end_user_id)
+    if is_end_user_has_history:
+        end_user_visit_count, redis_messages = is_end_user_has_history
+    else:
+        count_store.save_sessions_count(end_user_id, 1, langchain_messages)
+        return
+    end_user_visit_count += 1
+    if end_user_visit_count < scope:
+        redis_messages.extend(langchain_messages)
+        count_store.update_sessions_count(end_user_id, end_user_visit_count, redis_messages)
+    else:
         logger.info('写入长期记忆NEO4J')
-        formatted_messages = (redis_messages)
-        # 获取 config_id（如果 memory_config 是对象，提取 config_id；否则直接使用）
+        redis_messages.extend(langchain_messages)
+        # Get config_id (if memory_config is an object, extract config_id; otherwise use directly)
         if hasattr(memory_config, 'config_id'):
             config_id = memory_config.config_id
         else:
             config_id = memory_config
-        
-        await write(AgentMemory_Long_Term.STORAGE_NEO4J, end_user_id, "", "", None, end_user_id,
-                config_id, formatted_messages)
-        count_store.update_sessions_count(end_user_id, 1, langchain_messages)
-    else:
-        count_store.save_sessions_count(end_user_id, 1, langchain_messages)
+
+        scheduler.push_task(
+            "app.core.memory.agent.write_message",
+            str(end_user_id),
+            {
+                "end_user_id": str(end_user_id),
+                "message": redis_messages,
+                "config_id": str(config_id),
+                "storage_type": AgentMemory_Long_Term.STORAGE_NEO4J,
+                "user_rag_memory_id": ""
+            }
+        )
+        # write_message_task.delay(
+        #     end_user_id,  # end_user_id: User ID
+        #     redis_messages,  # message: JSON string format message list
+        #     config_id,  # config_id: Configuration ID string
+        #     AgentMemory_Long_Term.STORAGE_NEO4J,  # storage_type: "neo4j"
+        #     ""  # user_rag_memory_id: RAG memory ID (not used in Neo4j mode)
+        # )
+        count_store.update_sessions_count(end_user_id, 0, [])
 
 
-"""根据时间"""
-async def memory_long_term_storage(end_user_id,memory_config,time):
-    '''
-    根据时间获取redis数据,写入neo4j：
-     Args:
-        end_user_id: 终端用户ID
-        memory_config: 内存配置对象
-    '''
+async def memory_long_term_storage(end_user_id, memory_config, time):
+    """
+    Process memory storage based on time intervals and write to Neo4j
+
+    Retrieves Redis data based on time intervals and writes it to Neo4j for
+    long-term storage. This function handles time-based memory consolidation.
+
+    Args:
+        end_user_id: Terminal user identifier
+        memory_config: Memory configuration object containing settings
+        time: Time interval for data retrieval
+    """
     long_time_data = write_store.find_user_recent_sessions(end_user_id, time)
-    format_messages = (long_time_data)
-    messages=[]
-    memory_config=memory_config.config_id
+    format_messages = long_time_data
+    messages = []
+    memory_config = memory_config.config_id
     for i in format_messages:
-        message=json.loads(i['Query'])
-        messages+= message
-    if format_messages!=[]:
+        message = json.loads(i['Query'])
+        messages += message
+    if format_messages:
         await write(AgentMemory_Long_Term.STORAGE_NEO4J, end_user_id, "", "", None, end_user_id,
                     memory_config, messages)
-'''聚合判断'''
+
+
 async def aggregate_judgment(end_user_id: str, ori_messages: list, memory_config) -> dict:
     """
-    聚合判断函数：判断输入句子和历史消息是否描述同一事件
+    Aggregation judgment function: determine if input sentence and historical messages describe the same event
+
+    Uses LLM-based analysis to determine whether new messages should be aggregated with existing
+    historical data or stored as separate events. This helps optimize memory storage and retrieval.
     
     Args:
-        end_user_id: 终端用户ID
-        ori_messages: 原始消息列表，格式如 [{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}]
-        memory_config: 内存配置对象
-    """
+        end_user_id: Terminal user identifier
+        ori_messages: Original message list, format like [{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}]
+        memory_config: Memory configuration object containing LLM settings
 
+    Returns:
+        dict: Aggregation judgment result containing is_same_event flag and processed output
+    """
+    history = None
     try:
-        # 1. 获取历史会话数据（使用新方法）
+        # 1. Get historical session data (using new method)
         result = write_store.get_all_sessions_by_end_user_id(end_user_id)
         history = await format_parsing(result)
         if not result:
@@ -210,7 +269,7 @@ async def aggregate_judgment(end_user_id: str, ori_messages: list, memory_config
         output_value = structured.output
         if isinstance(output_value, list):
             output_value = [
-                {"role": msg.role, "content": msg.content} 
+                {"role": msg.role, "content": msg.content}
                 for msg in output_value
             ]
 
@@ -223,16 +282,14 @@ async def aggregate_judgment(end_user_id: str, ori_messages: list, memory_config
             await write("neo4j", end_user_id, "", "", None, end_user_id,
                         memory_config.config_id, output_value)
         return result_dict
-        
+
     except Exception as e:
-        print(f"[aggregate_judgment] 发生错误: {e}")
-        import traceback
-        traceback.print_exc()
-        
+        logger.error(f"[aggregate_judgment] 发生错误: {e}", exc_info=True)
+
         return {
             "is_same_event": False,
             "output": ori_messages,
             "messages": ori_messages,
             "history": history if 'history' in locals() else [],
             "error": str(e)
-        }
+        }

api/app/core/memory/agent/langgraph_graph/tools/tool.py

@@ -2,41 +2,53 @@ import asyncio
 import json
 from datetime import datetime, timedelta
 
-
 from langchain.tools import tool
 from pydantic import BaseModel, Field
 
-
 from app.core.memory.src.search import (
     search_by_temporal,
     search_by_keyword_temporal,
 )
 
+
 def extract_tool_message_content(response):
-    """从agent响应中提取ToolMessage内容和工具名称"""
+    """
+    Extract ToolMessage content and tool names from agent response
+
+    Parses agent response messages to extract tool execution results and metadata.
+    Handles JSON parsing and provides structured access to tool output data.
+
+    Args:
+        response: Agent response dictionary containing messages
+
+    Returns:
+        dict: Dictionary containing tool_name and parsed content, or None if no tool message found
+            - tool_name: Name of the executed tool
+            - content: Parsed tool execution result (JSON or raw text)
+    """
     messages = response.get('messages', [])
 
     for message in messages:
         if hasattr(message, 'tool_call_id') and hasattr(message, 'content'):
-            # 这是一个ToolMessage
+            # This is a ToolMessage
             tool_content = message.content
             tool_name = None
 
-            # 尝试获取工具名称
+            # Try to get tool name
             if hasattr(message, 'name'):
                 tool_name = message.name
             elif hasattr(message, 'tool_name'):
                 tool_name = message.tool_name
 
             try:
-                # 解析JSON内容
+                # Parse JSON content
                 parsed_content = json.loads(tool_content)
                 return {
                     'tool_name': tool_name,
                     'content': parsed_content
                 }
             except json.JSONDecodeError:
-                # 如果不是JSON格式，直接返回内容
+                # If not JSON format, return content directly
                 return {
                     'tool_name': tool_name,
                     'content': tool_content
@@ -46,38 +58,61 @@ def extract_tool_message_content(response):
 
 
 class TimeRetrievalInput(BaseModel):
-    """时间检索工具的输入模式"""
+    """
+    Input schema for time retrieval tool
+
+    Defines the expected input parameters for time-based retrieval operations.
+    Used for validation and documentation of tool parameters.
+
+    Attributes:
+        context: User input query content for search
+        end_user_id: Group ID for filtering search results, defaults to test user
+    """
     context: str = Field(description="用户输入的查询内容")
     end_user_id: str = Field(default="88a459f5_text09", description="组ID，用于过滤搜索结果")
 
+
 def create_time_retrieval_tool(end_user_id: str):
     """
-    创建一个带有特定end_user_id的TimeRetrieval工具（同步版本），用于按时间范围搜索语句(Statements)
+    Create a TimeRetrieval tool with specific end_user_id (synchronous version) for searching statements by time range
+
+    Creates a specialized time-based retrieval tool that searches for statements within
+    specified time ranges. Includes field cleaning functionality to remove unnecessary
+    metadata from search results.
+
+    Args:
+        end_user_id: User identifier for scoping search results
+
+    Returns:
+        function: Configured TimeRetrievalWithGroupId tool function
     """
-    
+
     def clean_temporal_result_fields(data):
         """
-        清理时间搜索结果中不需要的字段，并修改结构
+        Clean unnecessary fields from temporal search results and modify structure
+
+        Removes metadata fields that are not needed for end-user consumption and
+        restructures the response format for better usability.
         
         Args:
-            data: 要清理的数据
+            data: Data to be cleaned (dict, list, or other types)
             
         Returns:
-            清理后的数据
+            Cleaned data with unnecessary fields removed
         """
-        # 需要过滤的字段列表
+        # List of fields to filter out
         fields_to_remove = {
-            'id', 'apply_id', 'user_id', 'chunk_id', 'created_at', 
+            'id', 'apply_id', 'user_id', 'chunk_id', 'created_at',
             'valid_at', 'invalid_at', 'statement_ids'
         }
-        
+
         if isinstance(data, dict):
             cleaned = {}
             for key, value in data.items():
                 if key == 'statements' and isinstance(value, dict) and 'statements' in value:
-                    # 将 statements: {"statements": [...]} 改为 time_search: {"statements": [...]}
+                    # Change statements: {"statements": [...]} to time_search: {"statements": [...]}
                     cleaned_value = clean_temporal_result_fields(value)
-                    # 进一步将内部的 statements 改为 time_search
+                    # Further change internal statements to time_search
                     if 'statements' in cleaned_value:
                         cleaned['results'] = {
                             'time_search': cleaned_value['statements']
@@ -91,26 +126,35 @@ def create_time_retrieval_tool(end_user_id: str):
             return [clean_temporal_result_fields(item) for item in data]
         else:
             return data
-    
+
     @tool
-    def TimeRetrievalWithGroupId(context: str, start_date: str = None, end_date: str = None, end_user_id_param: str = None, clean_output: bool = True) -> str:
+    def TimeRetrievalWithGroupId(context: str, start_date: str = None, end_date: str = None,
+                                 end_user_id_param: str = None, clean_output: bool = True) -> str:
         """
-        优化的时间检索工具，只结合时间范围搜索（同步版本），自动过滤不需要的元数据字段
-        显式接收参数：
-        - context: 查询上下文内容
-        - start_date: 开始时间（可选，格式：YYYY-MM-DD）
-        - end_date: 结束时间（可选，格式：YYYY-MM-DD）
-        - end_user_id_param: 组ID（可选，用于覆盖默认组ID）
-        - clean_output: 是否清理输出中的元数据字段
-        -end_date 需要根据用户的描述获取结束的时间，输出格式用strftime("%Y-%m-%d")
+        Optimized time retrieval tool, combines time range search only (synchronous version), automatically filters unnecessary metadata fields
+
+        Performs time-based search operations with automatic metadata filtering. Supports
+        flexible date range specification and provides clean, user-friendly output.
+
+        Explicit parameters:
+        - context: Query context content
+        - start_date: Start time (optional, format: YYYY-MM-DD)
+        - end_date: End time (optional, format: YYYY-MM-DD)
+        - end_user_id_param: Group ID (optional, overrides default group ID)
+        - clean_output: Whether to clean metadata fields from output
+        - end_date needs to be obtained based on user description, output format uses strftime("%Y-%m-%d")
+
+        Returns:
+            str: JSON formatted search results with temporal data
         """
+
         async def _async_search():
-            # 使用传入的参数或默认值
+            # Use passed parameters or default values
             actual_end_user_id = end_user_id_param or end_user_id
             actual_end_date = end_date or datetime.now().strftime("%Y-%m-%d")
             actual_start_date = start_date or (datetime.now() - timedelta(days=7)).strftime("%Y-%m-%d")
             
-            # 基本时间搜索
+            # Basic time search
             results = await search_by_temporal(
                 end_user_id=actual_end_user_id,
                 start_date=actual_start_date,
@@ -118,33 +162,43 @@ def create_time_retrieval_tool(end_user_id: str):
                 limit=10
             )
             
-            # 清理结果中不需要的字段
+            # Clean unnecessary fields from results
             if clean_output:
                 cleaned_results = clean_temporal_result_fields(results)
             else:
                 cleaned_results = results
 
             return json.dumps(cleaned_results, ensure_ascii=False, indent=2)
-        
+
         return asyncio.run(_async_search())
 
     @tool
-    def KeywordTimeRetrieval(context: str, days_back: int = 7, start_date: str = None, end_date: str = None, clean_output: bool = True) -> str:
+    def KeywordTimeRetrieval(context: str, days_back: int = 7, start_date: str = None, end_date: str = None,
+                             clean_output: bool = True) -> str:
         """
-        优化的关键词时间检索工具，结合关键词和时间范围搜索（同步版本），自动过滤不需要的元数据字段
-        显式接收参数：
-        - context: 查询内容
-        - days_back: 向前搜索的天数，默认7天
-        - start_date: 开始时间（可选，格式：YYYY-MM-DD）
-        - end_date: 结束时间（可选，格式：YYYY-MM-DD）
-        - clean_output: 是否清理输出中的元数据字段
-        - end_date 需要根据用户的描述获取结束的时间，输出格式用strftime("%Y-%m-%d")
+        Optimized keyword time retrieval tool, combines keyword and time range search (synchronous version), automatically filters unnecessary metadata fields
+
+        Performs combined keyword and temporal search operations with automatic metadata
+        filtering. Provides more targeted search results by combining content relevance
+        with time-based filtering.
+
+        Explicit parameters:
+        - context: Query content for keyword matching
+        - days_back: Number of days to search backwards, default 7 days
+        - start_date: Start time (optional, format: YYYY-MM-DD)
+        - end_date: End time (optional, format: YYYY-MM-DD)
+        - clean_output: Whether to clean metadata fields from output
+        - end_date needs to be obtained based on user description, output format uses strftime("%Y-%m-%d")
+
+        Returns:
+            str: JSON formatted search results combining keyword and temporal data
         """
+
         async def _async_search():
             actual_end_date = end_date or datetime.now().strftime("%Y-%m-%d")
             actual_start_date = start_date or (datetime.now() - timedelta(days=days_back)).strftime("%Y-%m-%d")
 
-            # 关键词时间搜索
+            # Keyword time search
             results = await search_by_keyword_temporal(
                 query_text=context,
                 end_user_id=end_user_id,
@@ -153,7 +207,7 @@ def create_time_retrieval_tool(end_user_id: str):
                 limit=15
             )
             
-            # 清理结果中不需要的字段
+            # Clean unnecessary fields from results
             if clean_output:
                 cleaned_results = clean_temporal_result_fields(results)
             else:
@@ -162,51 +216,61 @@ def create_time_retrieval_tool(end_user_id: str):
             return json.dumps(cleaned_results, ensure_ascii=False, indent=2)
 
         return asyncio.run(_async_search())
-    
+
     return TimeRetrievalWithGroupId
 
 
 def create_hybrid_retrieval_tool_async(memory_config, **search_params):
     """
-    创建混合检索工具，使用run_hybrid_search进行混合检索，优化输出格式并过滤不需要的字段
+    Create hybrid retrieval tool using run_hybrid_search for hybrid retrieval, optimize output format and filter unnecessary fields
+
+    Creates an advanced hybrid search tool that combines multiple search strategies
+    (keyword, vector, hybrid) with automatic result cleaning and formatting.
     
     Args:
-        memory_config: 内存配置对象
-        **search_params: 搜索参数，包含end_user_id, limit, include等
+        memory_config: Memory configuration object containing LLM and search settings
+        **search_params: Search parameters including end_user_id, limit, include, etc.
+
+    Returns:
+        function: Configured HybridSearch tool function with async capabilities
     """
-    
+
     def clean_result_fields(data):
         """
-        递归清理结果中不需要的字段
+        Recursively clean unnecessary fields from results
+
+        Removes metadata fields that are not needed for end-user consumption,
+        improving readability and reducing response size.
         
         Args:
-            data: 要清理的数据（可能是字典、列表或其他类型）
+            data: Data to be cleaned (can be dict, list, or other types)
             
         Returns:
-            清理后的数据
+            Cleaned data with unnecessary fields removed
         """
-        # 需要过滤的字段列表
-        # TODO: fact_summary 功能暂时禁用，待后续开发完善后启用
+        # List of fields to filter out
+        # TODO: fact_summary functionality temporarily disabled, will be enabled after future development
         fields_to_remove = {
-            'invalid_at', 'valid_at', 'chunk_id_from_rel', 'entity_ids', 
-            'expired_at', 'created_at', 'chunk_id', 'id', 'apply_id', 
-            'user_id', 'statement_ids', 'updated_at',"chunk_ids"  ,"fact_summary"
+            'invalid_at', 'valid_at', 'chunk_id_from_rel', 'entity_ids',
+            'expired_at', 'created_at', 'chunk_id', 'apply_id',
+            'user_id', 'statement_ids', 'updated_at', "chunk_ids", "fact_summary"
         }
-        
+        # 注意：'id' 字段保留，community 展开时需要用 community id 查询成员 statements
+
         if isinstance(data, dict):
-            # 对字典进行清理
+            # Clean dictionary
             cleaned = {}
             for key, value in data.items():
                 if key not in fields_to_remove:
-                    cleaned[key] = clean_result_fields(value)  # 递归清理嵌套数据
+                    cleaned[key] = clean_result_fields(value)  # Recursively clean nested data
             return cleaned
         elif isinstance(data, list):
-            # 对列表中的每个元素进行清理
+            # Clean each element in list
             return [clean_result_fields(item) for item in data]
         else:
-            # 其他类型直接返回
+            # Return other types directly
             return data
-    
+
     @tool
     async def HybridSearch(
         context: str, 
@@ -216,57 +280,63 @@ def create_hybrid_retrieval_tool_async(memory_config, **search_params):
         rerank_alpha: float = 0.6,
         use_forgetting_rerank: bool = False,
         use_llm_rerank: bool = False,
-        clean_output: bool = True  # 新增：是否清理输出字段
+        clean_output: bool = True  # New: whether to clean output fields
     ) -> str:
         """
-        优化的混合检索工具，支持关键词、向量和混合搜索，自动过滤不需要的元数据字段
+        Optimized hybrid retrieval tool, supports keyword, vector and hybrid search, automatically filters unnecessary metadata fields
+
+        Provides comprehensive search capabilities combining multiple search strategies
+        with intelligent result ranking and automatic metadata filtering for clean output.
         
         Args:
-            context: 查询内容
-            search_type: 搜索类型 ('keyword', 'embedding', 'hybrid')
-            limit: 结果数量限制
-            end_user_id: 组ID，用于过滤搜索结果
-            rerank_alpha: 重排序权重参数
-            use_forgetting_rerank: 是否使用遗忘重排序
-            use_llm_rerank: 是否使用LLM重排序
-            clean_output: 是否清理输出中的元数据字段
+            context: Query content for search
+            search_type: Search type ('keyword', 'embedding', 'hybrid')
+            limit: Result quantity limit
+            end_user_id: Group ID for filtering search results
+            rerank_alpha: Reranking weight parameter for result scoring
+            use_forgetting_rerank: Whether to use forgetting-based reranking
+            use_llm_rerank: Whether to use LLM-based reranking
+            clean_output: Whether to clean metadata fields from output
+
+        Returns:
+            str: JSON formatted comprehensive search results
         """
         try:
-            # 导入run_hybrid_search函数
+            # Import run_hybrid_search function
             from app.core.memory.src.search import run_hybrid_search
             
-            # 合并参数，优先使用传入的参数
+            # Merge parameters, prioritize passed parameters
             final_params = {
                 "query_text": context,
                 "search_type": search_type,
                 "end_user_id": end_user_id or search_params.get("end_user_id"),
                 "limit": limit or search_params.get("limit", 10),
-                "include": search_params.get("include", ["summaries", "statements", "chunks", "entities"]),
-                "output_path": None,  # 不保存到文件
+                "include": search_params.get("include", ["summaries", "statements", "chunks", "entities", "communities"]),
+                "output_path": None,  # Don't save to file
                 "memory_config": memory_config,
                 "rerank_alpha": rerank_alpha,
                 "use_forgetting_rerank": use_forgetting_rerank,
                 "use_llm_rerank": use_llm_rerank
             }
             
-            # 执行混合检索
+            # Execute hybrid retrieval
             raw_results = await run_hybrid_search(**final_params)
             
-            # 清理结果中不需要的字段
+            # Clean unnecessary fields from results
             if clean_output:
                 cleaned_results = clean_result_fields(raw_results)
             else:
                 cleaned_results = raw_results
             
-            # 格式化返回结果
+            # Format return results
             formatted_results = {
                 "search_query": context,
                 "search_type": search_type,
                 "results": cleaned_results
             }
-            
+
             return json.dumps(formatted_results, ensure_ascii=False, indent=2, default=str)
-            
+
         except Exception as e:
             error_result = {
                 "error": f"混合检索失败: {str(e)}",
@@ -275,38 +345,52 @@ def create_hybrid_retrieval_tool_async(memory_config, **search_params):
                 "timestamp": datetime.now().isoformat()
             }
             return json.dumps(error_result, ensure_ascii=False, indent=2)
-    
+
     return HybridSearch
 
 
 def create_hybrid_retrieval_tool_sync(memory_config, **search_params):
     """
-    创建同步版本的混合检索工具，优化输出格式并过滤不需要的字段
+    Create synchronous version of hybrid retrieval tool, optimize output format and filter unnecessary fields
+
+    Creates a synchronous wrapper around the async hybrid search functionality,
+    making it compatible with synchronous tool execution environments.
     
     Args:
-        memory_config: 内存配置对象
-        **search_params: 搜索参数
+        memory_config: Memory configuration object containing search settings
+        **search_params: Search parameters for configuration
+
+    Returns:
+        function: Configured HybridSearchSync tool function
     """
+
     @tool
     def HybridSearchSync(
-        context: str, 
-        search_type: str = "hybrid",
-        limit: int = 10,
-        end_user_id: str = None,
-        clean_output: bool = True
+            context: str,
+            search_type: str = "hybrid",
+            limit: int = 10,
+            end_user_id: str = None,
+            clean_output: bool = True
     ) -> str:
         """
-        优化的混合检索工具（同步版本），自动过滤不需要的元数据字段
+        Optimized hybrid retrieval tool (synchronous version), automatically filters unnecessary metadata fields
+
+        Provides the same hybrid search capabilities as the async version but in a
+        synchronous execution context. Automatically handles async-to-sync conversion.
         
         Args:
-            context: 查询内容
-            search_type: 搜索类型 ('keyword', 'embedding', 'hybrid')
-            limit: 结果数量限制
-            end_user_id: 组ID，用于过滤搜索结果
-            clean_output: 是否清理输出中的元数据字段
+            context: Query content for search
+            search_type: Search type ('keyword', 'embedding', 'hybrid')
+            limit: Result quantity limit
+            end_user_id: Group ID for filtering search results
+            clean_output: Whether to clean metadata fields from output
+
+        Returns:
+            str: JSON formatted search results
         """
+
         async def _async_search():
-            # 创建异步工具并执行
+            # Create async tool and execute
             async_tool = create_hybrid_retrieval_tool_async(memory_config, **search_params)
             return await async_tool.ainvoke({
                 "context": context,
@@ -315,7 +399,7 @@ def create_hybrid_retrieval_tool_sync(memory_config, **search_params):
                 "end_user_id": end_user_id,
                 "clean_output": clean_output
             })
-        
+
         return asyncio.run(_async_search())
-    
-    return HybridSearchSync
+
+    return HybridSearchSync

api/app/core/memory/agent/langgraph_graph/tools/write_tool.py

@@ -1,20 +1,28 @@
 import json
 
 from langchain_core.messages import HumanMessage, AIMessage
-async def format_parsing(messages: list,type:str='string'):
+
+
+async def format_parsing(messages: list, type: str = 'string'):
     """
-    格式化解析消息列表
+    Format and parse message lists into different output types
+
+    Processes message lists from storage and converts them into either string format
+    or dictionary format based on the specified type parameter. Handles JSON parsing
+    and role-based message organization.
     
     Args:
-        messages: 消息列表
-        type: 返回类型 ('string' 或 'dict')
+        messages: List of message objects from storage containing message data
+        type: Return type specification ('string' for text format, 'dict' for key-value pairs)
         
     Returns:
-        格式化后的消息列表
+        list: Formatted message list in the specified format
+            - 'string': List of formatted text messages with role prefixes
+            - 'dict': List of dictionaries mapping user messages to AI responses
     """
     result = []
-    user=[]
-    ai=[]
+    user = []
+    ai = []
 
     for message in messages:
         hstory_messages = message['messages']
@@ -24,25 +32,38 @@ async def format_parsing(messages: list,type:str='string'):
                 role = content['role']
                 content = content['content']
                 if type == "string":
-                    if role == 'human' or role=="user":
+                    if role == 'human' or role == "user":
                         content = '用户:' + content
                     else:
                         content = 'AI:' + content
                     result.append(content)
-                if type == "dict" :
-                    if role == 'human'  or role=="user":
-                        user.append( content)
+                if type == "dict":
+                    if role == 'human' or role == "user":
+                        user.append(content)
                     else:
                         ai.append(content)
     if type == "dict":
-        for key,values in zip(user,ai):
-            result.append({key:values})
+        for key, values in zip(user, ai):
+            result.append({key: values})
     return result
 
+
 async def messages_parse(messages: list | dict):
-    user=[]
-    ai=[]
-    database=[]
+    """
+    Parse messages from storage format into user-AI conversation pairs
+
+    Extracts and organizes conversation data from stored message format,
+    separating user and AI messages and pairing them for database storage.
+
+    Args:
+        messages: List or dictionary containing stored message data with Query fields
+
+    Returns:
+        list: List of dictionaries containing user-AI message pairs for database storage
+    """
+    user = []
+    ai = []
+    database = []
     for message in messages:
         Query = message['Query']
         Query = json.loads(Query)
@@ -54,10 +75,23 @@ async def messages_parse(messages: list | dict):
                 ai.append(data['content'])
     for key, values in zip(user, ai):
         database.append({key, values})
-    return  database
+    return database
 
 
-async def agent_chat_messages(user_content,ai_content):
+async def agent_chat_messages(user_content, ai_content):
+    """
+    Create structured chat message format for agent conversations
+
+    Formats user and AI content into a standardized message structure suitable
+    for agent processing and storage. Creates role-based message objects.
+
+    Args:
+        user_content: User's message content string
+        ai_content: AI's response content string
+
+    Returns:
+        list: List of structured message dictionaries with role and content fields
+    """
     messages = [
         {
             "role": "user",

api/app/core/memory/agent/langgraph_graph/write_graph.py

@@ -1,104 +1,94 @@
-import asyncio
-import json
-import sys
 import warnings
-from contextlib import asynccontextmanager
-from langgraph.constants import END, START
-from langgraph.graph import StateGraph
 
-from app.db import get_db, get_db_context
 from app.core.logging_config import get_agent_logger
-from app.core.memory.agent.utils.llm_tools import WriteState
-from app.core.memory.agent.langgraph_graph.nodes.write_nodes import write_node
+from app.core.memory.agent.langgraph_graph.routing.write_router import memory_long_term_storage, window_dialogue, \
+    aggregate_judgment
+from app.core.memory.agent.utils.redis_tool import write_store
+from app.db import get_db_context
 from app.schemas.memory_agent_schema import AgentMemory_Long_Term
 from app.services.memory_config_service import MemoryConfigService
-
+from app.services.memory_konwledges_server import write_rag
 
 warnings.filterwarnings("ignore", category=RuntimeWarning)
 logger = get_agent_logger(__name__)
 
-if sys.platform.startswith("win"):
-    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
 
-
-@asynccontextmanager
-async def make_write_graph():
+async def long_term_storage(
+        long_term_type: str,
+        langchain_messages: list,
+        memory_config_id: str,
+        end_user_id: str,
+        scope: int = 6
+):
     """
-    Create a write graph workflow for memory operations.
+    Handle long-term memory storage with different strategies
+
+    Supports multiple storage strategies including chunk-based, time-based,
+    and aggregate judgment approaches for long-term memory persistence.
 
     Args:
-        user_id: User identifier
-        tools: MCP tools loaded from session
-        apply_id: Application identifier
-        end_user_id: Group identifier
-        memory_config: MemoryConfig object containing all configuration
+        long_term_type: Storage strategy type ('chunk', 'time', 'aggregate')
+        langchain_messages: List of messages to store
+        memory_config_id: Memory configuration identifier
+        end_user_id: User group identifier
+        scope: Scope parameter for chunk-based storage (default: 6)
     """
-    workflow = StateGraph(WriteState)
-    workflow.add_node("save_neo4j", write_node)
-    workflow.add_edge(START, "save_neo4j")
-    workflow.add_edge("save_neo4j", END)
+    if langchain_messages is None:
+        langchain_messages = []
 
-    graph = workflow.compile()
-
-    yield graph
-
-async def long_term_storage(long_term_type:str="chunk",langchain_messages:list=[],memory_config:str='',end_user_id:str='',scope:int=6):
-    from app.core.memory.agent.langgraph_graph.routing.write_router import memory_long_term_storage, window_dialogue,aggregate_judgment
-    from app.core.memory.agent.utils.redis_tool import write_store
-    write_store.save_session_write(end_user_id,  (langchain_messages))
+    write_store.save_session_write(end_user_id, langchain_messages)
     # 获取数据库会话
     with get_db_context() as db_session:
         config_service = MemoryConfigService(db_session)
         memory_config = config_service.load_memory_config(
-            config_id=memory_config,  # 改为整数
+            config_id=memory_config_id,  # 改为整数
             service_name="MemoryAgentService"
         )
-        if long_term_type=='chunk':
-            '''方案一:对话窗口6轮对话'''
-            await window_dialogue(end_user_id,langchain_messages,memory_config,scope)
-        if long_term_type=='time':
-            """时间"""
-            await memory_long_term_storage(end_user_id, memory_config,5)
-        if  long_term_type=='aggregate':
-            """方案三：聚合判断"""
+        if long_term_type == AgentMemory_Long_Term.STRATEGY_CHUNK:
+            # Dialogue window with 6 rounds of conversation
+            await window_dialogue(end_user_id, langchain_messages, memory_config, scope)
+        if long_term_type == AgentMemory_Long_Term.STRATEGY_TIME:
+            # Time-based strategy
+            await memory_long_term_storage(end_user_id, memory_config, AgentMemory_Long_Term.TIME_SCOPE)
+        if long_term_type == AgentMemory_Long_Term.STRATEGY_AGGREGATE:
+            # Aggregate judgment
             await aggregate_judgment(end_user_id, langchain_messages, memory_config)
 
 
+async def write_long_term(
+        storage_type: str,
+        end_user_id: str,
+        messages: list[dict],
+        user_rag_memory_id: str,
+        actual_config_id: str
+):
+    """
+    Write long-term memory with different storage types
 
-async def write_long_term(storage_type,end_user_id,message_chat,aimessages,user_rag_memory_id,actual_config_id):
-    from app.core.memory.agent.langgraph_graph.routing.write_router import write_rag_agent
+    Handles both RAG-based storage and traditional memory storage approaches.
+    For traditional storage, uses chunk-based strategy with paired user-AI messages.
+
+    Args:
+        storage_type: Type of storage (RAG or traditional)
+        end_user_id: User group identifier
+        messages: message list
+        user_rag_memory_id: RAG memory identifier
+        actual_config_id: Actual configuration ID
+    """
     from app.core.memory.agent.langgraph_graph.routing.write_router import term_memory_save
-    from app.core.memory.agent.langgraph_graph.tools.write_tool import  agent_chat_messages
     if storage_type == AgentMemory_Long_Term.STORAGE_RAG:
-        await write_rag_agent(end_user_id, message_chat, aimessages, user_rag_memory_id)
+        message_content = []
+        for message in messages:
+            message_content.append(f'{message.get("role")}:{message.get("content")}')
+        messages_string = "\n".join(message_content)
+        await write_rag(end_user_id, messages_string, user_rag_memory_id)
     else:
-        # AI 回复写入（用户消息和 AI 回复配对，一次性写入完整对话）
+        # AI reply writing (user messages and AI replies paired, written as complete dialogue at once)
         CHUNK = AgentMemory_Long_Term.STRATEGY_CHUNK
         SCOPE = AgentMemory_Long_Term.DEFAULT_SCOPE
-        long_term_messages = await agent_chat_messages(message_chat, aimessages)
-        await long_term_storage(long_term_type=CHUNK, langchain_messages=long_term_messages,
-                                memory_config=actual_config_id, end_user_id=end_user_id, scope=SCOPE)
-        await term_memory_save(long_term_messages, actual_config_id, end_user_id, CHUNK, scope=SCOPE)
-
-# async def main():
-#     """主函数 - 运行工作流"""
-#     langchain_messages = [
-#     {
-#       "role": "user",
-#       "content": "今天周五去爬山"
-#     },
-#     {
-#       "role": "assistant",
-#       "content": "好耶"
-#     }
-#
-#   ]
-#     end_user_id = '837fee1b-04a2-48ee-94d7-211488908940'  # 组ID
-#     memory_config="08ed205c-0f05-49c3-8e0c-a580d28f5fd4"
-#     await long_term_storage(long_term_type="chunk",langchain_messages=langchain_messages,memory_config=memory_config,end_user_id=end_user_id,scope=2)
-#
-#
-#
-# if __name__ == "__main__":
-#     import asyncio
-#     asyncio.run(main())
+        await long_term_storage(long_term_type=CHUNK,
+                                langchain_messages=messages,
+                                memory_config_id=actual_config_id,
+                                end_user_id=end_user_id,
+                                scope=SCOPE)
+        await term_memory_save(end_user_id, CHUNK, scope=SCOPE)

api/app/core/memory/agent/services/search_service.py

@@ -7,21 +7,88 @@ and deduplication.
 from typing import List, Tuple, Optional
 
 from app.core.logging_config import get_agent_logger
+from app.core.memory.enums import Neo4jNodeType
 from app.core.memory.src.search import run_hybrid_search
 from app.core.memory.utils.data.text_utils import escape_lucene_query
 
-
 logger = get_agent_logger(__name__)
 
+# 需要从展开结果中过滤的字段（含 Neo4j DateTime，不可 JSON 序列化）
+_EXPAND_FIELDS_TO_REMOVE = {
+    'invalid_at', 'valid_at', 'chunk_id_from_rel', 'entity_ids',
+    'expired_at', 'created_at', 'chunk_id', 'apply_id',
+    'user_id', 'statement_ids', 'updated_at', 'chunk_ids', 'fact_summary'
+}
+
+
+def _clean_expand_fields(obj):
+    """递归过滤展开结果中不可序列化的字段（DateTime 等）。"""
+    if isinstance(obj, dict):
+        return {k: _clean_expand_fields(v) for k, v in obj.items() if k not in _EXPAND_FIELDS_TO_REMOVE}
+    if isinstance(obj, list):
+        return [_clean_expand_fields(i) for i in obj]
+    return obj
+
+
+async def expand_communities_to_statements(
+        community_results: List[dict],
+        end_user_id: str,
+        existing_content: str = "",
+        limit: int = 10,
+) -> Tuple[List[dict], List[str]]:
+    """
+    社区展开 helper：给定命中的 community 列表，拉取关联 Statement。
+
+    - 对展开结果去重（过滤已在 existing_content 中出现的文本）
+    - 过滤不可序列化字段
+    - 返回 (cleaned_expanded_stmts, new_texts)
+      - cleaned_expanded_stmts: 可直接写回 raw_results 的列表
+      - new_texts: 去重后新增的 statement 文本列表，用于追加到 clean_content
+    """
+    community_ids = [r.get("id") for r in community_results if r.get("id")]
+    if not community_ids or not end_user_id:
+        return [], []
+
+    from app.repositories.neo4j.graph_search import search_graph_community_expand
+    from app.repositories.neo4j.neo4j_connector import Neo4jConnector
+
+    connector = Neo4jConnector()
+    try:
+        result = await search_graph_community_expand(
+            connector=connector,
+            community_ids=community_ids,
+            end_user_id=end_user_id,
+            limit=limit,
+        )
+    except Exception as e:
+        logger.warning(f"[expand_communities] 社区展开检索失败，跳过: {e}")
+        return [], []
+    finally:
+        await connector.close()
+
+    expanded_stmts = result.get("expanded_statements", [])
+    if not expanded_stmts:
+        return [], []
+
+    existing_lines = set(existing_content.splitlines())
+    new_texts = [
+        s["statement"] for s in expanded_stmts
+        if s.get("statement") and s["statement"] not in existing_lines
+    ]
+    cleaned = _clean_expand_fields(expanded_stmts)
+    logger.info(
+        f"[expand_communities] 展开 {len(expanded_stmts)} 条 statements，新增 {len(new_texts)} 条，community_ids={community_ids}")
+    return cleaned, new_texts
+
 
 class SearchService:
     """Service for executing hybrid search and processing results."""
-    
+
     def __init__(self):
         """Initialize the search service."""
         logger.info("SearchService initialized")
-    
-    def extract_content_from_result(self, result: dict) -> str:
+
+    def extract_content_from_result(self, result: dict, node_type: str = "") -> str:
         """
         Extract only meaningful content from search results, dropping all metadata.
         
@@ -30,35 +97,50 @@ class SearchService:
         - Entities: extract 'name' and 'fact_summary' fields
         - Summaries: extract 'content' field
         - Chunks: extract 'content' field
+        - Communities: extract 'content' field (c.summary), prefixed with community name
         
         Args:
             result: Search result dictionary
+            node_type: Hint for node type ("community", "summary", etc.)
             
         Returns:
             Clean content string without metadata
         """
         if not isinstance(result, dict):
             return str(result)
-        
+
         content_parts = []
-        
+
         # Statements: extract statement field
-        if 'statement' in result and result['statement']:
-            content_parts.append(result['statement'])
-        
-        # Summaries/Chunks: extract content field
-        if 'content' in result and result['content']:
+        if Neo4jNodeType.STATEMENT in result and result[Neo4jNodeType.STATEMENT]:
+            content_parts.append(result[Neo4jNodeType.STATEMENT])
+
+        # Community 节点：有 member_count 或 core_entities 字段，或 node_type 明确指定
+        # 用 "[主题：{name}]" 前缀区分，让 LLM 知道这是主题级摘要
+        is_community = (
+                node_type == Neo4jNodeType.COMMUNITY
+                or 'member_count' in result
+                or 'core_entities' in result
+        )
+        if is_community:
+            name = result.get('name', '')
+            content = result.get('content', '')
+            if content:
+                prefix = f"[主题：{name}] " if name else ""
+                content_parts.append(f"{prefix}{content}")
+        elif 'content' in result and result['content']:
+            # Summaries / Chunks
             content_parts.append(result['content'])
-        
+
         # Entities: extract name and fact_summary (commented out in original)
         # if 'name' in result and result['name']:
         #     content_parts.append(result['name'])
         #     if result.get('fact_summary'):
         #         content_parts.append(result['fact_summary'])
-        
+
         # Return concatenated content or empty string
         return '\n'.join(content_parts) if content_parts else ""
-    
+
     def clean_query(self, query: str) -> str:
         """
         Clean and escape query text for Lucene.
@@ -74,32 +156,33 @@ class SearchService:
             Cleaned and escaped query string
         """
         q = str(query).strip()
-        
+
         # Remove wrapping quotes
         if (q.startswith("'") and q.endswith("'")) or (
-            q.startswith('"') and q.endswith('"')
+                q.startswith('"') and q.endswith('"')
         ):
             q = q[1:-1]
-        
+
         # Remove newlines and carriage returns
         q = q.replace('\r', ' ').replace('\n', ' ').strip()
-        
+
         # Apply Lucene escaping
         q = escape_lucene_query(q)
-        
+
         return q
-    
+
     async def execute_hybrid_search(
-        self,
-        end_user_id: str,
-        question: str,
-        limit: int = 5,
-        search_type: str = "hybrid",
-        include: Optional[List[str]] = None,
-        rerank_alpha: float = 0.4,
-        output_path: str = "search_results.json",
-        return_raw_results: bool = False,
-        memory_config = None
+            self,
+            end_user_id: str,
+            question: str,
+            limit: int = 5,
+            search_type: str = "hybrid",
+            include: Optional[List[str]] = None,
+            rerank_alpha: float = 0.4,
+            output_path: str = "search_results.json",
+            return_raw_results: bool = False,
+            memory_config=None,
+            expand_communities: bool = True,
     ) -> Tuple[str, str, Optional[dict]]:
         """
         Execute hybrid search and return clean content.
@@ -114,17 +197,19 @@ class SearchService:
             output_path: Path to save search results (default: "search_results.json")
             return_raw_results: If True, also return the raw search results as third element (default: False)
             memory_config: Memory configuration object (required)
+            expand_communities: If True, expand community hits to member statements (default: True).
+                                 Set to False for quick-summary paths that only need community-level text.
         
         Returns:
             Tuple of (clean_content, cleaned_query, raw_results)
             raw_results is None if return_raw_results=False
         """
         if include is None:
-            include = ["statements", "chunks", "entities", "summaries"]
-        
+            include = [Neo4jNodeType.STATEMENT, Neo4jNodeType.CHUNK, Neo4jNodeType.EXTRACTEDENTITY, Neo4jNodeType.MEMORYSUMMARY, Neo4jNodeType.COMMUNITY]
+
         # Clean query
         cleaned_query = self.clean_query(question)
-        
+
         try:
             # Execute search
             answer = await run_hybrid_search(
@@ -137,18 +222,18 @@ class SearchService:
                 memory_config=memory_config,
                 rerank_alpha=rerank_alpha
             )
-            
+
             # Extract results based on search type and include parameter
             # Prioritize summaries as they contain synthesized contextual information
             answer_list = []
-            
+
             # For hybrid search, use reranked_results
             if search_type == "hybrid":
                 reranked_results = answer.get('reranked_results', {})
-                
-                # Priority order: summaries first (most contextual), then statements, chunks, entities
-                priority_order = ['summaries', 'statements', 'chunks', 'entities']
-                
+
+                # Priority order: summaries first (most contextual), then communities, statements, chunks, entities
+                priority_order = [Neo4jNodeType.STATEMENT, Neo4jNodeType.CHUNK, Neo4jNodeType.EXTRACTEDENTITY, Neo4jNodeType.MEMORYSUMMARY, Neo4jNodeType.COMMUNITY]
+
                 for category in priority_order:
                     if category in include and category in reranked_results:
                         category_results = reranked_results[category]
@@ -157,33 +242,46 @@ class SearchService:
             else:
                 # For keyword or embedding search, results are directly in answer dict
                 # Apply same priority order
-                priority_order = ['summaries', 'statements', 'chunks', 'entities']
-                
+                priority_order = [Neo4jNodeType.STATEMENT, Neo4jNodeType.CHUNK, Neo4jNodeType.EXTRACTEDENTITY, Neo4jNodeType.MEMORYSUMMARY, Neo4jNodeType.COMMUNITY]
+
                 for category in priority_order:
                     if category in include and category in answer:
                         category_results = answer[category]
                         if isinstance(category_results, list):
                             answer_list.extend(category_results)
-            
-            # Extract clean content from all results
-            content_list = [
-                self.extract_content_from_result(ans) 
-                for ans in answer_list
-            ]
 
-            
+            # 对命中的 community 节点展开其成员 statements（路径 "0"/"1" 需要，路径 "2" 不需要）
+            if expand_communities and Neo4jNodeType.COMMUNITY in include:
+                community_results = (
+                    answer.get('reranked_results', {}).get(Neo4jNodeType.COMMUNITY.value, [])
+                    if search_type == "hybrid"
+                    else answer.get(Neo4jNodeType.COMMUNITY.value, [])
+                )
+                cleaned_stmts, new_texts = await expand_communities_to_statements(
+                    community_results=community_results,
+                    end_user_id=end_user_id,
+                )
+                answer_list.extend(cleaned_stmts)
+
+            # Extract clean content from all results，按类型传入 node_type 区分 community
+            content_list = []
+            for ans in answer_list:
+                # community 节点有 member_count 或 core_entities 字段
+                ntype = Neo4jNodeType.COMMUNITY if ('member_count' in ans or 'core_entities' in ans) else ""
+                content_list.append(self.extract_content_from_result(ans, node_type=ntype))
+
             # Filter out empty strings and join with newlines
             clean_content = '\n'.join([c for c in content_list if c])
-            
+
             # Log first 200 chars
             logger.info(f"检索接口搜索结果==>>:{clean_content[:200]}...")
-            
+
             # Return raw results if requested
             if return_raw_results:
                 return clean_content, cleaned_query, answer
             else:
                 return clean_content, cleaned_query, None
-            
+
         except Exception as e:
             logger.error(
                 f"Search failed for query '{question}' in group '{end_user_id}': {e}",

api/app/core/memory/agent/utils/get_dialogs.py

@@ -11,7 +11,7 @@ async def get_chunked_dialogs(
         chunker_strategy: str = "RecursiveChunker",
         end_user_id: str = "group_1",
         messages: list = None,
-        ref_id: str = "wyl_20251027",
+        ref_id: str = "",
         config_id: str = None
 ) -> List[DialogData]:
     """Generate chunks from structured messages using the specified chunker strategy.
@@ -21,7 +21,7 @@ async def get_chunked_dialogs(
         end_user_id: Group identifier
         messages: Structured message list [{"role": "user", "content": "..."}, ...]
         ref_id: Reference identifier
-        config_id: Configuration ID for processing
+        config_id: Configuration ID for processing (used to load pruning config)
 
     Returns:
         List of DialogData objects with generated chunks
@@ -40,12 +40,13 @@ async def get_chunked_dialogs(
 
         role = msg['role']
         content = msg['content']
+        files = msg.get("file_content", [])
 
         if role not in ['user', 'assistant']:
             raise ValueError(f"Message {idx} role must be 'user' or 'assistant', got: {role}")
 
         if content.strip():
-            conversation_messages.append(ConversationMessage(role=role, msg=content.strip()))
+            conversation_messages.append(ConversationMessage(role=role, msg=content.strip(), files=files))
 
     if not conversation_messages:
         raise ValueError("Message list cannot be empty after filtering")
@@ -57,6 +58,63 @@ async def get_chunked_dialogs(
         end_user_id=end_user_id,
         config_id=config_id
     )
+    
+    # 语义剪枝步骤（在分块之前）
+    try:
+        from app.core.memory.storage_services.extraction_engine.data_preprocessing.data_pruning import SemanticPruner
+        from app.core.memory.models.config_models import PruningConfig
+        from app.db import get_db_context
+        from app.services.memory_config_service import MemoryConfigService
+        from app.core.memory.utils.llm.llm_utils import MemoryClientFactory
+        
+        # 加载剪枝配置
+        pruning_config = None
+        if config_id:
+            try:
+                with get_db_context() as db:
+                    # 使用 MemoryConfigService 加载完整的 MemoryConfig 对象
+                    config_service = MemoryConfigService(db)
+                    memory_config = config_service.load_memory_config(
+                        config_id=config_id,
+                        service_name="semantic_pruning"
+                    )
+                    
+                    if memory_config:
+                        pruning_config = PruningConfig(
+                            pruning_switch=memory_config.pruning_enabled,
+                            pruning_scene=memory_config.pruning_scene or "education",
+                            pruning_threshold=memory_config.pruning_threshold,
+                            scene_id=str(memory_config.scene_id) if memory_config.scene_id else None,
+                            ontology_class_infos=memory_config.ontology_class_infos,
+                        )
+                        logger.info(f"[剪枝] 加载配置: switch={pruning_config.pruning_switch}, scene={pruning_config.pruning_scene}, threshold={pruning_config.pruning_threshold}")
+                        
+                        # 获取LLM客户端用于剪枝
+                        if pruning_config.pruning_switch:
+                            factory = MemoryClientFactory(db)
+                            llm_client = factory.get_llm_client_from_config(memory_config)
+                            
+                            # 执行剪枝 - 使用 prune_dataset 支持消息级剪枝
+                            pruner = SemanticPruner(config=pruning_config, llm_client=llm_client)
+                            original_msg_count = len(dialog_data.context.msgs)
+                            
+                            # 使用 prune_dataset 而不是 prune_dialog
+                            # prune_dataset 会进行消息级剪枝，即使对话整体相关也会删除不重要消息
+                            pruned_dialogs = await pruner.prune_dataset([dialog_data])
+                            
+                            if pruned_dialogs:
+                                dialog_data = pruned_dialogs[0]
+                                remaining_msg_count = len(dialog_data.context.msgs)
+                                deleted_count = original_msg_count - remaining_msg_count
+                                logger.info(f"[剪枝] 完成: 原始{original_msg_count}条 -> 保留{remaining_msg_count}条 (删除{deleted_count}条)")
+                            else:
+                                logger.warning("[剪枝] prune_dataset 返回空列表")
+                        else:
+                            logger.info("[剪枝] 配置中剪枝开关关闭，跳过剪枝")
+            except Exception as e:
+                logger.warning(f"[剪枝] 加载配置失败，跳过剪枝: {e}", exc_info=True)
+    except Exception as e:
+        logger.warning(f"[剪枝] 执行失败，跳过剪枝: {e}", exc_info=True)
 
     chunker = DialogueChunker(chunker_strategy)
     extracted_chunks = await chunker.process_dialogue(dialog_data)

api/app/core/memory/agent/utils/llm_client_pool.py

@@ -1,56 +0,0 @@
-
-import asyncio
-from typing import Dict, Optional
-from app.core.memory.utils.llm.llm_utils import get_llm_client_fast
-from app.db import get_db
-from app.core.logging_config import get_agent_logger
-
-logger = get_agent_logger(__name__)
-
-class LLMClientPool:
-    """LLM客户端连接池"""
-    
-    def __init__(self, max_size: int = 5):
-        self.max_size = max_size
-        self.pools: Dict[str, asyncio.Queue] = {}
-        self.active_clients: Dict[str, int] = {}
-        
-    async def get_client(self, llm_model_id: str):
-        """获取LLM客户端"""
-        if llm_model_id not in self.pools:
-            self.pools[llm_model_id] = asyncio.Queue(maxsize=self.max_size)
-            self.active_clients[llm_model_id] = 0
-            
-        pool = self.pools[llm_model_id]
-        
-        try:
-            # 尝试从池中获取客户端
-            client = pool.get_nowait()
-            logger.debug(f"从池中获取LLM客户端: {llm_model_id}")
-            return client
-        except asyncio.QueueEmpty:
-            # 池为空，创建新客户端
-            if self.active_clients[llm_model_id] < self.max_size:
-                db_session = next(get_db())
-                client = get_llm_client_fast(llm_model_id, db_session)
-                self.active_clients[llm_model_id] += 1
-                logger.debug(f"创建新LLM客户端: {llm_model_id}")
-                return client
-            else:
-                # 等待可用客户端
-                logger.debug(f"等待LLM客户端可用: {llm_model_id}")
-                return await pool.get()
-                
-    async def return_client(self, llm_model_id: str, client):
-        """归还LLM客户端到池中"""
-        if llm_model_id in self.pools:
-            try:
-                self.pools[llm_model_id].put_nowait(client)
-                logger.debug(f"归还LLM客户端到池: {llm_model_id}")
-            except asyncio.QueueFull:
-                # 池已满，丢弃客户端
-                self.active_clients[llm_model_id] -= 1
-                logger.debug(f"池已满，丢弃LLM客户端: {llm_model_id}")
-
-# 全局客户端池
-llm_client_pool = LLMClientPool()

api/app/core/memory/agent/utils/llm_tools.py

@@ -1,4 +1,3 @@
-import os
 from collections import defaultdict
 from pathlib import Path
 from typing import Annotated, TypedDict
@@ -8,10 +7,11 @@ from langgraph.graph import add_messages
 
 PROJECT_ROOT_ = str(Path(__file__).resolve().parents[3])
 
+
 class WriteState(TypedDict):
-    '''
+    """
     Langgrapg Writing TypedDict
-    '''
+    """
     messages: Annotated[list[AnyMessage], add_messages]
     end_user_id: str
     errors: list[dict]  # Track errors: [{"tool": "tool_name", "error": "message"}]
@@ -20,6 +20,7 @@ class WriteState(TypedDict):
     data: str
     language: str  # 语言类型 ("zh" 中文, "en" 英文)
 
+
 class ReadState(TypedDict):
     """
     LangGraph 工作流状态定义
@@ -43,18 +44,21 @@ class ReadState(TypedDict):
     config_id: str
     data: str  # 新增字段用于传递内容
     spit_data: dict  # 新增字段用于传递问题分解结果
-    problem_extension:dict
+    problem_extension: dict
     storage_type: str
     user_rag_memory_id: str
     llm_id: str
     embedding_id: str
     memory_config: object  # 新增字段用于传递内存配置对象
-    retrieve:dict
+    retrieve: dict
+    perceptual_data: dict
     RetrieveSummary: dict
     InputSummary: dict
     verify: dict
     SummaryFails: dict
     summary: dict
+
+
 class COUNTState:
     """
     工作流对话检索内容计数器
@@ -99,6 +103,7 @@ class COUNTState:
         self.total = 0
         print("[COUNTState] 已重置为 0")
 
+
 def deduplicate_entries(entries):
     seen = set()
     deduped = []
@@ -109,6 +114,7 @@ def deduplicate_entries(entries):
             deduped.append(entry)
     return deduped
 
+
 def merge_to_key_value_pairs(data, query_key, result_key):
     grouped = defaultdict(list)
     for item in data:
@@ -142,4 +148,4 @@ def convert_extended_question_to_question(data):
         return [convert_extended_question_to_question(item) for item in data]
     else:
         # 其他类型直接返回
-        return data
+        return data

api/app/core/memory/agent/utils/prompt/Problem_Extension_prompt.jinja2

@@ -39,6 +39,30 @@
     比如：输入历史信息内容:[{'Query': '4月27日，我和你推荐过一本书，书名是什么？', 'ANswer': '张曼玉推荐了《小王子》'}]
     拆分问题：4月27日，我和你推荐过一本书，书名是什么？，可以拆分为：4月27日，张曼玉推荐过一本书，书名是什么？
 
+## 指代消歧规则（Coreference Resolution）：
+在拆分问题时，必须解析并替换所有指代词和抽象称呼，使问题具体化：
+
+1. **"用户"的消歧**：
+   - "用户是谁？" → 分析历史记录，找出对话发起者的姓名
+   - 如果历史中有"我叫X"、"我的名字是X"、或多次提到某个人物，则"用户"指的就是这个人
+   - 示例：历史中有"老李的原名叫李建国"，则"用户是谁？"应拆分为"李建国是谁？"或"老李（李建国）是谁？"
+
+2. **"我"的消歧**：
+   - "我喜欢什么？" → 从历史中找出对话发起者的姓名，替换为"X喜欢什么？"
+   - 示例：历史中有"张曼玉推荐了《小王子》"，则"我推荐的书是什么？"应拆分为"张曼玉推荐的书是什么？"
+
+3. **"他/她/它"的消歧**：
+   - 从上下文或历史中找出最近提到的同类实体
+   - 示例：历史中有"老李的同事叫他建国哥"，则"他的同事怎么称呼他？"应拆分为"老李的同事怎么称呼他？"
+
+4. **"那个人/这个人"的消歧**：
+   - 从历史中找出最近提到的人物
+   - 示例：历史中有"李建国"，则"那个人的原名是什么？"应拆分为"李建国的原名是什么？"
+
+5. **优先级**：
+   - 如果历史记录中反复出现某个人物（如"老李"、"李建国"、"建国哥"），则"用户"很可能指的就是这个人
+   - 如果无法从历史中确定指代对象，保留原问题，但在reason中说明"无法确定指代对象"
+
 
 
 输出要求：
@@ -71,6 +95,34 @@
     "reason": "输出原问题的关键要素"
   }
 ]
+
+## 指代消歧示例（重要）：
+示例1 - "用户"的消歧：
+输入历史：[{'Query': '老李的原名叫什么？', 'Answer': '李建国'}, {'Query': '老李的同事叫他什么？', 'Answer': '建国哥'}]
+输入问题："用户是谁？"
+输出：
+[
+  {
+    "original_question": "用户是谁？",
+    "extended_question": "李建国是谁？",
+    "type": "单跳",
+    "reason": "历史中反复提到'老李/李建国/建国哥'，'用户'指的就是对话发起者李建国"
+  }
+]
+
+示例2 - "我"的消歧：
+输入历史：[{'Query': '张曼玉推荐了什么书？', 'Answer': '《小王子》'}]
+输入问题："我推荐的书是什么？"
+输出：
+[
+  {
+    "original_question": "我推荐的书是什么？",
+    "extended_question": "张曼玉推荐的书是什么？",
+    "type": "单跳",
+    "reason": "历史中提到张曼玉推荐了书，'我'指的就是张曼玉"
+  }
+]
+
 **Output format**
 **CRITICAL JSON FORMATTING REQUIREMENTS:**
 1. Use only standard ASCII double quotes (") for JSON structure - never use Chinese quotation marks ("") or other Unicode quotes

api/app/core/memory/agent/utils/prompt/problem_breakdown_prompt.jinja2

@@ -27,6 +27,30 @@
     比如：输入历史信息内容:[{'Query': '4月27日，我和你推荐过一本书，书名是什么？', 'ANswer': '张曼玉推荐了《小王子》'}]
     拆分问题：4月27日，我和你推荐过一本书，书名是什么？，可以拆分为：4月27日，张曼玉推荐过一本书，书名是什么？
 
+## 指代消歧规则（Coreference Resolution）：
+在拆分问题时，必须解析并替换所有指代词和抽象称呼，使问题具体化：
+
+1. **"用户"的消歧**：
+   - "用户是谁？" → 分析历史记录，找出对话发起者的姓名
+   - 如果历史中有"我叫X"、"我的名字是X"、或多次提到某个人物（如"老李"、"李建国"），则"用户"指的就是这个人
+   - 示例：历史中反复出现"老李/李建国/建国哥"，则"用户是谁？"应拆分为"李建国是谁？"或"老李（李建国）是谁？"
+
+2. **"我"的消歧**：
+   - "我喜欢什么？" → 从历史中找出对话发起者的姓名，替换为"X喜欢什么？"
+   - 示例：历史中有"张曼玉推荐了《小王子》"，则"我推荐的书是什么？"应拆分为"张曼玉推荐的书是什么？"
+
+3. **"他/她/它"的消歧**：
+   - 从上下文或历史中找出最近提到的同类实体
+   - 示例：历史中有"老李的同事叫他建国哥"，则"他的同事怎么称呼他？"应拆分为"老李的同事怎么称呼他？"
+
+4. **"那个人/这个人"的消歧**：
+   - 从历史中找出最近提到的人物
+   - 示例：历史中有"李建国"，则"那个人的原名是什么？"应拆分为"李建国的原名是什么？"
+
+5. **优先级**：
+   - 如果历史记录中反复出现某个人物（如"老李"、"李建国"、"建国哥"），则"用户"很可能指的就是这个人
+   - 如果无法从历史中确定指代对象，保留原问题，但在reason中说明"无法确定指代对象"
+
 ## 指令：
 你是一个智能数据拆分助手，请根据数据特性判断输入属于哪种类型：
 单跳（Single-hop）
@@ -151,6 +175,34 @@
 ]
 - 必须通过json.loads()的格式支持的形式输出
 - 必须通过json.loads()的格式支持的形式输出,响应必须是与此确切模式匹配的有效JSON对象。不要在JSON之前或之后包含任何文本。
+
+## 指代消歧示例（重要）：
+示例1 - "用户"的消歧：
+输入历史：[{'Query': '老李的原名叫什么？', 'Answer': '李建国'}, {'Query': '老李的同事叫他什么？', 'Answer': '建国哥'}]
+输入问题："用户是谁？"
+输出：
+[
+  {
+    "id": "Q1",
+    "question": "李建国是谁？",
+    "type": "单跳",
+    "reason": "历史中反复提到'老李/李建国/建国哥'，'用户'指的就是对话发起者李建国"
+  }
+]
+
+示例2 - "我"的消歧：
+输入历史：[{'Query': '张曼玉推荐了什么书？', 'Answer': '《小王子》'}]
+输入问题："我推荐的书是什么？"
+输出：
+[
+  {
+    "id": "Q1",
+    "question": "张曼玉推荐的书是什么？",
+    "type": "单跳",
+    "reason": "历史中提到张曼玉推荐了书，'我'指的就是张曼玉"
+  }
+]
+
 - 关键的JSON格式要求
 1.JSON结构仅使用标准ASCII双引号（“）-切勿使用中文引号（“”）或其他Unicode引号
 2.如果提取的语句文本包含引号，请使用反斜杠（\“）正确转义它们

api/app/core/memory/agent/utils/redis_tool.py

@@ -3,8 +3,9 @@ import uuid
 from app.core.config import settings
 from typing import List, Dict, Any, Optional, Union
 
+from app.core.logging_config import get_logger
 from app.core.memory.agent.utils.redis_base import (
-    serialize_messages, 
+    serialize_messages,
     deserialize_messages,
     fix_encoding,
     format_session_data,
@@ -14,12 +15,12 @@ from app.core.memory.agent.utils.redis_base import (
     get_current_timestamp
 )
 
-
+logger = get_logger(__name__)
 
 
 class RedisWriteStore:
     """Redis Write 类型存储类，用于管理 save_session_write 相关的数据"""
-    
+
     def __init__(self, host='localhost', port=6379, db=0, password=None, session_id=''):
         """
         初始化 Redis 连接
@@ -66,10 +67,10 @@ class RedisWriteStore:
             })
             result = pipe.execute()
 
-            print(f"[save_session_write] 保存结果: {result[0]}, session_id: {session_id}")
+            logger.debug(f"[save_session_write] 保存结果: {result[0]}, session_id: {session_id}")
             return session_id
         except Exception as e:
-            print(f"[save_session_write] 保存会话失败: {e}")
+            logger.error(f"[save_session_write] 保存会话失败: {e}")
             raise e
 
     def get_session_by_userid(self, userid: str) -> Union[List[Dict[str, str]], bool]:
@@ -99,7 +100,7 @@ class RedisWriteStore:
             for key, data in zip(keys, all_data):
                 if not data:
                     continue
-                
+
                 # 从 write 类型读取，匹配 sessionid 字段
                 if data.get('sessionid') == userid:
                     # 从 key 中提取 session_id: session:write:{session_id}
@@ -108,16 +109,16 @@ class RedisWriteStore:
                         "sessionid": session_id,
                         "messages": fix_encoding(data.get('messages', ''))
                     })
-            
+
             if not results:
                 return False
-            
-            print(f"[get_session_by_userid] userid={userid}, 找到 {len(results)} 条数据")
+
+            logger.debug(f"[get_session_by_userid] userid={userid}, 找到 {len(results)} 条数据")
             return results
         except Exception as e:
-            print(f"[get_session_by_userid] 查询失败: {e}")
+            logger.error(f"[get_session_by_userid] 查询失败: {e}")
             return False
-    
+
     def get_all_sessions_by_end_user_id(self, end_user_id: str) -> Union[List[Dict[str, Any]], bool]:
         """
         通过 end_user_id 获取所有 write 类型的会话数据
@@ -144,7 +145,7 @@ class RedisWriteStore:
             # 只查询 write 类型的 key
             keys = self.r.keys('session:write:*')
             if not keys:
-                print(f"[get_all_sessions_by_end_user_id] 没有找到任何 write 类型的会话")
+                logger.debug(f"[get_all_sessions_by_end_user_id] 没有找到任何 write 类型的会话")
                 return False
 
             # 批量获取数据
@@ -158,12 +159,12 @@ class RedisWriteStore:
             for key, data in zip(keys, all_data):
                 if not data:
                     continue
-                
+
                 # 从 write 类型读取，匹配 sessionid 字段
                 if data.get('sessionid') == end_user_id:
                     # 从 key 中提取 session_id: session:write:{session_id}
                     session_id = key.split(':')[-1]
-                    
+
                     # 构建完整的会话信息
                     session_info = {
                         "session_id": session_id,
@@ -173,23 +174,21 @@ class RedisWriteStore:
                         "starttime": data.get('starttime', '')
                     }
                     results.append(session_info)
-            
+
             if not results:
-                print(f"[get_all_sessions_by_end_user_id] end_user_id={end_user_id}, 没有找到数据")
+                logger.debug(f"[get_all_sessions_by_end_user_id] end_user_id={end_user_id}, 没有找到数据")
                 return False
-            
+
             # 按时间排序（最新的在前）
             results.sort(key=lambda x: x.get('starttime', ''), reverse=True)
-            
-            print(f"[get_all_sessions_by_end_user_id] end_user_id={end_user_id}, 找到 {len(results)} 条数据")
+
+            logger.debug(f"[get_all_sessions_by_end_user_id] end_user_id={end_user_id}, 找到 {len(results)} 条数据")
             return results
         except Exception as e:
-            print(f"[get_all_sessions_by_end_user_id] 查询失败: {e}")
-            import traceback
-            traceback.print_exc()
+            logger.error(f"[get_all_sessions_by_end_user_id] 查询失败: {e}", exc_info=True)
             return False
 
-    def find_user_recent_sessions(self, userid: str, 
+    def find_user_recent_sessions(self, userid: str,
                                   minutes: int = 5) -> List[Dict[str, str]]:
         """
         根据 userid 从 save_session_write 写入的数据中查询最近 N 分钟内的会话数据
@@ -203,11 +202,11 @@ class RedisWriteStore:
         """
         import time
         start_time = time.time()
-        
+
         # 只查询 write 类型的 key
         keys = self.r.keys('session:write:*')
         if not keys:
-            print(f"[find_user_recent_sessions] 查询耗时: {time.time() - start_time:.3f}秒, 结果数: 0")
+            logger.debug(f"[find_user_recent_sessions] 查询耗时: {time.time() - start_time:.3f}秒, 结果数: 0")
             return []
 
         # 批量获取数据
@@ -221,7 +220,7 @@ class RedisWriteStore:
         for data in all_data:
             if not data:
                 continue
-            
+
             # 从 write 类型读取，匹配 sessionid 字段
             if data.get('sessionid') == userid and data.get('starttime'):
                 # write 类型没有 aimessages，所以 Answer 为空
@@ -230,15 +229,14 @@ class RedisWriteStore:
                     "Answer": "",
                     "starttime": data.get('starttime', '')
                 })
-        
+
         # 根据时间范围过滤
         filtered_items = filter_by_time_range(matched_items, minutes)
         # 排序并移除时间字段
-        result_items = sort_and_limit_results(filtered_items, limit=None)
-        print(result_items)
+        result_items = sort_and_limit_results(filtered_items)
 
         elapsed_time = time.time() - start_time
-        print(f"[find_user_recent_sessions] userid={userid}, minutes={minutes}, "
+        logger.debug(f"[find_user_recent_sessions] userid={userid}, minutes={minutes}, "
               f"查询耗时: {elapsed_time:.3f}秒, 结果数: {len(result_items)}")
 
         return result_items
@@ -258,7 +256,7 @@ class RedisWriteStore:
 
 class RedisCountStore:
     """Redis Count 类型存储类，用于管理访问次数统计相关的数据"""
-    
+
     def __init__(self, host='localhost', port=6379, db=0, password=None, session_id=''):
         """
         初始化 Redis 连接
@@ -278,7 +276,7 @@ class RedisCountStore:
             decode_responses=True,
             encoding='utf-8'
         )
-        self.uudi = session_id
+        self.uuid = session_id
 
     def save_sessions_count(self, end_user_id: str, count: int, messages: Any) -> str:
         """
@@ -295,26 +293,26 @@ class RedisCountStore:
         session_id = str(uuid.uuid4())
         key = generate_session_key(session_id, key_type="count")
         index_key = f'session:count:index:{end_user_id}'  # 索引键
-        
+
         pipe = self.r.pipeline()
         pipe.hset(key, mapping={
-            "id": self.uudi,
+            "id": self.uuid,
             "end_user_id": end_user_id,
             "count": int(count),
             "messages": serialize_messages(messages),
             "starttime": get_current_timestamp()
         })
         pipe.expire(key, 30 * 24 * 60 * 60)  # 30天过期
-        
+
         # 创建索引：end_user_id -> session_id 映射
         pipe.set(index_key, session_id, ex=30 * 24 * 60 * 60)
-        
+
         result = pipe.execute()
-        
-        print(f"[save_sessions_count] 保存结果: {result}, session_id: {session_id}")
+
+        logger.debug(f"[save_sessions_count] 保存结果: {result}, session_id: {session_id}")
         return session_id
 
-    def get_sessions_count(self, end_user_id: str) -> Union[List[Any], bool]:
+    def get_sessions_count(self, end_user_id: str) -> tuple[int, list[dict]] | bool:
         """
         通过 end_user_id 查询访问次数统计
         
@@ -327,7 +325,7 @@ class RedisCountStore:
         try:
             # 使用索引键快速查找
             index_key = f'session:count:index:{end_user_id}'
-            
+
             # 检查索引键类型，避免 WRONGTYPE 错误
             try:
                 key_type = self.r.type(index_key)
@@ -335,35 +333,40 @@ class RedisCountStore:
                     self.r.delete(index_key)
                     return False
             except Exception as type_error:
-                print(f"[get_sessions_count] 检查键类型失败: {type_error}")
-            
+                logger.error(f"[get_sessions_count] 检查键类型失败: {type_error}")
+
             session_id = self.r.get(index_key)
-            
+
             if not session_id:
                 return False
-            
+
             # 直接获取数据
             key = generate_session_key(session_id, key_type="count")
             data = self.r.hgetall(key)
-            
+
             if not data:
                 # 索引存在但数据不存在，清理索引
                 self.r.delete(index_key)
                 return False
-            
+
             count = data.get('count')
             messages_str = data.get('messages')
-            
+
             if count is not None:
-                messages = deserialize_messages(messages_str)
-                return [int(count), messages]
-            
+                messages: list[dict] = deserialize_messages(messages_str)
+                return int(count), messages
+
             return False
         except Exception as e:
-            print(f"[get_sessions_count] 查询失败: {e}")
+            logger.error(f"[get_sessions_count] 查询失败: {e}")
             return False
-    def update_sessions_count(self, end_user_id: str, new_count: int, 
-                             messages: Any) -> bool:
+
+    def update_sessions_count(
+            self,
+            end_user_id: str,
+            new_count: int,
+            messages: Any
+    ) -> bool:
         """
         通过 end_user_id 修改访问次数统计（优化版：使用索引）
         
@@ -378,39 +381,39 @@ class RedisCountStore:
         try:
             # 使用索引键快速查找
             index_key = f'session:count:index:{end_user_id}'
-            
+
             # 检查索引键类型，避免 WRONGTYPE 错误
             try:
                 key_type = self.r.type(index_key)
                 if key_type != 'string' and key_type != 'none':
                     # 索引键类型错误，删除并返回 False
-                    print(f"[update_sessions_count] 索引键类型错误: {key_type}，删除索引")
+                    logger.warning(f"[update_sessions_count] 索引键类型错误: {key_type}，删除索引")
                     self.r.delete(index_key)
-                    print(f"[update_sessions_count] 未找到记录: end_user_id={end_user_id}")
+                    logger.debug(f"[update_sessions_count] 未找到记录: end_user_id={end_user_id}")
                     return False
             except Exception as type_error:
-                print(f"[update_sessions_count] 检查键类型失败: {type_error}")
-            
+                logger.error(f"[update_sessions_count] 检查键类型失败: {type_error}")
+
             session_id = self.r.get(index_key)
-            
+
             if not session_id:
-                print(f"[update_sessions_count] 未找到记录: end_user_id={end_user_id}")
+                logger.debug(f"[update_sessions_count] 未找到记录: end_user_id={end_user_id}")
                 return False
-            
+
             # 直接更新数据
             key = generate_session_key(session_id, key_type="count")
             messages_str = serialize_messages(messages)
-            
+
             pipe = self.r.pipeline()
-            pipe.hset(key, 'count', int(new_count))
+            pipe.hset(key, 'count', str(new_count))
             pipe.hset(key, 'messages', messages_str)
             result = pipe.execute()
-            
-            print(f"[update_sessions_count] 更新成功: end_user_id={end_user_id}, new_count={new_count}, key={key}")
+
+            logger.debug(f"[update_sessions_count] 更新成功: end_user_id={end_user_id}, new_count={new_count}, key={key}")
             return True
-            
+
         except Exception as e:
-            print(f"[update_sessions_count] 更新失败: {e}")
+            logger.debug(f"[update_sessions_count] 更新失败: {e}")
             return False
 
     def delete_all_count_sessions(self) -> int:
@@ -428,7 +431,7 @@ class RedisCountStore:
 
 class RedisSessionStore:
     """Redis 会话存储类，用于管理会话数据"""
-    
+
     def __init__(self, host='localhost', port=6379, db=0, password=None, session_id=''):
         """
         初始化 Redis 连接
@@ -451,9 +454,9 @@ class RedisSessionStore:
         self.uudi = session_id
 
     # ==================== 写入操作 ====================
-    
-    def save_session(self, userid: str, messages: str, aimessages: str, 
-                    apply_id: str, end_user_id: str) -> str:
+
+    def save_session(self, userid: str, messages: str, aimessages: str,
+                     apply_id: str, end_user_id: str) -> str:
         """
         写入一条会话数据，返回 session_id
         
@@ -483,14 +486,14 @@ class RedisSessionStore:
             })
             result = pipe.execute()
 
-            print(f"[save_session] 保存结果: {result[0]}, session_id: {session_id}")
+            logger.debug(f"[save_session] 保存结果: {result[0]}, session_id: {session_id}")
             return session_id
         except Exception as e:
-            print(f"[save_session] 保存会话失败: {e}")
+            logger.error(f"[save_session] 保存会话失败: {e}")
             raise e
 
     # ==================== 读取操作 ====================
-    
+
     def get_session(self, session_id: str) -> Optional[Dict[str, Any]]:
         """
         读取一条会话数据
@@ -520,8 +523,8 @@ class RedisSessionStore:
                 sessions[sid] = self.get_session(sid)
         return sessions
 
-    def find_user_apply_group(self, sessionid: str, apply_id: str, 
-                             end_user_id: str) -> List[Dict[str, str]]:
+    def find_user_apply_group(self, sessionid: str, apply_id: str,
+                              end_user_id: str) -> List[Dict[str, str]]:
         """
         根据 sessionid、apply_id 和 end_user_id 查询会话数据，返回最新的6条
         
@@ -535,10 +538,10 @@ class RedisSessionStore:
         """
         import time
         start_time = time.time()
-        
+
         keys = self.r.keys('session:*')
         if not keys:
-            print(f"[find_user_apply_group] 查询耗时: {time.time() - start_time:.3f}秒, 结果数: 0")
+            logger.debug(f"[find_user_apply_group] 查询耗时: {time.time() - start_time:.3f}秒, 结果数: 0")
             return []
 
         # 批量获取数据
@@ -556,21 +559,21 @@ class RedisSessionStore:
                 continue
 
             if (data.get('apply_id') == apply_id and
-                data.get('end_user_id') == end_user_id):
+                    data.get('end_user_id') == end_user_id):
                 # 支持模糊匹配或完全匹配 sessionid
                 if sessionid in data.get('sessionid', '') or data.get('sessionid') == sessionid:
                     matched_items.append(format_session_data(data, include_time=True))
-        
+
         # 排序、限制数量并移除时间字段
         result_items = sort_and_limit_results(matched_items, limit=6)
 
         elapsed_time = time.time() - start_time
-        print(f"[find_user_apply_group] 查询耗时: {elapsed_time:.3f}秒, 结果数: {len(result_items)}")
+        logger.debug(f"[find_user_apply_group] 查询耗时: {elapsed_time:.3f}秒, 结果数: {len(result_items)}")
 
         return result_items
 
     # ==================== 更新操作 ====================
-    
+
     def update_session(self, session_id: str, field: str, value: Any) -> bool:
         """
         更新单个字段
@@ -591,7 +594,7 @@ class RedisSessionStore:
         return bool(results[0])
 
     # ==================== 删除操作 ====================
-    
+
     def delete_session(self, session_id: str) -> int:
         """
         删除单条会话
@@ -632,7 +635,7 @@ class RedisSessionStore:
 
         keys = self.r.keys('session:*')
         if not keys:
-            print("[delete_duplicate_sessions] 没有会话数据")
+            logger.debug("[delete_duplicate_sessions] 没有会话数据")
             return 0
 
         # 批量获取所有数据
@@ -678,7 +681,7 @@ class RedisSessionStore:
                 deleted_count += len(batch)
 
         elapsed_time = time.time() - start_time
-        print(f"[delete_duplicate_sessions] 删除重复会话数量: {deleted_count}, 耗时: {elapsed_time:.3f}秒")
+        logger.debug(f"[delete_duplicate_sessions] 删除重复会话数量: {deleted_count}, 耗时: {elapsed_time:.3f}秒")
         return deleted_count
 
 

api/app/core/memory/agent/utils/write_tools.py

@@ -6,16 +6,21 @@ pipeline. Only MemoryConfig is needed - clients are constructed internally.
 """
 import asyncio
 import time
+import uuid
 from datetime import datetime
+from typing import List, Optional
 
 from dotenv import load_dotenv
 
 from app.core.logging_config import get_agent_logger
 from app.core.memory.agent.utils.get_dialogs import get_chunked_dialogs
+from app.core.memory.storage_services.extraction_engine.deduplication.deduped_and_disamb import _USER_PLACEHOLDER_NAMES
 from app.core.memory.storage_services.extraction_engine.extraction_orchestrator import ExtractionOrchestrator
-from app.core.memory.storage_services.extraction_engine.knowledge_extraction.memory_summary import memory_summary_generation
+from app.core.memory.storage_services.extraction_engine.knowledge_extraction.memory_summary import \
+    memory_summary_generation
 from app.core.memory.utils.llm.llm_utils import MemoryClientFactory
 from app.core.memory.utils.log.logging_utils import log_time
+from app.core.memory.utils.memory_count_utils import sync_end_user_memory_count_from_neo4j
 from app.db import get_db_context
 from app.repositories.neo4j.add_edges import add_memory_summary_statement_edges
 from app.repositories.neo4j.add_nodes import add_memory_summary_nodes
@@ -23,18 +28,17 @@ from app.repositories.neo4j.graph_saver import save_dialog_and_statements_to_neo
 from app.repositories.neo4j.neo4j_connector import Neo4jConnector
 from app.schemas.memory_config_schema import MemoryConfig
 
-
 load_dotenv()
 
 logger = get_agent_logger(__name__)
 
 
 async def write(
-    end_user_id: str,
-    memory_config: MemoryConfig,
-    messages: list,
-    ref_id: str = "wyl20251027",
-    language: str = "zh",
+        end_user_id: str,
+        memory_config: MemoryConfig,
+        messages: list,
+        ref_id: str = "",
+        language: str = "zh",
 ) -> None:
     """
     Execute the complete knowledge extraction pipeline.
@@ -43,9 +47,11 @@ async def write(
         end_user_id: Group identifier
         memory_config: MemoryConfig object containing all configuration
         messages: Structured message list [{"role": "user", "content": "..."}, ...]
-        ref_id: Reference ID, defaults to "wyl20251027"
+        ref_id: Reference ID, defaults to ""
         language: 语言类型 ("zh" 中文, "en" 英文)，默认中文
     """
+    if not ref_id:
+        ref_id = uuid.uuid4().hex
     # Extract config values
     embedding_model_id = str(memory_config.embedding_model_id)
     chunker_strategy = memory_config.chunker_strategy
@@ -99,14 +105,14 @@ async def write(
     if memory_config.scene_id:
         try:
             from app.core.memory.ontology_services.ontology_type_loader import load_ontology_types_for_scene
-            
+
             with get_db_context() as db:
                 ontology_types = load_ontology_types_for_scene(
                     scene_id=memory_config.scene_id,
                     workspace_id=memory_config.workspace_id,
                     db=db
                 )
-                
+
                 if ontology_types:
                     logger.info(
                         f"Loaded {len(ontology_types.types)} ontology types for scene_id: {memory_config.scene_id}"
@@ -135,9 +141,11 @@ async def write(
         all_chunk_nodes,
         all_statement_nodes,
         all_entity_nodes,
+        all_perceptual_nodes,
         all_statement_chunk_edges,
         all_statement_entity_edges,
         all_entity_entity_edges,
+        all_perceptual_edges,
         all_dedup_details,
     ) = await orchestrator.run(chunked_dialogs, is_pilot_run=False)
 
@@ -145,11 +153,24 @@ async def write(
 
     # Step 3: Save all data to Neo4j database
     step_start = time.time()
-    from app.repositories.neo4j.create_indexes import create_fulltext_indexes
+
+    # Neo4j 写入前：清洗用户/AI助手实体之间的别名交叉污染
+    # 从 Neo4j 查询已有的 AI 助手别名，与本轮实体中的 AI 助手别名合并，
+    # 确保用户实体的 aliases 不包含 AI 助手的名字
     try:
-        await create_fulltext_indexes()
+        from app.core.memory.storage_services.extraction_engine.deduplication.deduped_and_disamb import (
+            clean_cross_role_aliases,
+            fetch_neo4j_assistant_aliases,
+        )
+        neo4j_assistant_aliases = set()
+        if all_entity_nodes:
+            _eu_id = all_entity_nodes[0].end_user_id
+            if _eu_id:
+                neo4j_assistant_aliases = await fetch_neo4j_assistant_aliases(neo4j_connector, _eu_id)
+        clean_cross_role_aliases(all_entity_nodes, external_assistant_aliases=neo4j_assistant_aliases)
+        logger.info(f"Neo4j 写入前别名清洗完成，AI助手别名排除集大小: {len(neo4j_assistant_aliases)}")
     except Exception as e:
-        logger.error(f"Error creating indexes: {e}", exc_info=True)
+        logger.warning(f"Neo4j 写入前别名清洗失败（不影响主流程）: {e}")
 
     # 添加死锁重试机制
     max_retries = 3
@@ -162,13 +183,63 @@ async def write(
                 chunk_nodes=all_chunk_nodes,
                 statement_nodes=all_statement_nodes,
                 entity_nodes=all_entity_nodes,
+                perceptual_nodes=all_perceptual_nodes,
                 statement_chunk_edges=all_statement_chunk_edges,
                 statement_entity_edges=all_statement_entity_edges,
                 entity_edges=all_entity_entity_edges,
-                connector=neo4j_connector
+                perceptual_edges=all_perceptual_edges,
+                connector=neo4j_connector,
             )
             if success:
                 logger.info("Successfully saved all data to Neo4j")
+                
+                if all_entity_nodes:
+                    end_user_id = all_entity_nodes[0].end_user_id
+
+                    # Neo4j 写入完成后，用 PgSQL 权威 aliases 覆盖 Neo4j 用户实体
+                    try:
+                        from app.repositories.end_user_info_repository import EndUserInfoRepository
+                        if end_user_id:
+                            with get_db_context() as db_session:
+                                info = EndUserInfoRepository(db_session).get_by_end_user_id(uuid.UUID(end_user_id))
+                                pg_aliases = info.aliases if info and info.aliases else []
+                            if info is not None:
+                                # 将 Python 侧占位名集合作为参数传入，避免 Cypher 硬编码
+                                placeholder_names = list(_USER_PLACEHOLDER_NAMES)
+                                await neo4j_connector.execute_query(
+                                    """
+                                    MATCH (e:ExtractedEntity)
+                                    WHERE e.end_user_id = $end_user_id AND toLower(e.name) IN $placeholder_names
+                                    SET e.aliases = $aliases
+                                    """,
+                                    end_user_id=end_user_id, aliases=pg_aliases,
+                                    placeholder_names=placeholder_names,
+                                )
+                                logger.info(f"[AliasSync] Neo4j 用户实体 aliases 已用 PgSQL 权威源覆盖: {pg_aliases}")
+                    except Exception as sync_err:
+                        logger.warning(f"[AliasSync] PgSQL→Neo4j aliases 同步失败（不影响主流程）: {sync_err}")
+
+                    # 使用 Celery 异步任务触发聚类（不阻塞主流程）
+                    try:
+                        from app.tasks import run_incremental_clustering
+                        
+                        new_entity_ids = [e.id for e in all_entity_nodes]
+                        task = run_incremental_clustering.apply_async(
+                            kwargs={
+                                "end_user_id": end_user_id,
+                                "new_entity_ids": new_entity_ids,
+                                "llm_model_id": str(memory_config.llm_model_id) if memory_config.llm_model_id else None,
+                                "embedding_model_id": str(memory_config.embedding_model_id) if memory_config.embedding_model_id else None,
+                            },
+                            priority=3,
+                        )
+                        logger.info(
+                            f"[Clustering] 增量聚类任务已提交到 Celery - "
+                            f"task_id={task.id}, end_user_id={end_user_id}, entity_count={len(new_entity_ids)}"
+                        )
+                    except Exception as e:
+                        logger.error(f"[Clustering] 提交聚类任务失败（不影响主流程）: {e}", exc_info=True)
+                
                 break
             else:
                 logger.warning("Failed to save some data to Neo4j")
@@ -202,9 +273,8 @@ async def write(
         summaries = await memory_summary_generation(
             chunked_dialogs, llm_client=llm_client, embedder_client=embedder_client, language=language
         )
-
+        ms_connector = Neo4jConnector()
         try:
-            ms_connector = Neo4jConnector()
             await add_memory_summary_nodes(summaries, ms_connector)
             await add_memory_summary_statement_edges(summaries, ms_connector)
         finally:
@@ -225,5 +295,63 @@ async def write(
     with open(log_file, "a", encoding="utf-8") as f:
         f.write(f"=== Pipeline Run Completed: {timestamp} ===\n\n")
 
+    # 将提取统计写入 Redis，按 workspace_id 存储
+    try:
+        from app.cache.memory.activity_stats_cache import ActivityStatsCache
+
+        stats_to_cache = {
+            "chunk_count": len(all_chunk_nodes) if all_chunk_nodes else 0,
+            "statements_count": len(all_statement_nodes) if all_statement_nodes else 0,
+            "triplet_entities_count": len(all_entity_nodes) if all_entity_nodes else 0,
+            "triplet_relations_count": len(all_entity_entity_edges) if all_entity_entity_edges else 0,
+            "temporal_count": 0,
+        }
+        await ActivityStatsCache.set_activity_stats(
+            workspace_id=str(memory_config.workspace_id),
+            stats=stats_to_cache,
+        )
+        logger.info(f"[WRITE] 活动统计已写入 Redis: workspace_id={memory_config.workspace_id}")
+    except Exception as cache_err:
+        logger.warning(f"[WRITE] 写入活动统计缓存失败（不影响主流程）: {cache_err}", exc_info=True)
+
+    # 同步 Neo4j 记忆节点总数到 PostgreSQL end_users.memory_count
+    if end_user_id:
+        try:
+            memory_count_connector = Neo4jConnector()
+            try:
+                node_count = await sync_end_user_memory_count_from_neo4j(
+                    end_user_id,
+                    memory_count_connector,
+                )
+            finally:
+                await memory_count_connector.close()
+
+            logger.info(
+                f"[MemoryCount] 写入后同步 memory_count: "
+                f"end_user_id={end_user_id}, count={node_count}"
+            )
+        except Exception as e:
+            logger.warning(
+                f"[MemoryCount] 写入后同步 memory_count 失败（不影响主流程）: {e}",
+                exc_info=True,
+            )
+    
+    # Close LLM/Embedder underlying httpx clients to prevent
+    # 'RuntimeError: Event loop is closed' during garbage collection
+    for client_obj in (llm_client, embedder_client):
+        try:
+            underlying = getattr(client_obj, 'client', None) or getattr(client_obj, 'model', None)
+            if underlying is None:
+                continue
+            # Unwrap RedBearLLM / RedBearEmbeddings to get the LangChain model
+            inner = getattr(underlying, '_model', underlying)
+            # LangChain OpenAI models expose async_client (httpx.AsyncClient)
+            http_client = getattr(inner, 'async_client', None)
+            if http_client is not None and hasattr(http_client, 'aclose'):
+                await http_client.aclose()
+        except Exception:
+            pass
+
     logger.info("=== Pipeline Complete ===")
-    logger.info(f"Total execution time: {total_time:.2f} seconds")
+    logger.info(f"Total execution time: {total_time:.2f} seconds")
+

api/app/core/memory/analytics/hot_memory_tags.py

@@ -1,9 +1,12 @@
 import asyncio
 import json
+import logging
 import os
 from typing import List, Tuple
 
 from app.core.config import settings
+
+logger = logging.getLogger(__name__)
 from app.core.memory.utils.llm.llm_utils import MemoryClientFactory
 from app.db import get_db_context
 from app.repositories.neo4j.neo4j_connector import Neo4jConnector
@@ -16,6 +19,10 @@ class FilteredTags(BaseModel):
     """用于接收LLM筛选后的核心标签列表的模型。"""
     meaningful_tags: List[str] = Field(..., description="从原始列表中筛选出的具有核心代表意义的名词列表。")
 
+class InterestTags(BaseModel):
+    """用于接收LLM筛选后的兴趣活动标签列表的模型。"""
+    interest_tags: List[str] = Field(..., description="从原始列表中筛选出的代表用户兴趣活动的标签列表。")
+
 async def filter_tags_with_llm(tags: List[str], end_user_id: str) -> List[str]:
     """
     使用LLM筛选标签列表，仅保留具有代表性的核心名词。
@@ -85,10 +92,74 @@ async def filter_tags_with_llm(tags: List[str], end_user_id: str) -> List[str]:
         return structured_response.meaningful_tags
 
     except Exception as e:
-        print(f"LLM筛选过程中发生错误: {e}")
+        logger.error(f"LLM筛选过程中发生错误: {e}", exc_info=True)
         # 在LLM失败时返回原始标签，确保流程继续
         return tags
 
+async def filter_interests_with_llm(tags: List[str], end_user_id: str, language: str = "zh") -> List[str]:
+    """
+    使用LLM从标签列表中筛选出代表用户兴趣活动的标签。
+    
+    与 filter_tags_with_llm 不同，此函数专注于识别"活动/行为"类兴趣，
+    过滤掉纯物品、工具、地点等不代表用户主动参与活动的名词。
+    
+    Args:
+        tags: 原始标签列表
+        end_user_id: 用户ID，用于获取LLM配置
+        
+    Returns:
+        筛选后的兴趣活动标签列表
+    """
+    try:
+        with get_db_context() as db:
+            from app.services.memory_agent_service import (
+                get_end_user_connected_config,
+            )
+            connected_config = get_end_user_connected_config(end_user_id, db)
+            config_id = connected_config.get("memory_config_id")
+            workspace_id = connected_config.get("workspace_id")
+
+            if not config_id and not workspace_id:
+                raise ValueError(
+                    f"No memory_config_id found for end_user_id: {end_user_id}."
+                )
+
+            config_service = MemoryConfigService(db)
+            memory_config = config_service.load_memory_config(
+                config_id=config_id,
+                workspace_id=workspace_id
+            )
+
+            if not memory_config.llm_model_id:
+                raise ValueError(
+                    f"No llm_model_id found in memory config {config_id}."
+                )
+
+            factory = MemoryClientFactory(db)
+            llm_client = factory.get_llm_client(memory_config.llm_model_id)
+
+        tag_list_str = ", ".join(tags)
+        from app.core.memory.utils.prompt.prompt_utils import render_interest_filter_prompt
+        rendered_prompt = render_interest_filter_prompt(tag_list_str, language=language)
+        messages = [
+            {
+                "role": "user",
+                "content": rendered_prompt
+            }
+        ]
+
+        structured_response = await llm_client.response_structured(
+            messages=messages,
+            response_model=InterestTags
+        )
+
+        return structured_response.interest_tags
+
+    except Exception as e:
+        logger.error(f"兴趣标签LLM筛选过程中发生错误: {e}", exc_info=True)
+        return tags
+
+
 async def get_raw_tags_from_db(
     connector: Neo4jConnector,
     end_user_id: str,
@@ -139,14 +210,14 @@ async def get_raw_tags_from_db(
     
     return [(record["name"], record["frequency"]) for record in results]
 
-async def get_hot_memory_tags(end_user_id: str, limit: int = 40, by_user: bool = False) -> List[Tuple[str, int]]:
+async def get_hot_memory_tags(end_user_id: str, limit: int = 10, by_user: bool = False) -> List[Tuple[str, int]]:
     """
     获取原始标签，然后使用LLM进行筛选，返回最终的热门标签列表。
-    查询更多的标签(limit=40)给LLM提供更丰富的上下文进行筛选。
+    查询更多的标签(40条)给LLM提供更丰富的上下文进行筛选，但最终返回数量由limit参数控制。
 
     Args:
         end_user_id: 必需参数。如果by_user=False，则为end_user_id；如果by_user=True，则为user_id
-        limit: 返回的标签数量限制
+        limit: 最终返回的标签数量限制（默认10）
         by_user: 是否按user_id查询（默认False，按end_user_id查询）
         
     Raises:
@@ -161,8 +232,9 @@ async def get_hot_memory_tags(end_user_id: str, limit: int = 40, by_user: bool =
     # 使用项目的Neo4jConnector
     connector = Neo4jConnector()
     try:
-        # 1. 从数据库获取原始排名靠前的标签
-        raw_tags_with_freq = await get_raw_tags_from_db(connector, end_user_id, limit, by_user=by_user)
+        # 1. 从数据库获取原始排名靠前的标签（查询40条给LLM提供更丰富的上下文）
+        query_limit = 40
+        raw_tags_with_freq = await get_raw_tags_from_db(connector, end_user_id, query_limit, by_user=by_user)
         if not raw_tags_with_freq:
             return []
 
@@ -177,7 +249,61 @@ async def get_hot_memory_tags(end_user_id: str, limit: int = 40, by_user: bool =
             if tag in meaningful_tag_names:
                 final_tags.append((tag, freq))
 
-        return final_tags
+        # 4. 限制返回的标签数量
+        return final_tags[:limit]
     finally:
         # 确保关闭连接
         await connector.close()
+
+async def get_interest_distribution(end_user_id: str, limit: int = 10, by_user: bool = False, language: str = "zh") -> List[Tuple[str, int]]:
+    """
+    获取用户的兴趣分布标签。
+    
+    与 get_hot_memory_tags 不同，此函数使用专门针对"活动/行为"的LLM prompt，
+    过滤掉纯物品、工具、地点等，只保留能代表用户兴趣爱好的活动类标签。
+
+    Args:
+        end_user_id: 必需参数。如果by_user=False，则为end_user_id；如果by_user=True，则为user_id
+        limit: 最终返回的标签数量限制（默认10）
+        by_user: 是否按user_id查询（默认False，按end_user_id查询）
+
+    Raises:
+        ValueError: 如果end_user_id未提供或为空
+    """
+    if not end_user_id or not end_user_id.strip():
+        raise ValueError(
+            "end_user_id is required. Please provide a valid end_user_id or user_id."
+        )
+
+    connector = Neo4jConnector()
+    try:
+        # 查询更多原始标签，给LLM提供充足上下文
+        query_limit = 40
+        raw_tags_with_freq = await get_raw_tags_from_db(connector, end_user_id, query_limit, by_user=by_user)
+        if not raw_tags_with_freq:
+            return []
+
+        raw_tag_names = [tag for tag, freq in raw_tags_with_freq]
+        raw_freq_map = {tag: freq for tag, freq in raw_tags_with_freq}
+
+        # 使用兴趣活动专用prompt进行筛选（支持语义推断出新标签）
+        interest_tag_names = await filter_interests_with_llm(raw_tag_names, end_user_id, language=language)
+
+        # 构建最终标签列表：
+        # - 原始标签中存在的，保留原始频率
+        # - LLM推断出的新标签（不在原始列表中），赋予默认频率1
+        final_tags = []
+        seen = set()
+        for tag in interest_tag_names:
+            if tag in seen:
+                continue
+            seen.add(tag)
+            freq = raw_freq_map.get(tag, 1)
+            final_tags.append((tag, freq))
+
+        # 按频率降序排列
+        final_tags.sort(key=lambda x: x[1], reverse=True)
+
+        return final_tags[:limit]
+    finally:
+        await connector.close()

api/app/core/memory/enums.py

@@ -0,0 +1,31 @@
+from enum import StrEnum
+
+
+class StorageType(StrEnum):
+    NEO4J = 'neo4j'
+    RAG = 'rag'
+
+
+class Neo4jStorageStrategy(StrEnum):
+    WINDOW = 'window'
+    TIMELINE = 'timeline'
+    AGGREGATE = "aggregate"
+
+
+class SearchStrategy(StrEnum):
+    DEEP = "0"
+    NORMAL = "1"
+    QUICK = "2"
+
+
+class Neo4jNodeType(StrEnum):
+    CHUNK = "Chunk"
+    COMMUNITY = "Community"
+    DIALOGUE = "Dialogue"
+    EXTRACTEDENTITY = "ExtractedEntity"
+    MEMORYSUMMARY = "MemorySummary"
+    PERCEPTUAL = "Perceptual"
+    STATEMENT = "Statement"
+
+    RAG = "Rag"
+

api/app/core/memory/llm_tools/chunker_client.py

@@ -1,10 +1,10 @@
-from typing import Any, List
-import re
-import os
 import asyncio
 import json
-import numpy as np
 import logging
+import os
+from typing import Any, List
+
+import numpy as np
 
 # Fix tokenizer parallelism warning
 os.environ["TOKENIZERS_PARALLELISM"] = "false"
@@ -21,6 +21,7 @@ from chonkie import (
 
 from app.core.memory.models.config_models import ChunkerConfig
 from app.core.memory.models.message_models import DialogData, Chunk
+
 try:
     from app.core.memory.llm_tools.openai_client import OpenAIClient
 except Exception:
@@ -32,6 +33,7 @@ logger = logging.getLogger(__name__)
 
 class LLMChunker:
     """LLM-based intelligent chunking strategy"""
+
     def __init__(self, llm_client: OpenAIClient, chunk_size: int = 1000):
         self.llm_client = llm_client
         self.chunk_size = chunk_size
@@ -46,7 +48,8 @@ class LLMChunker:
             """
 
         messages = [
-            {"role": "system", "content": "You are a professional text analysis assistant, skilled at splitting long texts into semantically coherent paragraphs."},
+            {"role": "system",
+             "content": "You are a professional text analysis assistant, skilled at splitting long texts into semantically coherent paragraphs."},
             {"role": "user", "content": prompt}
         ]
 
@@ -246,6 +249,7 @@ class ChunkerClient:
                             "total_sub_chunks": len(sub_chunks),
                             "chunker_strategy": self.chunker_config.chunker_strategy,
                         },
+                        files=msg.files
                     )
                     dialogue.chunks.append(chunk)
             else:
@@ -258,6 +262,7 @@ class ChunkerClient:
                         "message_role": msg.role,
                         "chunker_strategy": self.chunker_config.chunker_strategy,
                     },
+                    files=msg.files
                 )
                 dialogue.chunks.append(chunk)
 
@@ -309,7 +314,7 @@ class ChunkerClient:
             f.write("=" * 60 + "\n\n")
 
             for i, chunk in enumerate(dialogue.chunks):
-                f.write(f"Chunk {i+1}:\n")
+                f.write(f"Chunk {i + 1}:\n")
                 f.write(f"Size: {len(chunk.content)} characters\n")
                 if hasattr(chunk, 'metadata') and 'start_index' in chunk.metadata:
                     f.write(f"Position: {chunk.metadata.get('start_index')}-{chunk.metadata.get('end_index')}\n")

api/app/core/memory/llm_tools/llm_client.py

@@ -56,7 +56,7 @@ class LLMClient(ABC):
         self.max_retries = self.config.max_retries
         self.timeout = self.config.timeout
 
-        logger.info(
+        logger.debug(
             f"初始化 LLM 客户端: provider={self.provider}, "
             f"model={self.model_name}, max_retries={self.max_retries}"
         )

api/app/core/memory/llm_tools/openai_client.py

@@ -65,7 +65,7 @@ class OpenAIClient(LLMClient):
             type=type_
         )
 
-        logger.info(f"OpenAI 客户端初始化完成: type={type_}")
+        logger.debug(f"OpenAI 客户端初始化完成: type={type_}")
 
     async def chat(self, messages: List[Dict[str, str]], **kwargs) -> Any:
         """

api/app/core/memory/llm_tools/openai_embedder.py

@@ -2,6 +2,7 @@
 OpenAI Embedder 客户端实现
 
 基于 LangChain 和 RedBearEmbeddings 的 OpenAI 嵌入模型客户端实现。
+自动支持火山引擎的多模态 Embedding。
 """
 
 from typing import List
@@ -13,6 +14,7 @@ from app.core.memory.llm_tools.embedder_client import (
 )
 from app.core.models.base import RedBearModelConfig
 from app.core.models.embedding import RedBearEmbeddings
+from app.models.models_model import ModelProvider
 
 logger = logging.getLogger(__name__)
 
@@ -25,6 +27,7 @@ class OpenAIEmbedderClient(EmbedderClient):
     - 批量文本嵌入
     - 自动重试机制
     - 错误处理
+    - 火山引擎多模态 Embedding（自动识别）
     """
 
     def __init__(self, model_config: RedBearModelConfig):
@@ -36,7 +39,7 @@ class OpenAIEmbedderClient(EmbedderClient):
         """
         super().__init__(model_config)
 
-        # 初始化 RedBearEmbeddings 模型
+        # 初始化 RedBearEmbeddings（自动支持火山引擎多模态）
         self.model = RedBearEmbeddings(
             RedBearModelConfig(
                 model_name=self.model_name,
@@ -47,8 +50,9 @@ class OpenAIEmbedderClient(EmbedderClient):
                 timeout=self.timeout,
             )
         )
+        self.is_multimodal = self.model.is_multimodal_supported()
 
-        logger.info("OpenAI Embedder 客户端初始化完成")
+        logger.info(f"OpenAI Embedder 客户端初始化完成 (provider={self.provider}, multimodal={self.is_multimodal})")
 
     async def response(
         self,
@@ -77,7 +81,14 @@ class OpenAIEmbedderClient(EmbedderClient):
                 return []
 
             # 生成嵌入向量
-            embeddings = await self.model.aembed_documents(texts)
+            if self.is_multimodal:
+                # 火山引擎多模态 Embedding
+                embeddings = await self.model.aembed_multimodal(
+                    [{"type": "text", "text": text} for text in texts]
+                )
+            else:
+                # 普通 Embedding
+                embeddings = await self.model.aembed_documents(texts)
 
             logger.debug(f"成功生成 {len(embeddings)} 个嵌入向量")
             return embeddings

api/app/core/memory/memory_service.py

@@ -0,0 +1,58 @@
+from sqlalchemy.orm import Session
+
+from app.core.memory.enums import StorageType, SearchStrategy
+from app.core.memory.models.service_models import MemoryContext, MemorySearchResult
+from app.core.memory.pipelines.memory_read import ReadPipeLine
+from app.db import get_db_context
+from app.services.memory_config_service import MemoryConfigService
+
+
+class MemoryService:
+    def __init__(
+            self,
+            db: Session,
+            config_id: str | None,
+            end_user_id: str,
+            workspace_id: str | None = None,
+            storage_type: str = "neo4j",
+            user_rag_memory_id: str | None = None,
+            language: str = "zh",
+    ):
+        config_service = MemoryConfigService(db)
+        memory_config = None
+        if config_id is not None:
+            memory_config = config_service.load_memory_config(
+                config_id=config_id,
+                workspace_id=workspace_id,
+                service_name="MemoryService",
+            )
+        if memory_config is None and storage_type.lower() == "neo4j":
+            raise RuntimeError("Memory configuration for unspecified users")
+        self.ctx = MemoryContext(
+            end_user_id=end_user_id,
+            memory_config=memory_config,
+            storage_type=StorageType(storage_type),
+            user_rag_memory_id=user_rag_memory_id,
+            language=language,
+        )
+
+    async def write(self, messages: list[dict]) -> str:
+        raise NotImplementedError
+
+    async def read(
+            self,
+            query: str,
+            search_switch: SearchStrategy,
+            limit: int = 10,
+    ) -> MemorySearchResult:
+        with get_db_context() as db:
+            return await ReadPipeLine(self.ctx, db).run(query, search_switch, limit)
+
+    async def forget(self, max_batch: int = 100, min_days: int = 30) -> dict:
+        raise NotImplementedError
+
+    async def reflect(self) -> dict:
+        raise NotImplementedError
+
+    async def cluster(self, new_entity_ids: list[str] = None) -> None:
+        raise NotImplementedError

api/app/core/memory/models/__init__.py

@@ -58,6 +58,14 @@ from app.core.memory.models.triplet_models import (
     TripletExtractionResponse,
 )
 
+# User metadata models
+from app.core.memory.models.metadata_models import (
+    UserMetadata,
+    UserMetadataProfile,
+    MetadataExtractionResponse,
+    MetadataFieldChange,
+)
+
 # Ontology scenario models (LLM extracted from scenarios)
 from app.core.memory.models.ontology_scenario_models import (
     OntologyClass,
@@ -124,6 +132,10 @@ __all__ = [
     "Entity",
     "Triplet",
     "TripletExtractionResponse",
+    "UserMetadata",
+    "UserMetadataProfile",
+    "MetadataExtractionResponse",
+    "MetadataFieldChange",
     # Ontology models
     "OntologyClass",
     "OntologyExtractionResponse",

api/app/core/memory/models/config_models.py

@@ -6,11 +6,12 @@ of the memory system including LLM, chunking, pruning, and search.
 Classes:
     LLMConfig: Configuration for LLM client
     ChunkerConfig: Configuration for dialogue chunking
+    OntologyClassInfo: Single ontology class with name and description
     PruningConfig: Configuration for semantic pruning
     TemporalSearchParams: Parameters for temporal search queries
 """
 
-from typing import Optional
+from typing import Optional, List
 from pydantic import BaseModel, Field
 
 
@@ -50,22 +51,42 @@ class ChunkerConfig(BaseModel):
     min_characters_per_chunk: Optional[int] = Field(24, ge=0, description="The minimum number of characters in each chunk.")
 
 
+class OntologyClassInfo(BaseModel):
+    """本体类型的名称与语义描述，用于剪枝提示词注入。
+
+    Attributes:
+        class_name: 本体类型名称（如"患者"、"课程"）
+        class_description: 本体类型语义描述，告知 LLM 该类型在当前场景下的含义
+    """
+    class_name: str = Field(..., description="本体类型名称")
+    class_description: str = Field(default="", description="本体类型语义描述")
+
+
 class PruningConfig(BaseModel):
     """Configuration for semantic pruning of dialogue content.
 
     Attributes:
         pruning_switch: Enable or disable semantic pruning
-        pruning_scene: Scene type for pruning ('education', 'online_service', 'outbound')
+        pruning_scene: Scene name for pruning from ontology_scene table
         pruning_threshold: Pruning ratio (0-0.9, max 0.9 to avoid complete removal)
+        scene_id: Optional ontology scene UUID
+        ontology_class_infos: Full ontology class info (name + description) from
+            ontology_class table, injected into the pruning prompt to drive
+            scene-aware preservation decisions
     """
     pruning_switch: bool = Field(False, description="Enable semantic pruning when True.")
     pruning_scene: str = Field(
         "education",
-        description="Scene for pruning: one of 'education', 'online_service', 'outbound'.",
+        description="Scene name from ontology_scene table.",
     )
     pruning_threshold: float = Field(
         0.5, ge=0.0, le=0.9,
         description="Pruning ratio within 0-0.9 (max 0.9 to avoid termination).")
+    scene_id: Optional[str] = Field(None, description="Ontology scene UUID (optional).")
+    ontology_class_infos: List[OntologyClassInfo] = Field(
+        default_factory=list,
+        description="Full ontology class info (name + description) injected into pruning prompt."
+    )
 
 
 class TemporalSearchParams(BaseModel):