kb-memory 2.1.0__py3-none-any.whl

kb/config.py

@@ -0,0 +1,136 @@
+"""全局配置：环境变量前缀 KB_，支持 .env 文件。"""
+from functools import lru_cache
+from pathlib import Path
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """全部配置；环境变量前缀 KB_，支持 .env 文件。"""
+
+    model_config = SettingsConfigDict(
+        env_prefix="KB_", env_file=".env", extra="ignore"
+    )
+
+    data_dir: Path = Path("kb_data")            # 运行数据根目录
+    device: str = ""                            # 空=自动检测；显式设 cpu/cuda 覆盖
+    # ---- v2.1 项目记忆与资源占用 ----
+    project_cache_size: int = 4                 # 同时打开的项目子库上限（LRU）；全局库不计入
+    project_boost: float = 0.05                 # 项目子库命中加分（检索合并时优先项目记忆）
+    idle_unload_seconds: int = 600              # 嵌入模型空闲卸载秒数；0=不卸载
+    memory_lang: str = "auto"                   # 记忆书写语言：auto=系统 locale，或 zh/en
+    rules_max_chars: int = 4000                 # 自定义规则注入上限，防止提示词膨胀
+    embed_model: str = "BAAI/bge-small-zh-v1.5"   # 轻量优先（设计文档 §3.1，2026-10-19）：~92MB/512维；可显式换 BAAI/bge-m3
+    llm_mode: str = "off"                      # off(默认,完全不加载/调用LLM) | local | auto | cloud
+    ollama_base_url: str = "http://localhost:11434"
+    llm_model: str = ""                        # 本地 Ollama 模型名（空=未配置，用户按自己电脑显存/需求自配，以 ollama list 为准）
+    deepseek_api_key: str = ""             # 兼容旧配置（已弃用，见 llm_api_key/llm_base_url/llm_model）
+    deepseek_base_url: str = "https://api.deepseek.com"
+    deepseek_model: str = "deepseek-v4-flash"
+    # 通用云端 LLM（OpenAI 兼容接口）：任意服务商（OpenAI/DeepSeek/通义/硅基流动等）
+    llm_api_key: str = ""                  # KB_LLM_API_KEY：云服务商 API Key
+    llm_base_url: str = "https://api.deepseek.com"   # KB_LLM_BASE_URL：OpenAI 兼容端点 base_url
+    llm_cloud_model: str = "deepseek-v4-flash"      # KB_LLM_CLOUD_MODEL：云端模型名
+    chunk_size: int = 500
+    chunk_overlap: int = 100
+    watch_dir: Path = Path("data")            # 目录监听（serve 挂载）；空串/"."=不启动
+    api_host: str = "127.0.0.1"
+    api_port: int = 8000
+    api_key: str = ""                            # KB_API_KEY：空=不鉴权（本地回环零摩擦）；非空=启用 Bearer/X-API-Key 鉴权（N19/TASK-0062）
+    context_token_limit: int = 2000             # /ask 检索上下文 token 硬上限
+    llm_max_tokens: int = 800
+    llm_temperature: float = 0.2
+    cache_size: int = 100                       # /ask 答案缓存条数（LRU）
+    cache_sim_threshold: float = 0.95           # 缓存命中相似度阈值
+    sensitive_namespaces: str = ""              # 逗号分隔，敏感 namespace 强制本地
+    # ---- 日志（日志设计文档第 3 节，N17）----
+    log_level: str = "INFO"                     # 全局级别（DEBUG 开发期排查用）
+    log_dir: Path = Path("logs")                # 日志目录（相对仓库根；gitignore 排除）
+    log_max_bytes: int = 1048576                # 单文件 1MB，超限轮转
+    log_backup_count: int = 5                   # 轮转保留备份数（合计 ≤6MB）
+    # ---- 本地监控 Agent（0015 设计书，N18；TASK-0021 去常驻改按需）----
+    monitor_enabled: bool = False               # 默认不启常驻线程（去常驻：按需端点触发）
+    monitor_interval: int = 10                  # 轮询间隔（分钟），≥1，非法回退默认（常驻模式用）
+    monitor_startup_run: bool = True            # 启动时立即跑一轮（便于验证；常驻模式用）
+    monitor_max_tokens: int = 300               # 摘要输出上限（护栏：≤300，硬约束）
+    monitor_autotimer: int = 0                  # KB_MONITOR_AUTOTIMER：外部轮询间隔（分钟），0=关
+    dispatch_enabled: bool = True                # KB_DISPATCH_ENABLED：监控单轮后异常调度（comm:dispatch），默认开（TASK-0049）
+    monitor_llm: str = "off"                     # KB_MONITOR_LLM：监控摘要模式 off=全程纯文本不调LLM(默认零成本/不抢GPU) / auto=LLM可用摘要化不可用降级(TASK-0065)
+    # ---- 记忆治理 A3（N21b 衰减评分公式模块，TASK-0068；N22a 语义去重服务层，TASK-0069）----
+    # ---- Agent 身份隔离与存取审计（A 节点 spec：2026-08-29；v2 2026-08-30）----
+    access_audit_enabled: bool = True             # KB_ACCESS_AUDIT_ENABLED：Agent 存取审计开关（access-audit.log）
+    lang: str = "auto"                            # KB_LANG：消息语言 zh/en/auto（auto=检测系统 locale；B4 节点）
+    decay_enabled: bool = False                   # KB_DECAY_ENABLED：访问频率衰减开关，默认关（零行为变化）
+    decay_lambda: float = 0.02                    # KB_DECAY_LAMBDA：衰减速率 λ（/天），半衰期≈35天
+    decay_gamma: float = 0.3                      # KB_DECAY_GAMMA：高频访问加权系数 γ，access_count=10→约2.0倍
+    # ---- 记忆治理 A3（N22b 新鲜度权重，TASK-0070）----
+    freshness_enabled: bool = False               # KB_FRESHNESS_ENABLED：新鲜度权重开关，默认关（零行为变化）
+    freshness_beta: float = 0.05                  # KB_FRESHNESS_BETA：新鲜度衰减速率 β（/天），半衰期≈14天
+    freshness_alpha: float = 0.3                  # KB_FRESHNESS_ALPHA：新鲜度加权上限系数 α，boost范围[1,1.3]
+    # ---- 记忆治理 A3（N22a 语义去重，TASK-0069）----
+    dedup_enabled: bool = False                   # KB_DEDUP_ENABLED：语义去重开关，默认关（零行为变化）
+    dedup_threshold: float = 0.92                 # KB_DEDUP_THRESHOLD：去重余弦相似度阈值，≥此值视为重复（BGE-M3，0.92以上高度重复）
+    # ---- 记忆治理审计（N23b/TASK-0073）：治理操作结构化审计日志 ----
+    audit_dedup_enabled: bool = True               # KB_AUDIT_DEDUP_ENABLED：去重拦截审计，默认开
+    audit_decay_enabled: bool = False              # KB_AUDIT_DECAY_ENABLED：衰减降权审计，默认关
+    audit_freshness_enabled: bool = False          # KB_AUDIT_FRESHNESS_ENABLED：新鲜度加权审计，默认关
+    # ---- A3 智能层 consolidation（N23c 基础框架，TASK-0076）----
+    consolidation_enabled: bool = False               # KB_CONSOLIDATION_ENABLED：智能归并总开关，默认关（零行为变化）
+    consolidation_confidence_threshold: float = 0.6    # KB_CONSOLIDATION_CONFIDENCE_THRESHOLD：置信度门槛，低于强制 human
+    # ---- A3.5 检索质量（N24 reranker，2026-08-28 spec）----
+    rerank_enabled: bool = False                  # KB_RERANK_ENABLED：交叉重排开关，默认关（零行为变化）
+    rerank_model: str = "BAAI/bge-reranker-v2-m3"  # KB_RERANK_MODEL：重排模型（~600MB fp16 显存）
+    rerank_top_n: int = 20                        # KB_RERANK_TOP_N：参与精排的融合候选数上限
+    # ---- A3.5 检索质量（N25 稀疏向量，2026-08-28 spec）----
+    sparse_enabled: bool = False                  # KB_SPARSE_ENABLED：稀疏第三路开关，默认关（零行为变化）
+
+    @property
+    def chroma_dir(self) -> Path:
+        """全局库 ChromaDB 持久化目录。"""
+        return self.data_dir / "chroma"
+
+    @property
+    def projects_dir(self) -> Path:
+        """项目子库根目录：每个项目一个独立 Chroma/BM25。"""
+        return self.data_dir / "projects"
+
+    @property
+    def rules_file(self) -> Path:
+        """本安装的自定义记忆规则文件。"""
+        return self.data_dir / "rules.md"
+
+    @property
+    def runtime_file(self) -> Path:
+        """运行时选择持久化文件（如 GPU 加速选择）。"""
+        return self.data_dir / "runtime.json"
+
+    @property
+    def sensitive_ns_list(self) -> list[str]:
+        """把敏感 namespace 拆分为列表，空串→[]。"""
+        return [s.strip() for s in self.sensitive_namespaces.split(",") if s.strip()]
+
+    @property
+    def log_file(self) -> Path:
+        """日志文件路径（log_dir/kb.log）。"""
+        return self.log_dir / "kb.log"
+
+    @property
+    def cloud_api_key(self) -> str:
+        """云端 API Key：优先通用 KB_LLM_API_KEY，回退旧 KB_DEEPSEEK_API_KEY（兼容）。"""
+        return self.llm_api_key or self.deepseek_api_key
+
+    @property
+    def cloud_base_url(self) -> str:
+        """云端 base_url：优先通用 KB_LLM_BASE_URL，回退旧 KB_DEEPSEEK_BASE_URL（兼容）。"""
+        return self.llm_base_url or self.deepseek_base_url
+
+    @property
+    def cloud_model(self) -> str:
+        """云端模型名：优先 KB_LLM_CLOUD_MODEL，回退旧 KB_DEEPSEEK_MODEL（兼容）。"""
+        return self.llm_cloud_model or self.deepseek_model
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """全局配置单例；测试用环境变量隔离时调用 get_settings.cache_clear()。"""
+    return Settings()

kb/consolidation.py

@@ -0,0 +1,228 @@
+"""智能层 consolidation 基础模块（A3 智能层 spec，N23c/TASK-0076）。
+
+职责（基础框架，提示词按 TASK-0074 spec §4 落地）：
+- MergeResult：单对记录的归并决策结果模型
+- detect_conflict：启发式冲突检测纯函数（spec §3.1，无 LLM 可用）
+- consolidate_pair：LLM 归并决策封装（spec §4，复用 kb/llm.py，仅本地禁云端）
+- consolidate_dry_run：dry-run 骨架（spec §7 preview 语义，只返回建议不写库）
+
+安全护栏（spec §9）：默认关（consolidation_enabled=False 零行为变化）；
+LLM 输出校验失败 / 置信度低于门槛 → 降级 human；LLM 不可用 → 降级 human。
+零新增依赖；不触碰 service/api/retriever/cli/audit。
+"""
+import json
+import re
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from kb.config import Settings
+from kb.llm import LLMClient, LLMError
+from kb.models import Record
+
+
+class ConsolidationError(Exception):
+    """consolidation 不可用（未启用 / 配置非法等）。"""
+
+
+class MergeResult(BaseModel):
+    """单对记录的归并决策结果（spec §4.3 输出结构）。
+
+    - action：merge（合并）/ independent（保持独立）/ human（人工确认）
+    - merged_content：merge 时的合并后内容；其余决策为 None
+    - confidence：LLM 置信度 0.0-1.0；低于门槛会被强制升级 human
+    - conflict_type：预筛冲突标记（attribute_conflict / temporal / none）
+    """
+
+    action: str
+    merged_content: str | None = None
+    confidence: float = 0.0
+    reason: str = ""
+    conflict_type: str = "none"
+
+
+# 决策枚举（spec §4.1）
+_ACTIONS = ("merge", "independent", "human")
+
+# 属性模式：`关键词[:：] 值`（值取到首个中文标点/换行为止，spec §3.1）
+_KEY_VALUE_RE = re.compile(r"([\u4e00-\u9fa5A-Za-z0-9_\-]{1,16})\s*[:：]\s*([^，。；\n]+)")
+# 断定词（spec §3.1 陈述语气）
+_ASSERTION_WORDS = ("是", "为", "用", "使用", "采用")
+# 时间矛盾的判定阈值（spec §3.1：updated_at 差距 >30 天）
+_TEMPORAL_GAP_DAYS = 30.0
+# 同主题判定：共享字符 bigram 数下限（关键词重叠的轻量近似）
+_TOPIC_OVERLAP_BIGRAMS = 3
+
+
+def _bigrams(text: str) -> set[str]:
+    """文本的字符 bigram 集合（去空白后滑动窗口，用于同主题近似判定）。"""
+    cleaned = re.sub(r"\s+", "", text)
+    return {cleaned[i:i + 2] for i in range(len(cleaned) - 1)}
+
+
+def _extract_key_values(content: str) -> dict[str, str]:
+    """从内容提取 key:value 属性对（spec §3.1 属性模式匹配）。
+
+    同一 key 多次出现取首个（以最早表述为准，后续由 LLM 综合判断）。
+    """
+    kv: dict[str, str] = {}
+    for m in _KEY_VALUE_RE.finditer(content):
+        key = m.group(1).lower()
+        if key not in kv:
+            kv[key] = m.group(2).strip()
+    return kv
+
+
+def detect_conflict(record_a: Record, record_b: Record) -> str:
+    """启发式冲突检测纯函数（spec §3.1，无 LLM 可用）。
+
+    返回 conflict_type：
+    - attribute_conflict：两记录提取到同 key 不同值（值无包含关系）
+    - temporal：同主题（bigram 重叠≥3）+ updated_at 差>30 天 + 含断定词
+    - none：未检测到明显冲突（仍可送 LLM 判断是否互补合并）
+
+    预筛只做标记不做决策，最终决策由 LLM 做出（spec §3.1）。
+    """
+    kv_a = _extract_key_values(record_a.content)
+    kv_b = _extract_key_values(record_b.content)
+    # ① 同 key 不同值（值包含关系视为兼容，如 Python vs Python 3.10）
+    for key, va in kv_a.items():
+        if key in kv_b:
+            vb = kv_b[key]
+            if va == vb or va in vb or vb in va:
+                continue  # 同值或兼容细化
+            return "attribute_conflict"
+    # ② 时间矛盾：同主题 + 时间差>30天 + 陈述语气
+    overlap = _bigrams(record_a.content) & _bigrams(record_b.content)
+    if len(overlap) >= _TOPIC_OVERLAP_BIGRAMS and _has_assertion(
+            record_a.content, record_b.content):
+        try:
+            ta = datetime.fromisoformat(record_a.updated_at)
+            tb = datetime.fromisoformat(record_b.updated_at)
+        except (ValueError, TypeError):
+            return "none"  # 日期无效不做时间判断
+        if abs((ta - tb).total_seconds()) > _TEMPORAL_GAP_DAYS * 86400:
+            return "temporal"
+    return "none"
+
+
+def _has_assertion(*contents: str) -> bool:
+    """任一内容含断定词（是/为/用等，spec §3.1 陈述语气）。"""
+    return any(w in c for c in contents for w in _ASSERTION_WORDS)
+
+
+# ---- LLM 提示词（TASK-0074 spec §4.1/§4.2 原文落地） ----
+
+_SYSTEM_PROMPT = """你是记忆归并代理（Memory Consolidation Agent）。
+任务：给定 2-5 条记忆记录，判断它们是否应合并为一条更完整的记忆，或保持独立，或需要人工确认。
+
+决策规则：
+- merge：记录表达同一事实/同一主题互补信息/同一属性新值明确替代旧值 → 合并为一条
+- independent：记录主题不同/角度不同且各自有独立检索价值 → 保持独立
+- human：信息矛盾且无法判断哪个正确/合并可能丢失重要信息/置信度低 → 人工确认
+
+合并要求：
+- merged_content 保留所有有价值信息，去重，语言简洁
+- 若同一属性有新旧值，保留较新值（updated_at 较晚者），除非旧值明显更准确
+- 不添加记录中不存在的信息
+- 不删除可能有独立检索价值的细节
+
+输出严格 JSON，不输出任何其他文字：
+{"decision":"merge|independent|human","reason":"简短原因","merged_content":"合并后内容或null","conflict_type":"attribute_conflict|temporal|none","confidence":0.0-1.0}"""
+
+
+def _build_user_prompt(record_a: Record, record_b: Record,
+                       conflict_type: str) -> str:
+    """用户提示词模板（spec §4.2）：记录列表 + 预筛冲突标记。"""
+
+    def _line(r: Record) -> str:
+        return (f"[id={r.id}] created_at={r.created_at} "
+                f"updated_at={r.updated_at} tags={r.tags} source={r.source}\n"
+                f"内容：{r.content}")
+
+    return (f"记忆记录列表：\n{_line(record_a)}\n{_line(record_b)}\n\n"
+            f"预筛冲突标记：{conflict_type}"
+            f"（若为 none 表示未检测到明显冲突）\n\n"
+            f"请按系统提示规则决策，输出严格 JSON。")
+
+
+def _parse_llm_output(raw: str, threshold: float) -> MergeResult:
+    """解析并校验 LLM 输出（spec §4.3）。
+
+    - JSON 解析失败 / decision 不在枚举 / merge 时 merged_content 空 → 降级 human
+    - confidence < threshold → 强制升级 human
+    """
+    fallback = MergeResult(
+        action="human", confidence=0.0,
+        reason="LLM 输出校验失败，降级人工确认")
+    try:
+        data = json.loads(raw)
+    except (ValueError, TypeError):
+        return fallback
+    if not isinstance(data, dict):
+        return fallback
+    action = data.get("decision")
+    if action not in _ACTIONS:
+        return fallback
+    try:
+        confidence = float(data.get("confidence", 0.0))
+    except (ValueError, TypeError):
+        return fallback
+    merged = data.get("merged_content") or None
+    # merge 决策必须带非空合并内容
+    if action == "merge" and not (merged and merged.strip()):
+        return fallback
+    # 置信度门槛：低于强制 human（spec §4.3）
+    if confidence < threshold:
+        return MergeResult(
+            action="human", confidence=confidence,
+            reason=f"置信度 {confidence:.2f} 低于门槛 {threshold}，强制人工确认",
+            conflict_type=data.get("conflict_type", "none"))
+    return MergeResult(
+        action=action,
+        merged_content=merged if action == "merge" else None,
+        confidence=confidence,
+        reason=str(data.get("reason", "")),
+        conflict_type=data.get("conflict_type", "none"))
+
+
+def consolidate_pair(record_a: Record, record_b: Record,
+                     client: LLMClient,
+                     settings: Settings | None = None) -> MergeResult:
+    """LLM 归并决策封装（spec §4/§6）：对一对记录调本地 LLM 返回 MergeResult。
+
+    - 复用 kb/llm.py LLMClient.chat，prefer="local"（智能层禁止云端外传）
+    - 预筛冲突标记（detect_conflict）作为用户提示上下文
+    - LLM 不可用/调用失败 → 该对降级 human（不抛异常，spec §6）
+    """
+    threshold = (settings or Settings()).consolidation_confidence_threshold
+    conflict_type = detect_conflict(record_a, record_b)
+    messages = [
+        {"role": "system", "content": _SYSTEM_PROMPT},
+        {"role": "user", "content": _build_user_prompt(
+            record_a, record_b, conflict_type)},
+    ]
+    try:
+        raw = client.chat(messages, prefer="local")
+    except LLMError as exc:
+        return MergeResult(
+            action="human", confidence=0.0,
+            reason=f"LLM 不可用（{exc}），降级人工确认",
+            conflict_type=conflict_type)
+    return _parse_llm_output(raw, threshold)
+
+
+def consolidate_dry_run(pairs: list[tuple[Record, Record]],
+                         client: LLMClient,
+                         settings: Settings) -> list[MergeResult]:
+    """dry-run 归并建议（spec §7 preview 语义）：逐对返回建议，不写库。
+
+    - consolidation_enabled=False 时抛 ConsolidationError（默认关，零行为变化）
+    - 单对失败（LLM 不可用/输出非法）降级 human，不阻塞整批（spec §6）
+    - 纯计算无副作用：不触碰存储层，apply/rollback 由后续节点实现
+    """
+    if not settings.consolidation_enabled:
+        raise ConsolidationError(
+            "consolidation 未启用（需 KB_CONSOLIDATION_ENABLED=true）")
+    return [consolidate_pair(a, b, client, settings)
+            for a, b in pairs]

kb/discovery.py

@@ -0,0 +1,264 @@
+"""服务发现与登录自启（v2.1 spec §3.3）。
+
+安装清单 `~/.kb/install.json` 由 skill 引导脚本写入；`kb where` 按
+manifest → PATH → importlib.metadata 的顺序定位服务安装，`kb autostart`
+在 Windows 启动目录 / systemd user unit / macOS LaunchAgent 之间切换。
+
+English: Service discovery and login autostart (v2.1 spec §3.3). The install
+manifest ~/.kb/install.json is written by the skill bootstrap; `kb where`
+locates the service via manifest → PATH → importlib.metadata, and
+`kb autostart` manages the Windows Startup entry / systemd user unit /
+macOS LaunchAgent.
+"""
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+
+APP_NAME = "kb"
+UNIT_NAME = "kb.service"
+LAUNCH_LABEL = "io.github.fish827.kb"
+
+
+def manifest_path() -> Path:
+    """安装清单路径：~/.kb/install.json。"""
+    return Path.home() / ".kb" / "install.json"
+
+
+def read_manifest() -> dict | None:
+    """读取安装清单；缺失或损坏返回 None。"""
+    path = manifest_path()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def write_manifest(*, python: str, version: str, data_dir: str,
+                   extras: str = "", venv: str = "") -> Path:
+    """写入安装清单（skill 引导安装成功后调用）。
+    English: Write the install manifest after a successful bootstrap install."""
+    from datetime import datetime
+    path = manifest_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "python": str(python),
+        "version": version,
+        "data_dir": str(data_dir),
+        "extras": extras,
+        "venv": str(venv),
+        "installed_at": datetime.now().isoformat(timespec="seconds"),
+    }
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2),
+                    encoding="utf-8")
+    return path
+
+
+def _package_version() -> str:
+    try:
+        from importlib.metadata import version
+        return version("kb-memory")
+    except Exception:
+        from kb import __version__
+        return __version__
+
+
+def _running(host: str, port: int) -> bool:
+    """探测本机服务健康端点（0.5s 超时，不依赖第三方库）。"""
+    import urllib.request
+    try:
+        with urllib.request.urlopen(
+                f"http://{host}:{port}/api/v1/healthz", timeout=0.5) as resp:
+            return resp.status == 200
+    except Exception:
+        return False
+
+
+def discover(settings=None) -> dict:
+    """按 manifest → PATH → 当前解释器 的顺序发现服务安装。
+
+    返回 {source, python, version, data_dir, running, endpoint, command}。
+    English: Discover the service installation in manifest → PATH → current
+    interpreter order. Returns a dict describing the installation.
+    """
+    if settings is None:
+        from kb.config import get_settings
+        settings = get_settings()
+    host, port = settings.api_host, settings.api_port
+    manifest = read_manifest()
+    if manifest and manifest.get("python") and Path(manifest["python"]).exists():
+        return {
+            "source": "manifest",
+            "python": manifest["python"],
+            "version": manifest.get("version") or _package_version(),
+            "data_dir": manifest.get("data_dir") or str(settings.data_dir),
+            "venv": manifest.get("venv") or "",
+            "running": _running(host, port),
+            "endpoint": f"http://{host}:{port}/mcp/",
+            "command": [manifest["python"], "-m", "kb", "serve",
+                        "--non-interactive"],
+        }
+    kb_bin = shutil.which("kb")
+    if kb_bin:
+        python = sys.executable
+        if os.name == "nt":
+            candidate = Path(kb_bin).with_name("python.exe")
+            if candidate.exists():
+                python = str(candidate)
+        return {
+            "source": "path",
+            "python": python,
+            "version": _package_version(),
+            "data_dir": str(settings.data_dir),
+            "venv": "",
+            "running": _running(host, port),
+            "endpoint": f"http://{host}:{port}/mcp/",
+            "command": [python, "-m", "kb", "serve", "--non-interactive"],
+        }
+    return {
+        "source": "package",
+        "python": sys.executable,
+        "version": _package_version(),
+        "data_dir": str(settings.data_dir),
+        "venv": "",
+        "running": _running(host, port),
+        "endpoint": f"http://{host}:{port}/mcp/",
+        "command": [sys.executable, "-m", "kb", "serve",
+                    "--non-interactive"],
+    }
+
+
+# ---- 登录自启 ----
+
+def autostart_file() -> Path:
+    """当前平台的登录自启文件路径。"""
+    if os.name == "nt":
+        base = os.environ.get("APPDATA") or str(Path.home() / "AppData/Roaming")
+        return (Path(base) / "Microsoft" / "Windows" / "Start Menu"
+                / "Programs" / "Startup" / "kb.cmd")
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "LaunchAgents" / f"{LAUNCH_LABEL}.plist"
+    return Path.home() / ".config" / "systemd" / "user" / UNIT_NAME
+
+
+def _service_target(info: dict) -> tuple[str, str]:
+    """确定自启解释器与数据目录：manifest 优先，其次当前解释器/配置。"""
+    python = info.get("python") or sys.executable
+    data_dir = info.get("data_dir") or ""
+    return python, data_dir
+
+
+def _windows_content(info: dict) -> str:
+    python, data_dir = _service_target(info)
+    pythonw = str(Path(python).with_name("pythonw.exe"))
+    exe = pythonw if Path(pythonw).exists() else python
+    lines = ["@echo off"]
+    if data_dir:
+        lines.append(f'set "KB_DATA_DIR={data_dir}"')
+    lines.append(f'start "" "{exe}" -m kb serve --non-interactive')
+    return "\r\n".join(lines) + "\r\n"
+
+
+def _systemd_content(info: dict) -> str:
+    python, data_dir = _service_target(info)
+    env = f"Environment=KB_DATA_DIR={data_dir}\n" if data_dir else ""
+    return (
+        "[Unit]\n"
+        "Description=kb local memory & knowledge service\n"
+        "After=network.target\n\n"
+        "[Service]\n"
+        "Type=simple\n"
+        f"ExecStart={python} -m kb serve --non-interactive\n"
+        f"{env}"
+        "Restart=on-failure\n"
+        "RestartSec=5\n\n"
+        "[Install]\n"
+        "WantedBy=default.target\n"
+    )
+
+
+def _launchd_content(info: dict) -> str:
+    python, data_dir = _service_target(info)
+    env = ""
+    if data_dir:
+        env = ("    <key>EnvironmentVariables</key>\n    <dict>\n"
+               "        <key>KB_DATA_DIR</key>\n"
+               f"        <string>{data_dir}</string>\n    </dict>\n")
+    return (
+        '<?xml version="1.0" encoding="UTF-8"?>\n'
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" '
+        '"http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n'
+        f'<plist version="1.0">\n<dict>\n'
+        f'    <key>Label</key>\n    <string>{LAUNCH_LABEL}</string>\n'
+        '    <key>ProgramArguments</key>\n    <array>\n'
+        f'        <string>{python}</string>\n'
+        '        <string>-m</string>\n        <string>kb</string>\n'
+        '        <string>serve</string>\n'
+        '        <string>--non-interactive</string>\n    </array>\n'
+        '    <key>RunAtLoad</key>\n    <true/>\n'
+        f'{env}'
+        '</dict>\n</plist>\n'
+    )
+
+
+def autostart_enable(info: dict | None = None, run: bool = True) -> dict:
+    """写入并启用登录自启；返回 {file, platform, activated}。
+    English: Write and enable login autostart; returns {file, platform, activated}."""
+    import subprocess
+    info = info or discover()
+    path = autostart_file()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    activated = False
+    if os.name == "nt":
+        path.write_text(_windows_content(info), encoding="utf-8",
+                        newline="")
+    elif sys.platform == "darwin":
+        path.write_text(_launchd_content(info), encoding="utf-8")
+        if run:
+            activated = _run(["launchctl", "load", str(path)]) is not None
+    else:
+        path.write_text(_systemd_content(info), encoding="utf-8")
+        if run:
+            _run(["systemctl", "--user", "daemon-reload"])
+            activated = _run(["systemctl", "--user", "enable", "--now",
+                              UNIT_NAME]) is not None
+    return {"file": str(path), "platform": sys.platform,
+            "activated": activated}
+
+
+def autostart_disable(run: bool = True) -> dict:
+    """删除自启文件并停用；返回 {file, removed, deactivated}。"""
+    path = autostart_file()
+    deactivated = False
+    if run and sys.platform == "darwin" and path.exists():
+        deactivated = _run(["launchctl", "unload", str(path)]) is not None
+    elif run and os.name != "nt" and path.exists():
+        _run(["systemctl", "--user", "disable", "--now", UNIT_NAME])
+        deactivated = _run(["systemctl", "--user", "daemon-reload"]) is not None
+    removed = path.exists()
+    try:
+        path.unlink(missing_ok=True)
+    except OSError:
+        removed = False
+    return {"file": str(path), "removed": removed,
+            "deactivated": deactivated}
+
+
+def autostart_status() -> dict:
+    """自启状态：是否已配置 + 文件路径 + 平台。"""
+    path = autostart_file()
+    return {"enabled": path.exists(), "file": str(path),
+            "platform": sys.platform}
+
+
+def _run(cmd: list[str]) -> int | None:
+    """执行系统命令并吞掉输出；失败返回 None（不抛异常，自启失败可降级提示）。"""
+    import subprocess
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True,
+                              timeout=15)
+        return proc.returncode if proc.returncode == 0 else None
+    except (OSError, subprocess.SubprocessError):
+        return None