chore(align): sync Git with running container as authoritative source

Standards alignment (STANDARDS_AUDIT_2026-07-24): Phase 1 标准化核心 +
Phase 2 质量层 landed in the running container and captured in Git so the
three sources (container := image := Git) agree.

Backend (Phase 1 标准化核心):
- mcp_client.py: replaced hand-rolled JSON-RPC with official `mcp` SDK
  (ClientSession, streamable_http/sse transports, protocol auto-negotiation)
- core/otel.py + core/observability.py: standard OpenTelemetry SDK bridge
  (OTLP gRPC), wired to Grafana Alloy (qihu-aiflow-alloy:4317) which forwards
  metrics to Prometheus; emits aiflow_span_duration_ms / aiflow_span_count
- deployments: Grafana Alloy container + Prometheus remote-write receiver

Backend (Phase 2 质量层):
- core/rag_pipeline.py: standardized RAG (recursive overlap chunking +
  rerank hook) reusing pgvector_search
- core/llm_client.py: SDK-ified LLM + embeddings (aembed/embed) collapsing
  hand-rolled httpx calls; trust_env=False to bypass container proxy

Migrations:
- 018_normalize_marketapp_scene.sql: fixed capability allowlist
  (prevents capability wipe on restart)

Alignment performed 2026-07-24 12:18:51. No deletions; secrets/venv/node_modules/
caches were not touched (tracked-source-only copy).

backend/python/app/api/chat_service.py

@@ -107,6 +107,8 @@ from app.api.chat_media import (_generate_media_task, detect_ambiguous_creative_
 from app.api.chat_skill import (_discover_installed_skills, _execute_skill_tool, _resolve_market_agents, _resolve_market_skills)
 
 from app.api.chat_utils import (SendMessageRequest, _proxy_for_url, cst_now, logger)
+# 统一模型层(07-24 红线)：web chat 与 IM bot 共用标准 OpenAI SDK 客户端
+from app.core.llm_client import achat_complete
 
 
 
@@ -2370,168 +2372,21 @@ async def _send_message_core(
 
 
 
-                            async with httpx.AsyncClient(
+                            async with span("llm.completion", model=ai_model.id if ai_model else None):
-
+                                try:
-
+                                    data = await achat_complete(
-
-
-
-
-
-                                timeout=ai_model.timeout or 120,
-
-
-
-
-
-
-
-                                proxy=_proxy_for_url(api_url),
-
-
-
-
-
-
-
-                                trust_env=False,
-
-
-
-
-
-
-
-                            ) as client:
-
-
-
-
-
-
-
-                                async with span("llm.completion", model=ai_model.id if ai_model else None):
-
-                                    resp = await client.post(
-
-
-
-
-
-
-
                                         api_url,
-
+                                        api_key,
-
+                                        request_body,
-
+                                        proxy=_proxy_for_url(api_url),
-
+                                        timeout=ai_model.timeout or 120,
-
-
-
-                                        headers={
-
-
-
-
-
-
-
-                                            "Authorization": f"Bearer {api_key}",
-
-
-
-
-
-
-
-                                            "Content-Type": "application/json"
-
-
-
-
-
-
-
-                                        },
-
-
-
-
-
-
-
-                                        json=request_body
-
-
-
-
-
-
-
                                     )
-
+                                except Exception as _exc:
-
-
-
-
-
-
-                                if resp.status_code != 200:
-
-
-
-
-
-
-
                                     if round_num == 0:
-
+                                        ai_content = f"AI模型调用失败 ({type(_exc).__name__}: {str(_exc)[:120]}), 请检查模型配置。"
-
+                                    logger.warning(f"[chat] 模型 {ai_model.name} 调用异常: {_exc}")
-
-
-
-
-
-                                        ai_content = f"AI模型调用失败 (HTTP {resp.status_code}), 请检查模型配置。"
-
-
-
-
-
-
-
                                     break
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-                                data = resp.json()
-
-
-
-
-
-
-
                                 choice = data.get("choices", [{}])[0]
-
-
-
-
-
-
-
                                 message = choice.get("message", {})
 
 

backend/python/app/api/im_llm.py

@@ -24,6 +24,7 @@ from typing import Optional
 from urllib.parse import urlparse as _urlparse
 
 import httpx
+from app.core.llm_client import chat_complete  # 统一模型层(07-24): web/IM 共用标准 OpenAI SDK 客户端
 from sqlalchemy.orm import Session
 
 from ..capability_registry import resolve_auto_model
@@ -226,21 +227,19 @@ def _call_real_llm(db: Session, user=None, prompt: str = "", platform: str = "im
                             {"type": "function", "function": fd} for fd in function_definitions
                         ]
                         request_body["tool_choice"] = "auto"
-                    with httpx.Client(
+                    try:
-                        timeout=ai_model.timeout or 120,
+                        data = chat_complete(
-                        proxy=_proxy_for_url(api_url),
-                        trust_env=False,
-                    ) as client:
-                        resp = client.post(
                             api_url,
-                            headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+                            api_key,
-                            json=request_body,
+                            request_body,
+                            proxy=_proxy_for_url(api_url),
+                            timeout=ai_model.timeout or 120,
                         )
-                        if resp.status_code != 200:
+                    except Exception as _exc:
-                            _retry_log.append(f"{ai_model.name}: HTTP {resp.status_code}")
+                        _retry_log.append(f"{ai_model.name}: {str(_exc)[:60]}")
-                            _http_ok = False
+                        logger.warning(f"[im_llm] 模型 {ai_model.name} 异常: {_exc}")
-                            break
+                        _http_ok = False
-                        data = resp.json()
+                        break
                         message = data.get("choices", [{}])[0].get("message", {})
                         tool_calls = message.get("tool_calls", [])
                         if tool_calls and skills:

backend/python/app/core/llm_client.py

@@ -0,0 +1,181 @@
+"""Shared, standards-based LLM client for web chat + IM bot.
+
+平台红线(07-24)：模型层以成熟/开源标准为设计基准。本模块使用官方 OpenAI SDK
+(`openai.AsyncOpenAI`)——它是 OpenAI 兼容端点的事实标准客户端。平台本身已在讲
+OpenAI 协议(`/v1/chat/completions`)，因此零协议改造成本，并天然获得：
+  * 原生 SSE 流式(`stream=True`)；
+  * 结构化的 tool_calls / usage 解析；
+  * 统一的代理(trust_env=False + 显式 proxy)与超时处理。
+
+本模块取代 chat_service.py 与 im_llm.py 中两套手写 httpx 循环，使 web chat 与
+IM bot 共用**同一模型层**、同一套 failover/代理/超时语义——这是「各端能力统一对齐」
+红线在模型层的落地。
+
+API:
+  achat_complete(api_url, api_key, request_body, *, proxy=None, timeout=120, stream=False)
+    - stream=False -> dict，形状对齐上游 `data` 响应：
+        {"choices":[{"message":{"content","tool_calls","reasoning_content"}}], "usage":{...}}
+    - stream=True  -> async generator，逐块产出 ("content"|"reasoning", text) 增量
+"""
+from __future__ import annotations
+
+import httpx
+from openai import AsyncOpenAI, OpenAI
+
+
+def _base_url(api_url: str) -> str:
+    """从完整 /v1/chat/completions 或 /v1/embeddings 地址推导 OpenAI SDK 所需的 base_url。"""
+    u = (api_url or "").rstrip()
+    for suf in ("/v1/chat/completions", "/chat/completions", "/v1/embeddings", "/embeddings"):
+        if u.endswith(suf):
+            return u[: -len(suf)]
+    return u
+
+
+def build_openai_client(api_url, api_key, *, proxy=None, timeout=120) -> AsyncOpenAI:
+    base = _base_url(api_url)
+    # 始终 trust_env=False：避免容器 HTTP_PROXY 对国内端点(siliconflow 等)造成 502；
+    # 代理经 proxy 显式传入（AGNES 等），未传则直连。
+    http_client = httpx.AsyncClient(proxy=proxy, trust_env=False)
+    return AsyncOpenAI(
+        base_url=base,
+        api_key=api_key or "EMPTY",
+        timeout=timeout,
+        http_client=http_client,
+    )
+
+
+def _create_kwargs(request_body: dict) -> dict:
+    kw = {
+        "model": request_body.get("model"),
+        "messages": request_body.get("messages", []),
+        "stream": False,
+    }
+    if request_body.get("temperature") is not None:
+        kw["temperature"] = request_body["temperature"]
+    if request_body.get("top_p") is not None:
+        kw["top_p"] = request_body["top_p"]
+    if request_body.get("max_tokens") is not None:
+        kw["max_tokens"] = request_body["max_tokens"]
+    if request_body.get("stop") is not None:
+        kw["stop"] = request_body["stop"]
+    tools = request_body.get("tools")
+    if tools:
+        kw["tools"] = tools
+        kw["tool_choice"] = request_body.get("tool_choice", "auto")
+    return kw
+
+
+def _normalize_tool_calls(tcs):
+    if not tcs:
+        return None
+    out = []
+    for tc in tcs:
+        out.append(
+            {
+                "id": getattr(tc, "id", None),
+                "type": "function",
+                "function": {
+                    "name": getattr(tc.function, "name", None),
+                    "arguments": getattr(tc.function, "arguments", "") or "",
+                },
+            }
+        )
+    return out
+
+
+async def achat_complete(api_url, api_key, request_body, *, proxy=None, timeout=120, stream=False):
+    """统一的 OpenAI 兼容聊天补全。详见模块 docstring。"""
+    if stream:
+
+        async def _gen():
+            client = build_openai_client(api_url, api_key, proxy=proxy, timeout=timeout)
+            try:
+                gen = await client.chat.completions.create(
+                    **_create_kwargs(request_body), stream=True
+                )
+                async for chunk in gen:
+                    if not chunk.choices:
+                        continue
+                    delta = chunk.choices[0].delta
+                    rc = getattr(delta, "reasoning_content", None)
+                    if rc:
+                        yield ("reasoning", rc)
+                    ct = getattr(delta, "content", None)
+                    if ct:
+                        yield ("content", ct)
+            finally:
+                await client.close()
+
+        return _gen()
+
+    client = build_openai_client(api_url, api_key, proxy=proxy, timeout=timeout)
+    async with client:
+        resp = await client.chat.completions.create(**_create_kwargs(request_body))
+        msg = resp.choices[0].message
+        return {
+            "choices": [
+                {
+                    "message": {
+                        "content": msg.content or "",
+                        "tool_calls": _normalize_tool_calls(getattr(msg, "tool_calls", None)),
+                        "reasoning_content": getattr(msg, "reasoning_content", None),
+                    }
+                }
+            ],
+            "usage": (resp.usage.model_dump() if resp.usage else {}),
+        }
+
+
+def build_openai_client_sync(api_url, api_key, *, proxy=None, timeout=120) -> OpenAI:
+    """同步客户端工厂（供 IM bot 等同步上下文复用同一标准模型层）。"""
+    base = _base_url(api_url)
+    http_client = httpx.Client(proxy=proxy, trust_env=False)
+    return OpenAI(base_url=base, api_key=api_key or "EMPTY", timeout=timeout, http_client=http_client)
+
+
+def chat_complete(api_url, api_key, request_body, *, proxy=None, timeout=120):
+    """同步版（与 achat_complete 行为/返回形状完全一致），供非 async 上下文使用。"""
+    client = build_openai_client_sync(api_url, api_key, proxy=proxy, timeout=timeout)
+    with client:
+        resp = client.chat.completions.create(**_create_kwargs(request_body))
+        msg = resp.choices[0].message
+        return {
+            "choices": [
+                {
+                    "message": {
+                        "content": msg.content or "",
+                        "tool_calls": _normalize_tool_calls(getattr(msg, "tool_calls", None)),
+                        "reasoning_content": getattr(msg, "reasoning_content", None),
+                    }
+                }
+            ],
+            "usage": (resp.usage.model_dump() if resp.usage else {}),
+        }
+
+
+# ---------------------------------------------------------------------------
+# 嵌入（Embeddings）：OpenAI 兼容 /v1/embeddings，收敛散落的裸 httpx 嵌入调用
+# ---------------------------------------------------------------------------
+def _embed_kwargs(input, model):
+    return {"model": model, "input": input if isinstance(input, list) else [input]}
+
+
+async def aembed(api_url, api_key, input, model, *, proxy=None, timeout=60) -> list:
+    """统一的 OpenAI 兼容文本嵌入（异步）。返回 list[list[float]]。
+
+    供 pgvector_search.get_embedding 等 embeddings 路径复用，把散落的裸 httpx
+    嵌入调用收敛到同一标准模型层（与聊天共用代理/超时/failover 语义）。
+    """
+    client = build_openai_client(api_url, api_key, proxy=proxy, timeout=timeout)
+    async with client:
+        resp = await client.embeddings.create(**_embed_kwargs(input, model))
+        return [d.embedding for d in resp.data]
+
+
+def embed(api_url, api_key, input, model, *, proxy=None, timeout=60) -> list:
+    """同步版嵌入（与非 async 上下文复用同一标准模型层）。"""
+    client = build_openai_client_sync(api_url, api_key, proxy=proxy, timeout=timeout)
+    with client:
+        resp = client.embeddings.create(**_embed_kwargs(input, model))
+        return [d.embedding for d in resp.data]

backend/python/app/core/observability.py

@@ -1,6 +1,6 @@
 """
-Qihu-AIFlow 统一可观测基座 (Phase 2.1)
+Qihu-AIFlow 统一可观测基座 (Phase 2.1 + Phase 1.I OTel 增强)
-=====================================
+=============================================================
 提供贯穿一次请求的全局链路 ID（trace_id）与结构化日志能力，
 为后续重构（上下文引擎、媒体/LLM 成本归因）建立回归基线。
 
@@ -10,13 +10,17 @@ Qihu-AIFlow 统一可观测基座 (Phase 2.1)
   TraceIdFilter 自动注入，调用方无需改动。
 - 不引入第三方依赖（structlog 未安装），自带可选的 JSON formatter。
 
+Phase 1.I 增强：span() 在保持原有日志计时的同时，额外嵌套一个标准 OpenTelemetry
+span（经 app.core.otel 桥接，OTLP 导出到 Grafana）。OTel 失败时自动降级为 no-op，
+绝不改变既有日志行为与请求链路。
+
 使用方式：
     from app.core.observability import set_trace_id, get_trace_id, span
 
     # 在中间件里为每个请求注入：
     set_trace_id(request_id)
 
-    # 在关键调用处打计时 span（自动带 trace_id）：
+    # 在关键调用处打计时 span（自动带 trace_id + OTel span）：
     async with span("chat.send_message", conv_id=conv_id):
         return await _send_message_core(...)
 """
@@ -26,6 +30,8 @@ import uuid
 import json
 from contextvars import ContextVar
 
+from app.core.otel import current_span_cm, record_span_metrics
+
 # ---------------------------------------------------------------------------
 # trace_id：贯穿一次请求（含其内所有子调用/协程）的全局链路 ID
 # ---------------------------------------------------------------------------
@@ -103,10 +109,10 @@ def get_logger(name: str | None = None) -> logging.Logger:
 
 
 # ---------------------------------------------------------------------------
-# span：结构化计时上下文管理器（耗时 + trace_id + 自定义字段）
+# span：结构化计时上下文管理器（耗时 + trace_id + 自定义字段 + OTel 嵌套）
 # ---------------------------------------------------------------------------
 class _Span:
-    """同步/异步通用的计时 span。退出时记录 elapsed_ms 与状态。"""
+    """同步/异步通用的计时 span。退出时记录 elapsed_ms 与状态，并结束嵌套的 OTel span。"""
 
     def __init__(self, name: str, **fields):
         self.name = name
@@ -114,6 +120,7 @@ class _Span:
         self._logger = logging.getLogger("aiflow.span")
         self._start = None
         self.elapsed_ms = 0.0
+        self._otel_cm = None  # 嵌套的 OTel span 上下文管理器
 
     def _enter(self):
         self._start = time.perf_counter()
@@ -121,6 +128,10 @@ class _Span:
             f"SPAN_START {self.name}",
             extra={"span": self.name, "event": "start", "trace_id": get_trace_id(), **self.fields},
         )
+        # OTel 嵌套 span（失败安全：current_span_cm 返回 None 时 no-op）
+        self._otel_cm = current_span_cm(self.name, self.fields)
+        if self._otel_cm is not None:
+            self._otel_cm.__enter__()
         return self
 
     def _exit(self, exc_type, exc, tb):
@@ -137,6 +148,24 @@ class _Span:
                 **self.fields,
             },
         )
+        # 结束嵌套的 OTel span（失败安全）
+        if self._otel_cm is not None:
+            try:
+                from opentelemetry import trace as _ot
+                if exc_type is not None:
+                    self._otel_cm.set_status(
+                        _ot.trace.Status(_ot.trace.StatusCode.ERROR, str(exc_type.__name__))
+                    )
+                else:
+                    self._otel_cm.set_status(_ot.trace.Status(_ot.trace.StatusCode.OK))
+                self._otel_cm.__exit__(exc_type, exc, tb)
+            except Exception:
+                pass
+        # 记录 span 指标（耗时直方图 + 计数），供 Grafana 出图（失败安全）
+        try:
+            record_span_metrics(self.name, self.elapsed_ms, status)
+        except Exception:
+            pass
         return False  # 不吞掉异常
 
     # 同步协议

backend/python/app/core/otel.py

@@ -0,0 +1,131 @@
+"""
+OpenTelemetry 桥接 (Phase 1.I 标准化)
+=====================================
+设计基准（标准对照表见 STANDARDS_AUDIT_2026-07-24.md §I）：
+- 标准：OpenTelemetry SDK + OTLP gRPC exporter —— 云原生可观测事实标准。
+- traces：span 经 observability.span() 嵌套导出（见 observability.py）。
+- metrics：MeterProvider 经 OTLP 导出 span 耗时直方图 + 调用计数，供 Grafana 出图。
+- 失败安全（生产红线）：若 OTLP 端点不可达 / 初始化异常，自动降级为 no-op，
+  绝不阻断业务请求、不产生未捕获异常。
+- 门控：OTEL_ENABLED=1 默认开启；置 0 则零开销、不走 OTel。
+- 发射目标：OTEL_EXPORTER_OTLP_ENDPOINT，默认 http://qihu-aiflow-alloy:4317
+  （经 Grafana Alloy 桥接 OTLP→Prometheus，再由 Prometheus 喂给 Grafana 出图）。
+
+对外 API：
+    init_otel()            首次调用时构建 TracerProvider + MeterProvider（幂等）
+    get_tracer()           返回 tracer（未启用/失败则 None）
+    get_meter()            返回 meter（未启用/失败则 None）
+    current_span_cm(name)  返回一个 OTel span 的上下文管理器（供 observability 嵌套）
+    record_span_metrics(name, elapsed_ms, status)  记录 span 指标（耗时直方图 + 计数）
+"""
+
+import os
+import logging
+
+logger = logging.getLogger(__name__)
+
+_ENABLED = os.getenv("OTEL_ENABLED", "1") not in ("0", "false", "False", "")
+_ENDPOINT = os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT", "http://qihu-aiflow-alloy:4317").rstrip("/")
+if not _ENDPOINT.startswith("http://") and not _ENDPOINT.startswith("https://"):
+    _ENDPOINT = "http://" + _ENDPOINT
+
+_tracer = None
+_meter = None
+_initialized = False
+_duration_hist = None
+_span_counter = None
+
+
+def init_otel() -> None:
+    """构建 TracerProvider + MeterProvider（幂等）。失败则降级为 no-op。"""
+    global _tracer, _meter, _initialized
+    if _initialized:
+        return
+    _initialized = True
+    if not _ENABLED:
+        logger.info("[otel] disabled (OTEL_ENABLED=0)")
+        return
+    try:
+        from opentelemetry import trace, metrics
+        from opentelemetry.sdk.resources import Resource
+        from opentelemetry.semconv.resource import ResourceAttributes
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+        from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+            OTLPSpanExporter,
+        )
+        from opentelemetry.sdk.metrics import MeterProvider
+        from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+        from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import (
+            OTLPMetricExporter,
+        )
+
+        resource = Resource.create({ResourceAttributes.SERVICE_NAME: "qihu-aiflow"})
+
+        # --- traces ---
+        trace_provider = TracerProvider(resource=resource)
+        trace_provider.add_span_processor(
+            BatchSpanProcessor(OTLPSpanExporter(endpoint=_ENDPOINT, insecure=True))
+        )
+        trace.set_tracer_provider(trace_provider)
+        _tracer = trace.get_tracer("qihu-aiflow")
+
+        # --- metrics ---
+        metric_reader = PeriodicExportingMetricReader(
+            OTLPMetricExporter(endpoint=_ENDPOINT, insecure=True)
+        )
+        meter_provider = MeterProvider(resource=resource, metric_readers=[metric_reader])
+        metrics.set_meter_provider(meter_provider)
+        _meter = metrics.get_meter("qihu-aiflow")
+
+        logger.info(f"[otel] tracer+meter ready -> {_ENDPOINT}")
+    except Exception as e:  # pragma: no cover - 降级保护
+        logger.warning(f"[otel] init failed, degraded to no-op: {e}")
+        _tracer = None
+        _meter = None
+
+
+def get_tracer():
+    """返回 tracer；首次调用触发 init。未启用/失败返回 None。"""
+    if _tracer is None and _ENABLED:
+        init_otel()
+    return _tracer
+
+
+def get_meter():
+    """返回 meter；首次调用触发 init。未启用/失败返回 None。"""
+    if _meter is None and _ENABLED:
+        init_otel()
+    return _meter
+
+
+def current_span_cm(name: str, attributes: dict | None = None):
+    """返回一个 OTel span 的上下文管理器（同步/异步通用）。失败时返回 None。"""
+    tr = get_tracer()
+    if tr is None:
+        return None
+    try:
+        return tr.start_as_current_span(name, attributes=attributes or {})
+    except Exception as e:  # pragma: no cover
+        logger.warning(f"[otel] start_span failed: {e}")
+        return None
+
+
+def record_span_metrics(name: str, elapsed_ms: float, status: str) -> None:
+    """记录 span 指标：耗时直方图 + 调用计数（供 Grafana 出图）。失败安全。"""
+    m = get_meter()
+    if m is None:
+        return
+    global _duration_hist, _span_counter
+    try:
+        if _duration_hist is None:
+            _duration_hist = m.create_histogram(
+                "aiflow_span_duration_ms", "Span duration in milliseconds"
+            )
+            _span_counter = m.create_counter("aiflow_span_count", "Span invocation count")
+        attrs = {"span": name, "status": status}
+        _duration_hist.record(elapsed_ms, attrs)
+        _span_counter.add(1, attrs)
+    except Exception:  # pragma: no cover
+        pass
+

backend/python/app/core/rag_pipeline.py

@@ -0,0 +1,97 @@
+"""标准 RAG 管线 (Phase 2.C 标准化)
+====================================
+设计基准（标准对照表见 STANDARDS_AUDIT_2026-07-24.md §C）：
+- 对齐 LlamaIndex / LangChain 的管线形态：load -> chunk(overlap) -> embed -> store -> retrieve -> rerank。
+- 复用现有 pgvector 后端（document_embeddings 表 + ivfflat）与共享 embeddings 客户端
+  （app.core.llm_client.aembed）；嵌入维度(1024)、表结构、混合检索(RRF)全部沿用，不重复造轮子。
+- 不引入 LlamaIndex 全量重依赖：平台运行时为最小 fastapi/httpx 容器，引入 LlamaIndex 栈有体积/冲突风险；
+  故以「接口对齐标准」的方式实现标准管线（递归重叠分块 + 召回 + rerank 钩子）。后续若评估可接受，
+  可平滑替换为 llama_index.core 的 VectorStoreIndex + PGVectorStore（对外接口一致）。
+
+对外 API：
+    retrieve(query, kb_id, top_k=5, rerank=True) -> [dict]   # 标准检索（向量召回 + 可选 rerank）
+    index_document(text, doc_id, kb_id, ...) -> int          # 标准索引（递归重叠分块后逐块入库）
+"""
+import logging
+
+from app.pgvector_search import vector_search, index_document as _pg_index
+
+logger = logging.getLogger("aiflow.rag")
+
+# 标准递归分块分隔符（与 LlamaIndex SentenceSplitter / LangChain RecursiveCharacterTextSplitter 同序）
+_SEPARATORS = ["\n\n", "\n", "。", "！", "？", "；", ".", "!", "?", ";", " ", ""]
+
+
+def _recursive_split(text: str, chunk_size: int = 500, chunk_overlap: int = 80):
+    """递归字符分块（带重叠），对齐标准 Splitter 算法。
+
+    逐层用分隔符切分；某段仍超长时递归细切；最终兜底硬切（带重叠步长）。
+    """
+    text = text or ""
+    if len(text) <= chunk_size:
+        return [text] if text.strip() else []
+    for sep in _SEPARATORS:
+        if not sep:
+            # 兜底：硬切（带重叠步长）
+            step = max(1, chunk_size - chunk_overlap)
+            return [text[i : i + chunk_size] for i in range(0, len(text), step)]
+        parts = text.split(sep)
+        if len(parts) <= 1:
+            continue  # 该分隔符在文本中未出现，尝试更细的分隔符
+        chunks, cur = [], ""
+        for p in parts:
+            cand = (cur + sep + p) if cur else p
+            if len(cand) <= chunk_size:
+                cur = cand
+            else:
+                if cur:
+                    chunks.append(cur)
+                    cur = ""
+                if len(p) > chunk_size:
+                    chunks.extend(_recursive_split(p, chunk_size, chunk_overlap))
+                else:
+                    cur = p
+        if cur:
+            chunks.append(cur)
+        if chunks:
+            return [c for c in chunks if c.strip()]
+    return [text]
+
+
+async def index_document(
+    text: str,
+    doc_id: str,
+    kb_id: str,
+    chunk_size: int = 500,
+    chunk_overlap: int = 80,
+    metadata: dict | None = None,
+) -> int:
+    """标准索引：递归重叠分块后逐块存入 pgvector。返回成功分块数。"""
+    chunks = _recursive_split(text, chunk_size, chunk_overlap)
+    ok = 0
+    for i, ch in enumerate(chunks):
+        cid = f"{doc_id}_{i}"
+        if await _pg_index(doc_id, kb_id, ch, chunk_id=cid, metadata=metadata):
+            ok += 1
+    logger.info(f"[rag] indexed {doc_id}: {ok}/{len(chunks)} chunks")
+    return ok
+
+
+async def retrieve(
+    query: str,
+    kb_id: str | None = None,
+    top_k: int = 5,
+    rerank: bool = True,
+) -> list:
+    """标准检索：向量召回 + 可选 rerank。
+
+    返回 [{doc_id, chunk_id, content, score, metadata}, ...]。
+    rerank 钩子默认按向量余弦分排序；接入标准 cross-encoder
+    （sentence-transformers CrossEncoder）即替换此处，对外接口不变。
+    """
+    results = await vector_search(query, kb_id, top_k=top_k * 2 if rerank else top_k)
+    if not results:
+        return results
+    if rerank and len(results) > 1:
+        results = sorted(results, key=lambda r: r.get("score", 0), reverse=True)
+    return results[:top_k]

backend/python/app/mcp_client.py

@@ -1,122 +1,96 @@
 """
-MCP (Model Context Protocol) 客户端 —— 异步实现 streamable_http 传输。
+MCP (Model Context Protocol) 客户端 —— 基于官方 `mcp` Python SDK (Phase 1.E 标准化)
 
-支持：
+设计基准（标准对照表见 STANDARDS_AUDIT_2026-07-24.md §E）：
-- initialize / notifications/initialized / tools/list / tools/call 标准流程
+- 采用 Anthropic 官方 `mcp` SDK 处理 JSON-RPC 帧 + 协议版本协商，
-- streamable_http：POST JSON-RPC，响应可能是 SSE（event: message / data: {...}）或纯 JSON
+  不再手写解析、不再写死 MCP_PROTOCOL_VERSION 常量（旧实现写死 "2024-11-05"，
-- SSE 解析兼容
+  上游协议一升级即碎）。
-- 直连外部端点（trust_env=False，不绕容器代理）
+- 支持 streamable_http（默认）与 sse 两种传输，按 server['transport_type'] 选择。
-
+- 公共 API 保持向后兼容：list_mcp_tools(server, timeout) / call_mcp_tool(server, tool_name, arguments, timeout)
-供 chat.py 在 AI 对话中把 MCP 工具暴露为 function calling，并代理执行 tools/call。
+  供 chat.py / chat_service.py / chat_agents.py / chat_skill.py / chat_mcp.py /
+  chat_context.py / chat_knowledge.py / chat_media.py / chat_utils.py / core/aca.py
+  共 10+ 处调用，签名与返回结构（tools 数组 / 文本结果字符串）不变。
+- 工具列表缓存（按 url）与错误处理保持原行为，避免重复握手、保证降级安全。
 """
 
-import json
-import logging
 import asyncio
+import logging
 from typing import Optional
 
-import httpx
+from mcp import ClientSession
+from mcp.client.sse import sse_client
+from mcp.client.streamable_http import streamablehttp_client
 
 logger = logging.getLogger(__name__)
 
-MCP_PROTOCOL_VERSION = "2024-11-05"
-
 # 工具列表缓存（url -> (timestamp, tools)），避免同一请求内 / 短时间重复握手
 _TOOLS_CACHE: dict = {}
 _TOOLS_CACHE_TTL = 120  # 秒
 
 
-def _parse_sse(text: str):
+def _transport_cm(server: dict, timeout: float):
-    """从响应文本解析 JSON-RPC 结果。兼容 SSE（data: 行）与纯 JSON。"""
+    """按 server['transport_type'] 选择官方 SDK 传输层。
-    if not text:
+
-        return None
+    返回异步上下文管理器，进入后产出 (read_stream, write_stream, ...)。
-    text = text.strip()
+    """
-    # SSE 格式：多行 "event: message" / "data: {...}"
+    url = (server.get("url") or "").strip()
-    data_lines = []
+    ttype = (server.get("transport_type") or "streamable_http").lower()
-    for line in text.splitlines():
+    headers = server.get("headers") or {}
-        ls = line.strip()
+    if ttype == "sse":
-        if ls.startswith("data:"):
+        return sse_client(url, headers=headers, timeout=timeout)
-            data_lines.append(ls[5:].strip())
+    # 默认 streamable_http（官方 SDK 标准传输）
-    if data_lines:
+    return streamablehttp_client(url, headers=headers, timeout=timeout)
-        last = data_lines[-1]
-        try:
-            return json.loads(last)
-        except Exception:
-            pass
-    # 纯 JSON
-    try:
-        return json.loads(text)
-    except Exception:
-        return None
 
 
-async def _handshake_and_request(
+async def _session_request(
-    url: str,
+    server: dict, method: str, params: dict, timeout: float = 30.0
-    headers: dict,
-    method: str,
-    params: dict,
-    timeout: float = 30.0,
 ):
+    """用官方 ClientSession 完成一次标准 MCP 调用（initialize -> 目标请求）。
+
+    返回解析后的 dict：{"result": {...}} 或 None（失败）。
+    协议版本由 SDK 自动协商，不再硬编码。
     """
-    完成一次完整 MCP 会话（initialize -> initialized -> 目标请求）。
+    url = (server.get("url") or "").strip()
-    返回解析后的 JSON-RPC 响应 dict，或 None。
+    if not url:
-    """
+        return None
-    base_headers = {
+    try:
-        "Content-Type": "application/json",
+        async with _transport_cm(server, timeout) as streams:
-        "Accept": "application/json, text/event-stream",
+            read, write, *_ = streams
-    }
+            async with ClientSession(read, write) as session:
-    base_headers.update(headers or {})
+                # 标准握手：initialize 会发送 initialize 请求并自动补 notifications/initialized
+                await session.initialize()
+                # 防御性补发 initialized 通知（部分服务端要求显式接收）
+                try:
+                    if hasattr(session, "send_notification"):
+                        await session.send_notification("notifications/initialized", {})
+                except Exception:
+                    pass
 
-    async with httpx.AsyncClient(timeout=timeout, trust_env=False) as client:
+                if method == "tools/list":
-        # 1) initialize
+                    result = await session.list_tools()
-        r = await client.post(
+                    tools = [t.model_dump() for t in (result.tools or [])]
-            url,
+                    return {"result": {"tools": tools}}
-            headers=base_headers,
+                elif method == "tools/call":
-            json={
+                    res = await session.call_tool(
-                "jsonrpc": "2.0",
+                        params.get("name"), params.get("arguments") or {}
-                "id": 1,
+                    )
-                "method": "initialize",
+                    content = []
-                "params": {
+                    for blk in (res.content or []):
-                    "protocolVersion": MCP_PROTOCOL_VERSION,
+                        btype = getattr(blk, "type", "text")
-                    "capabilities": {},
+                        if btype == "text":
-                    "clientInfo": {"name": "aiflow", "version": "1.0"},
+                            content.append({"type": "text", "text": getattr(blk, "text", "")})
-                },
+                        else:
-            },
+                            content.append({"type": btype, "text": str(blk)})
-        )
+                    return {
-        if r.status_code >= 400:
+                        "result": {
-            logger.warning(f"[MCP] initialize 失败 {url} -> HTTP {r.status_code}")
+                            "content": content,
-            return None
+                            "isError": bool(getattr(res, "isError", False)),
-        sid = r.headers.get("mcp-session-id") or r.headers.get("Mcp-Session-Id")
+                        }
-        req_headers = dict(base_headers)
+                    }
-        if sid:
+    except Exception as e:
-            req_headers["Mcp-Session-Id"] = sid
+        logger.warning(f"[MCP] {method} 异常 {url}: {e}")
-
+        return None
-        # 2) initialized 通知（不需要响应）
+    return None
-        try:
-            await client.post(
-                url,
-                headers=req_headers,
-                json={"jsonrpc": "2.0", "method": "notifications/initialized"},
-            )
-        except Exception:
-            pass
-
-        # 3) 目标请求
-        rid = 2 if method != "tools/call" else 3
-        r2 = await client.post(
-            url,
-            headers=req_headers,
-            json={
-                "jsonrpc": "2.0",
-                "id": rid,
-                "method": method,
-                "params": params,
-            },
-        )
-        if r2.status_code >= 400:
-            logger.warning(f"[MCP] {method} 失败 {url} -> HTTP {r2.status_code}")
-            return None
-        return _parse_sse(r2.text)
 
 
 async def list_mcp_tools(server: dict, timeout: float = 30.0) -> list:
@@ -134,9 +108,7 @@ async def list_mcp_tools(server: dict, timeout: float = 30.0) -> list:
     if cached and (now - cached[0]) < _TOOLS_CACHE_TTL:
         return cached[1]
     try:
-        data = await _handshake_and_request(
+        data = await _session_request(server, "tools/list", {}, timeout)
-            url, server.get("headers") or {}, "tools/list", {}, timeout
-        )
         tools = []
         if data and "result" in data:
             tools = data["result"].get("tools", []) or []
@@ -158,9 +130,8 @@ async def call_mcp_tool(
         return f"[MCP 工具 {tool_name} 执行失败：服务端地址为空]"
     logger.info(f"[MCP] 执行工具调用 tool={tool_name} server={server.get('name')} url={url}")
     try:
-        data = await _handshake_and_request(
+        data = await _session_request(
-            url,
+            server,
-            server.get("headers") or {},
             "tools/call",
             {"name": tool_name, "arguments": arguments or {}},
             timeout,
@@ -169,7 +140,7 @@ async def call_mcp_tool(
             return f"[MCP 工具 {tool_name} 调用失败：无响应]"
         if "error" in data:
             err = data["error"]
-            return f"[MCP 工具 {tool_name} 返回错误] {json.dumps(err, ensure_ascii=False)}"
+            return f"[MCP 工具 {tool_name} 返回错误] {__import__('json').dumps(err, ensure_ascii=False)}"
         result = data.get("result", {})
         content = result.get("content", []) or []
         parts = []
@@ -177,7 +148,7 @@ async def call_mcp_tool(
             if isinstance(item, dict) and item.get("type") == "text":
                 parts.append(item.get("text", ""))
             else:
-                parts.append(json.dumps(item, ensure_ascii=False))
+                parts.append(__import__("json").dumps(item, ensure_ascii=False))
         text = "\n".join(parts).strip()
         if result.get("isError"):
             return f"[MCP 工具 {tool_name} 执行报错]\n{text}"

backend/python/app/pgvector_search.py

@@ -135,27 +135,16 @@ async def get_embedding(text: str) -> Optional[List[float]]:
     if cached:
         return cached
     try:
-        import httpx
+        # 收敛到共享标准模型层（app.core.llm_client.aembed），与聊天共用代理/超时/failover 语义
-        async with httpx.AsyncClient(timeout=30, trust_env=False) as client:
+        from app.core.llm_client import aembed
-            resp = await client.post(
+        embedding = await aembed(
-                f"{EMBEDDING_API_URL}/v1/embeddings",
+            EMBEDDING_API_URL, EMBEDDING_API_KEY, text[:8000], EMBEDDING_MODEL, timeout=30
-                headers={
+        )
-                    "Authorization": f"Bearer {EMBEDDING_API_KEY}",
+        if embedding:
-                    "Content-Type": "application/json",
+            _embed_cache_put(text, EMBEDDING_MODEL, embedding)
-                },
+            return embedding
-                json={
+        logger.error("Embedding API returned empty")
-                    "model": EMBEDDING_MODEL,
+        return None
-                    "input": text[:8000],  # 截断防止超长
-                },
-            )
-            if resp.status_code == 200:
-                data = resp.json()
-                embedding = data["data"][0]["embedding"]
-                _embed_cache_put(text, EMBEDDING_MODEL, embedding)
-                return embedding
-            else:
-                logger.error(f"Embedding API error: {resp.status_code} {resp.text[:200]}")
-                return None
     except Exception as e:
         logger.error(f"Embedding generation failed: {e}")
         return None