kb-memory 2.1.0__py3-none-any.whl

kb/i18n.py

@@ -0,0 +1,257 @@
+"""双语消息（i18n）与 MCP 接入规约。
+
+- `KB_LANG`：服务端错误/校验消息语言（zh/en/auto，默认 auto）
+- `KB_MEMORY_LANG`：记忆书写语言（auto/zh/en/...，默认 auto = 操作系统默认语言）
+- 自定义记忆规则：`~/.kb/rules.md` + `<data_dir>/rules.md`，截断后注入 MCP instructions
+
+English: Bilingual messages plus the MCP instructions contract.
+- KB_LANG: language of server error/validation messages (zh/en/auto).
+- KB_MEMORY_LANG: language used when writing memories (auto = OS default language).
+- Custom memory rules: ~/.kb/rules.md plus <data_dir>/rules.md, truncated and injected
+  into the MCP instructions.
+"""
+import locale
+from pathlib import Path
+
+from kb.config import get_settings
+
+
+def detect_lang() -> str:
+    """检测系统语言：中文系统→zh，其他→en；KB_LANG=zh/en 时直接采用。
+    English: Detect system language: Chinese systems→zh, otherwise→en; KB_LANG=zh/en wins."""
+    try:
+        cfg_lang = get_settings().lang
+        if cfg_lang in ("zh", "en"):
+            return cfg_lang
+    except Exception:
+        pass
+    # auto：检测系统 locale
+    try:
+        code, _ = locale.getdefaultlocale()
+        if code and code.lower().startswith("zh"):
+            return "zh"
+    except Exception:
+        pass
+    return "en"
+
+
+# 常见语言代码 → 语言名（供 MCP instructions 明确要求 agent 使用的书写语言）
+_LANG_NAMES: dict[str, str] = {
+    "zh": "Chinese (简体中文)",
+    "en": "English",
+    "ja": "Japanese (日本語)",
+    "ko": "Korean (한국어)",
+    "de": "German (Deutsch)",
+    "fr": "French (Français)",
+    "es": "Spanish (Español)",
+    "pt": "Portuguese (Português)",
+    "it": "Italian (Italiano)",
+    "ru": "Russian (Русский)",
+    "ar": "Arabic (العربية)",
+    "hi": "Hindi (हिन्दी)",
+    "nl": "Dutch (Nederlands)",
+    "pl": "Polish (Polski)",
+    "tr": "Turkish (Türkçe)",
+}
+
+
+def system_language_code() -> str:
+    """操作系统默认语言代码（如 zh-CN / fr-FR）；检测失败回退 en。
+    English: OS default language code (e.g. zh-CN / fr-FR); falls back to en."""
+    code = ""
+    try:
+        code = locale.getlocale()[0] or ""
+    except Exception:
+        pass
+    if not code:
+        try:
+            code, _ = locale.getdefaultlocale()
+        except Exception:
+            pass
+    return (code or "en").replace("_", "-")
+
+
+def memory_lang() -> str:
+    """记忆书写语言名：KB_MEMORY_LANG 显式指定优先，auto 按操作系统语言。
+    English: Display name of the memory-writing language: KB_MEMORY_LANG wins;
+    auto follows the OS language."""
+    try:
+        cfg = (get_settings().memory_lang or "auto").strip().lower()
+    except Exception:
+        cfg = "auto"
+    code = system_language_code() if cfg == "auto" else cfg
+    base = code.replace("_", "-").split("-")[0].lower()
+    return _LANG_NAMES.get(base, code or "English")
+
+
+# 消息表：key → {zh, en}
+_MESSAGES: dict[str, dict[str, str]] = {
+    # 校验类（service.validate_* 供 MCP/REST 共用）
+    "agent_id_required": {
+        "zh": "agent_id 必填且必须是有意义的任务名（如 TASK-0076 / worker-1），不能用 default/unknown 等占位",
+        "en": "agent_id is required and must be a meaningful task name (e.g. TASK-0076 / worker-1); placeholders like default/unknown are rejected",
+    },
+    "agent_id_format": {
+        "zh": "agent_id 格式非法：仅允许字母/数字/中文/下划线/连字符，1~64 字符（当前：{v!r}）",
+        "en": "invalid agent_id: only letters/digits/CJK/underscore/hyphen allowed, 1~64 chars (got {v!r})",
+    },
+    "client_format": {
+        "zh": "client 格式非法：仅允许字母/数字/中文/下划线/连字符/空格/点，1~64 字符（当前：{v!r}；不传则自动识别）",
+        "en": "invalid client: only letters/digits/CJK/underscore/hyphen/space/dot allowed, 1~64 chars (got {v!r}; omit for auto-detect)",
+    },
+    "project_format": {
+        "zh": "project 格式非法：仅允许字母/数字/中文/下划线/连字符，1~64 字符且不能是系统保留名（当前：{v!r}）",
+        "en": "invalid project: only letters/digits/CJK/underscore/hyphen allowed, 1~64 chars, reserved OS names rejected (got {v!r})",
+    },
+    # 业务错误（MCP 工具返回的错误消息）
+    "content_blank": {
+        "zh": "content 不能为空或纯空白",
+        "en": "content must not be empty or blank",
+    },
+    "top_k_min": {
+        "zh": "top_k 必须 >= 1",
+        "en": "top_k must be >= 1",
+    },
+    "record_none": {
+        "zh": "记录不存在或无权访问",
+        "en": "record not found or forbidden",
+    },
+    "record_forbidden": {
+        "zh": "无权访问该记忆（非当前客户端/项目归属）",
+        "en": "memory not accessible (not owned by this client/project)",
+    },
+    "llm_disabled": {
+        "zh": "未检测到可用的 LLM：请在 .env 配置 KB_LLM_MODE=local（Ollama）或 KB_LLM_API_KEY 启用云端（任意 OpenAI 兼容服务商）",
+        "en": "no LLM available: configure KB_LLM_MODE=local (Ollama) or KB_LLM_API_KEY in .env for a cloud provider (any OpenAI-compatible endpoint)",
+    },
+    "unsupported_format": {
+        "zh": "不支持的文件格式",
+        "en": "unsupported file format",
+    },
+    "web_fetch_failed": {
+        "zh": "网页抓取/正文提取失败",
+        "en": "webpage fetch/body extraction failed",
+    },
+    "file_not_found": {
+        "zh": "文件不存在",
+        "en": "file not found",
+    },
+    "bad_request": {
+        "zh": "请求参数不合法",
+        "en": "invalid request parameters",
+    },
+}
+
+
+def t(key: str, **fmt) -> str:
+    """按当前语言返回 key 的消息；未知 key 回退英文（或 key 本身）。
+    English: Return the message for key in the current language; unknown keys fall back to English."""
+    msg = _MESSAGES.get(key, {})
+    text = msg.get(detect_lang()) or msg.get("en") or key
+    try:
+        return text.format(**fmt)
+    except Exception:
+        return text
+
+
+def custom_rules() -> str:
+    """读取用户自定义记忆规则：全局 ~/.kb/rules.md 在前，本安装 rules.md 在后，
+    拼接后按 KB_RULES_MAX_CHARS 截断（默认 4000）。
+    English: Load user-defined memory rules: the global ~/.kb/rules.md first, then
+    this installation's rules.md, joined and truncated to KB_RULES_MAX_CHARS (4000)."""
+    try:
+        settings = get_settings()
+    except Exception:
+        return ""
+    paths = [Path.home() / ".kb" / "rules.md", settings.rules_file]
+    parts: list[str] = []
+    for path in paths:
+        try:
+            if path.is_file():
+                text = path.read_text(encoding="utf-8").strip()
+                if text:
+                    parts.append(text)
+        except OSError:
+            continue
+    limit = max(0, int(settings.rules_max_chars or 0))
+    return "\n\n".join(parts)[:limit]
+
+
+# ---- MCP server instructions（v2.1 接入规约，2026-10-20）----
+# 跨客户端全局提示词载体：任何客户端挂载 MCP 后自动注入 AI 上下文；
+# 语言按 KB_MEMORY_LANG/系统语言确定，并注入用户自定义记忆规则。
+# 核心：不要求先做健康探测、反馈极简、project 隔离项目记忆、全局记忆共享。
+_MCP_INSTRUCTIONS: dict[str, str] = {
+    "zh": """你是连接到 kb（本地 Agent 记忆与知识服务）的助手。kb 是本机常驻服务，你现在就能直接调用它的 MCP 工具写入/检索记忆与知识，默认情况下服务在正常运行，无需也不要求事前探测（health check）——直接调用工具即可，一切正常时请继续工作。
+
+【身份与项目】
+- client 由系统自动识别，你不需要自报身份，也不要展示。
+- project 用于区分不同项目的记忆：当用户明确在某个项目上下文中工作（提到项目名、仓库名或项目目录）时，将该项目的稳定短名传给 project 参数；同一项目始终用同一个名字。
+- 项目记忆只在该 project 下可见；不传 project 写入的是全局记忆（所有项目可见），适合用户偏好、通用事实与跨项目约定。不确定项目名时不要猜测：写全局或先问用户。
+- 检索时传 project 会同时覆盖该项目与全局记忆；不传只看全局。
+
+【记忆语言】
+- 写入记忆一律使用 {memory_lang}；专有名词、代码、命令、路径保持原文，不要翻译。
+
+【何时写入记忆（write_memory，内容精炼 1~3 句）】
+1. 用户偏好：主题、工具链、代码风格、命名习惯、沟通方式。
+2. 项目决策：已拍板的选型/架构取舍/约定，写清背景与结论。
+3. 事实与约定：关键路径、命令、依赖、环境细节、版本约束等可复用事实。
+4. 敏感约束：用户明示的不可做红线、安全/隐私要求。
+5. 任务进度：复杂任务的关键进展与下一步，便于跨会话接力。
+不写：纯寒暄、临时计算、可由代码/文档直接查到的实现细节。
+- 写前先查重：先 search_memory，已有同类则 update_memory 覆盖，不新增重复。
+- 敏感信息不入库：密钥、凭据、身份证号等严禁写入。
+
+【何时检索（search_memory）】
+- 任务开始、回答涉及历史决策/用户偏好、跨会话接力时，先主动检索召回，query 用自然语言描述语义。
+
+【对用户反馈（重要，极简）】
+- 写入/更新成功：只轻提一句，如"已记住你的偏好"；失败才说明原因（如"没记：与已有记忆重复/内容敏感/格式不支持"）。
+- 不要展示：健康检查过程、工具名、记录 ID、JSON、检索命中详情。
+- 若 MCP 工具调用报连接失败（服务确实不可达），简提"kb 服务未启动，需先运行 python -m kb serve"，不要臆造结果。""",
+    "en": """You are connected to kb, a local Agent memory & knowledge service. kb is a resident local service whose MCP tools you can call right now to write/retrieve memories and knowledge. It is normally running; no health check or pre-probing is required — just call the tools directly and keep working when things are normal.
+
+[Identity & projects]
+- The client is auto-detected; never self-report or display it.
+- project separates memories between projects: when the user is clearly working in a project context (project name, repository name, or project directory), pass that project's stable short name as project; always use the same name for the same project.
+- Project memories are visible only under that project. Without project, writes go to global memory (visible to every project) — suitable for user preferences, general facts, and cross-project conventions. Never guess a project name: write globally or ask the user.
+- Searching with project covers that project plus global memory; without it, only global memory.
+
+[Memory language]
+- Always write memories in {memory_lang}; keep proper nouns, code, commands, and paths unchanged — do not translate them.
+
+[When to write memory (write_memory, 1-3 concise sentences)]
+1. User preferences: themes, toolchain, code style, naming habits, communication style.
+2. Project decisions: settled tech choices, architecture trade-offs, conventions — with context and conclusion.
+3. Facts & conventions: key paths, commands, dependencies, environment details, version constraints.
+4. Sensitive constraints: explicit hard rules ("do not"), security/privacy requirements.
+5. Task progress: key progress of complex tasks and next steps, for cross-session handoff.
+Do NOT write: chit-chat, transient computation, implementation details directly findable in code/docs.
+- Dedupe before writing: search_memory first; if similar content exists, update_memory to overwrite instead of adding duplicates.
+- Never store sensitive data: keys, credentials, ID numbers are forbidden.
+
+[When to search (search_memory)]
+- Proactively recall at task start, when an answer involves past decisions/preferences, or on cross-session handoff; ask in natural language describing the semantics.
+
+[Feedback to user (important — keep it minimal)]
+- On successful write/update: mention it briefly, e.g. "Noted your preference."
+- On failure, state the reason (e.g. "Not saved: duplicate of an existing memory / sensitive content / unsupported format").
+- Do NOT show: health-check process, tool names, record IDs, JSON, retrieval hit details.
+- Only if an MCP tool call fails with a connection error (service truly unreachable), briefly say "kb service is not running; start it with python -m kb serve". Never fabricate results.""",
+}
+
+
+def mcp_instructions() -> str:
+    """按当前系统语言返回 MCP instructions，并注入记忆语言与用户自定义规则。
+    English: Return the MCP instructions for the current system language, with the
+    memory language and user-defined rules injected."""
+    lang = detect_lang()
+    text = (_MCP_INSTRUCTIONS.get(lang) or _MCP_INSTRUCTIONS["en"]).format(
+        memory_lang=memory_lang())
+    rules = custom_rules()
+    if not rules:
+        return text
+    if lang == "zh":
+        return text + "\n\n【用户自定义记忆规则（优先遵守）】\n" + rules
+    return text + "\n\n[User-defined memory rules (take precedence)]\n" + rules

kb/ingest.py

@@ -0,0 +1,122 @@
+"""文档/网页摄取：解析为纯文本 + 递归切分（设计文档第 9 节）。
+
+解析分派：.pdf→pypdf；.docx→python-docx；.md/.txt→直读；
+Office 等已知格式（.xlsx/.pptx/...）→ markitdown 兜底；
+白名单之外的扩展名一律抛 UnsupportedFormatError（API 层转 400）。
+
+网页摄取：httpx 拉取（超时 15s，UA 伪装常规浏览器）→ trafilatura
+提取正文；抓取/提取失败抛 WebFetchError（API 层转 400 + 原因）。
+
+重依赖（pypdf / python-docx / markitdown / langchain-text-splitters /
+httpx / trafilatura）均在函数内延迟导入，服务启动不加载；其中
+pypdf/python-docx/markitdown/trafilatura 属于可选 extra `[ingest]`，
+缺失时返回带安装指引的可读错误。
+"""
+from pathlib import Path
+
+_INGEST_HINT = "请运行 pip install \"kb-memory[ingest]\" 后重试"
+
+
+def _ingest_import(module: str, what: str):
+    """导入摄取可选依赖；缺失时抛带 extra 安装指引的 UnsupportedFormatError。"""
+    import importlib
+    try:
+        return importlib.import_module(module)
+    except ImportError as exc:
+        raise UnsupportedFormatError(
+            f"{what}需要可选依赖 {module}：{_INGEST_HINT}") from exc
+
+# 直接解析的扩展名（.md / .txt 直读原文，不做任何清洗）
+_DIRECT_EXTS = {".md", ".txt"}
+# markitdown 兜底的已知格式（Office 全格式等；markitdown 对未知扩展名
+# 会当纯文本静默返回，故必须白名单控制，白名单外直接拒绝）
+_MARKITDOWN_EXTS = {".xlsx", ".xls", ".pptx", ".ppt", ".csv", ".json",
+                    ".xml", ".html", ".htm", ".rst"}
+
+
+class UnsupportedFormatError(Exception):
+    """不支持的文档格式（API 层转 400）。"""
+
+
+class WebFetchError(Exception):
+    """网页抓取或正文提取失败（API 层转 400 + 原因）。"""
+
+
+# 网页抓取 UA：伪装常规浏览器（设计文档第 9 节），避免站点拒绝默认 UA
+_WEB_USER_AGENT = ("Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+                   "AppleWebKit/537.36 (KHTML, like Gecko) "
+                   "Chrome/126.0.0.0 Safari/537.36")
+
+
+def parse_file(path: Path | str) -> str:
+    """解析文档为纯文本；不支持的扩展名抛 UnsupportedFormatError。"""
+    path = Path(path)
+    ext = path.suffix.lower()
+    if ext in _DIRECT_EXTS:
+        return path.read_text(encoding="utf-8")
+    if ext == ".pdf":
+        return _parse_pdf(path)
+    if ext == ".docx":
+        return _parse_docx(path)
+    if ext in _MARKITDOWN_EXTS:
+        return _parse_markitdown(path)
+    raise UnsupportedFormatError(f"不支持的文档格式：{ext or '<无扩展名>'}（{path.name}）")
+
+
+def _parse_pdf(path: Path) -> str:
+    """pypdf 逐页提取文本，空页跳过。"""
+    PdfReader = _ingest_import("pypdf", "解析 PDF ").PdfReader
+    reader = PdfReader(str(path))
+    return "\n".join((page.extract_text() or "") for page in reader.pages)
+
+
+def _parse_docx(path: Path) -> str:
+    """python-docx 提取全部段落文本。"""
+    Document = _ingest_import("docx", "解析 DOCX ").Document
+    doc = Document(str(path))
+    return "\n".join(p.text for p in doc.paragraphs)
+
+
+def _parse_markitdown(path: Path) -> str:
+    """markitdown 兜底解析（Office 全格式）；解析失败抛 UnsupportedFormatError。"""
+    MarkItDown = _ingest_import("markitdown", "解析 Office 文档 ").MarkItDown
+    try:
+        return MarkItDown().convert(str(path)).text_content
+    except Exception as exc:
+        raise UnsupportedFormatError(f"文档解析失败（{path.name}）：{exc}") from exc
+
+
+def chunk_text(text: str, size: int, overlap: int) -> list[str]:
+    """langchain RecursiveCharacterTextSplitter 递归切分（按分隔符层级回退）。"""
+    from langchain_text_splitters import RecursiveCharacterTextSplitter
+    splitter = RecursiveCharacterTextSplitter(chunk_size=size,
+                                              chunk_overlap=overlap)
+    return splitter.split_text(text)
+
+
+def _fetch_html(url: str) -> str:
+    """httpx 抓取页面 HTML：超时 15s、UA 伪装常规浏览器、跟随重定向；
+    4xx/5xx 与网络错误抛原始异常（由 fetch_webpage 统一包装）。"""
+    import httpx
+    with httpx.Client(timeout=15, headers={"User-Agent": _WEB_USER_AGENT},
+                      follow_redirects=True) as client:
+        resp = client.get(url)
+        resp.raise_for_status()
+        return resp.text
+
+
+def fetch_webpage(url: str) -> str:
+    """抓取网页并提取正文：_fetch_html 拉取 → trafilatura.extract 提取；
+    抓取异常或正文提取结果为空时抛 WebFetchError。"""
+    try:
+        html = _fetch_html(url)
+    except Exception as exc:
+        raise WebFetchError(f"网页抓取失败（{url}）：{exc}") from exc
+    try:
+        trafilatura = _ingest_import("trafilatura", "提取网页正文 ")
+    except UnsupportedFormatError as exc:
+        raise WebFetchError(str(exc)) from exc
+    text = trafilatura.extract(html)
+    if not text:
+        raise WebFetchError(f"网页正文提取失败（{url}）：未识别到正文内容")
+    return text

kb/llm.py

@@ -0,0 +1,155 @@
+"""LLM 接入层：Ollama 探测、模式解析（local/auto/cloud）、护栏参数、本地/云端双客户端统一接口。"""
+from enum import Enum
+
+import httpx
+
+from kb.config import Settings
+
+
+class LLMError(Exception):
+    """LLM 调用异常（service 层据此转 503 或降级）。"""
+
+
+class LLMStatus(str, Enum):
+    """LLM 可用状态。"""
+
+    LOCAL = "local"
+    CLOUD = "cloud"
+    DISABLED = "disabled"
+
+
+class LLMClient:
+    """本地（Ollama 原生 /api/chat）与云端（OpenAI 兼容接口）统一生成接口。
+
+    模式（KB_LLM_MODE）：off（默认，不加载/不调用任何 LLM）| local | auto | cloud。
+    云端端点通用化：任意 OpenAI 兼容服务（OpenAI/DeepSeek/通义/硅基流动等），
+    配置键 KB_LLM_API_KEY / KB_LLM_BASE_URL / KB_LLM_CLOUD_MODEL；旧 KB_DEEPSEEK_* 兼容。
+
+    护栏参数硬编码默认值：think=False、temperature 0.2、num_ctx 4096、
+    max_tokens 800（可被 chat 入参覆盖），不新增配置项。
+    """
+
+    def __init__(self, settings: Settings, http_client: httpx.Client | None = None):
+        """http_client 注入用于测试；默认自建（base_url=settings.ollama_base_url）。
+        构造时立即探测（每次构造重新探测，不使用模块级缓存）。"""
+        self._settings = settings
+        # 生成可能较慢（含模型冷加载），默认客户端给足超时；probe 另有 2s 限时
+        self._http = http_client or httpx.Client(
+            base_url=settings.ollama_base_url, timeout=120.0)
+        self._local_ok = False
+        self._cloud_ok = False
+        self.probe()
+
+    def probe(self) -> dict:
+        """GET {ollama_base_url}/v1/models（2s 超时）→ 本地可用性；
+        云端 API Key 非空 → 云端可用性。off 模式不探测（恒 DISABLED）。
+        Returns {"local": bool, "cloud": bool}."""
+        if self._settings.llm_mode == "off":
+            self._local_ok = False
+            self._cloud_ok = False
+            return {"local": False, "cloud": False}
+        local_ok = False
+        try:
+            resp = self._http.get("/v1/models", timeout=2.0)
+            local_ok = resp.is_success
+        except httpx.HTTPError:
+            local_ok = False
+        self._local_ok = local_ok
+        self._cloud_ok = bool(self._settings.cloud_api_key)
+        return {"local": self._local_ok, "cloud": self._cloud_ok}
+
+    @property
+    def status(self) -> LLMStatus:
+        """off：恒 DISABLED；
+        local 模式：本地可用→LOCAL 否则 DISABLED；
+        cloud 模式：有 Key→CLOUD 否则 DISABLED；
+        auto 模式：本地可用→LOCAL；无本地有云→CLOUD；都无→DISABLED。"""
+        mode = self._settings.llm_mode
+        if mode == "off":
+            return LLMStatus.DISABLED
+        if mode == "local":
+            return LLMStatus.LOCAL if self._local_ok else LLMStatus.DISABLED
+        if mode == "cloud":
+            return LLMStatus.CLOUD if self._cloud_ok else LLMStatus.DISABLED
+        # auto（默认）：本地优先，云端兜底
+        if self._local_ok:
+            return LLMStatus.LOCAL
+        if self._cloud_ok:
+            return LLMStatus.CLOUD
+        return LLMStatus.DISABLED
+
+    def chat(self, messages: list[dict], max_tokens: int | None = None,
+             prefer: str = "auto") -> str:
+        """统一生成接口。prefer: local/cloud/auto（路由用）。
+
+        - DISABLED 状态直接抛 LLMError；
+        - 显式 prefer 指定的后端不可用时抛 LLMError（不跨端回退，
+          避免 local 模式或敏感场景下悄悄走云）；
+        - auto：本地优先，云端兜底，都无抛 LLMError。
+        """
+        if self.status is LLMStatus.DISABLED:
+            raise LLMError("LLM 不可用：KB_LLM_MODE=off 或本地 Ollama 未响应且云端未配置 API Key")
+        mode = self._settings.llm_mode
+        # 模式约束后端范围：local 模式禁云端，cloud 模式禁本地
+        local_usable = self._local_ok and mode != "cloud"
+        cloud_usable = self._cloud_ok and mode != "local"
+        if prefer == "local":
+            if not local_usable:
+                raise LLMError("本地 LLM 不可用（Ollama 未响应或 cloud 模式禁用本地）")
+            return self._chat_local(messages, max_tokens)
+        if prefer == "cloud":
+            if not cloud_usable:
+                raise LLMError("云端 LLM 不可用（未配置 API Key 或 local 模式禁用云端）")
+            return self._chat_cloud(messages, max_tokens)
+        # prefer == "auto"：本地优先，云端兜底
+        if local_usable:
+            return self._chat_local(messages, max_tokens)
+        return self._chat_cloud(messages, max_tokens)
+
+    def _chat_local(self, messages: list[dict], max_tokens: int | None) -> str:
+        """本地 Ollama 原生 /api/chat（openai SDK 不透传 think 参数，故直用 httpx）。"""
+        if not self._settings.llm_model:
+            raise LLMError(
+                "未配置本地模型：请在 .env 设置 KB_LLM_MODEL=<ollama list 中的模型名>")
+        body = {
+            "model": self._settings.llm_model,
+            "messages": messages,
+            "think": False,
+            "stream": False,
+            "options": {
+                "temperature": 0.2,
+                "num_ctx": 4096,
+                "max_tokens": max_tokens or 800,
+            },
+        }
+        try:
+            resp = self._http.post("/api/chat", json=body)
+            resp.raise_for_status()
+            data = resp.json()
+        except httpx.HTTPError as exc:
+            raise LLMError(f"本地 LLM 调用失败: {exc}") from exc
+        return data.get("message", {}).get("content") or ""
+
+    def _chat_cloud(self, messages: list[dict], max_tokens: int | None) -> str:
+        """云端 OpenAI 兼容接口（openai SDK；延迟导入，off/local 模式无需安装 SDK）。
+
+        端点由 KB_LLM_BASE_URL / KB_LLM_API_KEY / KB_LLM_CLOUD_MODEL 配置（兼容旧 KB_DEEPSEEK_*）。
+        """
+        try:
+            from openai import OpenAI, OpenAIError
+        except ImportError as exc:
+            raise LLMError(
+                "未安装 openai SDK，无法调用云端 LLM："
+                "请运行 pip install \"kb-memory[llm]\"") from exc
+        client = OpenAI(api_key=self._settings.cloud_api_key,
+                        base_url=self._settings.cloud_base_url)
+        try:
+            resp = client.chat.completions.create(
+                model=self._settings.cloud_model,
+                messages=messages,
+                temperature=0.2,
+                max_tokens=max_tokens or 800,
+            )
+        except OpenAIError as exc:
+            raise LLMError(f"云端 LLM 调用失败: {exc}") from exc
+        return resp.choices[0].message.content or ""

kb/logging_setup.py

@@ -0,0 +1,75 @@
+"""日志体系装配（N17）：setup_logging 一次调用配置 kb.* 日志树。
+
+设计依据（历史日志设计，已本地归档）第 6 节：
+- 控制台 handler：精简格式（asctime 只保留时分秒，省略日期部分）；
+- RotatingFileHandler：完整格式（含模块名），按 KB_LOG_MAX_BYTES 轮转，
+  保留 KB_LOG_BACKUP_COUNT 个备份；
+- 格式统一 ``%(asctime)s | %(levelname)s | %(name)s | %(message)s``。
+
+说明：handler 挂在 "kb" 命名日志树根上（kb.serve / kb.api / kb.watcher
+等子 logger 自动继承级别与 handler），不碰进程根 logger——避免第三方库
+（urllib3 / watchdog 等）日志混入 kb.log。可重复调用（create_app 每次
+装配都会走到）：先关闭并摘除旧 handler 再挂新的，规避 Windows 文件
+句柄占用导致轮转失败。
+"""
+import logging
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+# 统一格式（设计第 6 节）：时间 | 级别 | 模块 | 消息
+_FORMAT = "%(asctime)s | %(levelname)s | %(name)s | %(message)s"
+# 控制台版 datefmt：只保留时分秒（省略日期部分保持简洁）
+_CONSOLE_DATEFMT = "%H:%M:%S"
+
+# KB_LOG_LEVEL 合法级别表；非法值回退 INFO（容错不阻断启动）
+_LEVELS = {"DEBUG": logging.DEBUG, "INFO": logging.INFO,
+           "WARNING": logging.WARNING, "ERROR": logging.ERROR,
+           "CRITICAL": logging.CRITICAL}
+
+
+class _NoRequestFilter(logging.Filter):
+    """控制台降噪过滤器：拦截 event=request.* 的访问日志。
+
+    文件 handler 不挂此过滤器（全量审计保留）；仅控制台静默，
+    避免高频轮询（每 10 秒 3 个请求）刷屏。匹配 N17 中间件的
+    消息格式 "request.start method=..." / "request.end method=..."。
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        return not str(record.getMessage()).startswith("request.")
+
+
+def setup_logging(settings=None) -> logging.Logger:
+    """装配 kb 日志树：控制台 + 轮转文件双 handler，返回 "kb" logger。
+
+    settings 缺省时读全局配置单例（get_settings）。日志目录不存在时
+    自动创建；级别名大小写不敏感，非法值回退 INFO。
+    """
+    if settings is None:
+        from kb.config import get_settings
+        settings = get_settings()
+
+    level = _LEVELS.get(str(settings.log_level).upper(), logging.INFO)
+    log_dir = Path(settings.log_dir)
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    root = logging.getLogger("kb")
+    root.setLevel(level)
+    # 关闭并摘除旧 handler（测试/重复装配场景），防 Windows 句柄占用
+    for h in list(root.handlers):
+        root.removeHandler(h)
+        h.close()
+
+    console = logging.StreamHandler()  # 默认 stderr
+    console.setFormatter(logging.Formatter(_FORMAT, datefmt=_CONSOLE_DATEFMT))
+    # 控制台降噪（用户反馈）：request.* 访问日志全量进文件（审计），
+    # 控制台只保留错误与关键生命周期事件，高频轮询不再刷屏
+    console.addFilter(_NoRequestFilter())
+    root.addHandler(console)
+
+    file_handler = RotatingFileHandler(
+        log_dir / "kb.log", maxBytes=settings.log_max_bytes,
+        backupCount=settings.log_backup_count, encoding="utf-8")
+    file_handler.setFormatter(logging.Formatter(_FORMAT))
+    root.addHandler(file_handler)
+    return root