foxclaw 0.1.0 → 0.1.2

package/python/foxclaw/core/secrets.py

@@ -0,0 +1,134 @@
+"""本地密钥存储:优先 OS 凭据库(keyring),不可用时回退 base64 混淆。
+
+为什么值得单独一层:自定义模型的 API key 之前只做 base64 落到
+`custom_models.json`。base64 是**编码**不是加密 —— 任何读到该文件的人
+(含备份、网盘同步、误提交)一行 python 就能还原成明文。
+
+keyring 把密钥交给操作系统保管:Windows DPAPI / macOS Keychain / Linux
+Secret Service。密钥材料不再出现在项目目录里,备份也不会带走它。
+
+回退是刻意的:keyring 是可选依赖,且 Linux 无桌面会话时常常没有可用后端
+(`NoKeyringError`)。这种情况下继续 base64,而不是拒绝保存 —— 否则用户
+连「改个 key」都做不到。`store()` 返回 False 即表示没接管,调用方据此决定
+要不要继续写 `api_key_obf`。
+
+命名空间:`SERVICE` 固定,username = 模型名。改名必须调 `rename()`,
+否则 `load(新名)` 取不到,key 会静默丢失。
+"""
+
+from __future__ import annotations
+
+import base64
+
+SERVICE = "foxclaw.llm"
+
+# 后端探测结果缓存(含失败):每个请求都 import + 探测一次没必要。
+# 失败也缓存是有意的 —— 没有可用后端时不该反复重试。
+_kr_cache = None
+_kr_probed = False
+
+
+def _keyring():
+    """取得可用的 keyring 模块;无可用后端返回 None。"""
+    global _kr_cache, _kr_probed
+    if _kr_probed:
+        return _kr_cache
+    _kr_probed = True
+    try:
+        import keyring
+        from keyring.backends.fail import Keyring as _FailBackend
+        # 默认后端是 Fail 时说明系统上没有可用凭据库(典型:无桌面会话的 Linux)
+        if isinstance(keyring.get_keyring(), _FailBackend):
+            _kr_cache = None
+        else:
+            _kr_cache = keyring
+    except Exception:
+        _kr_cache = None
+    return _kr_cache
+
+
+def available() -> bool:
+    """是否有可用的 OS 凭据库。"""
+    return _keyring() is not None
+
+
+def reset_probe() -> None:
+    """清掉后端探测缓存(测试里替换 keyring 后需要重探)。"""
+    global _kr_cache, _kr_probed
+    _kr_cache = None
+    _kr_probed = False
+
+
+def obf(text: str) -> str:
+    """base64 混淆:只防 grep,不提供任何机密性。"""
+    if not text:
+        return ""
+    return base64.b64encode(text.encode()).decode()
+
+
+def deobf(text: str) -> str:
+    if not text:
+        return ""
+    try:
+        return base64.b64decode(text.encode()).decode()
+    except Exception:
+        return text
+
+
+def store(name: str, key: str) -> bool:
+    """把 key 写进 OS 凭据库。True = 已接管,调用方不该再落盘密文。"""
+    if not name or not key:
+        return False
+    kr = _keyring()
+    if kr is None:
+        return False
+    try:
+        kr.set_password(SERVICE, name, key)
+        return True
+    except Exception:
+        return False
+
+
+def load(name: str, obf_key: str = "") -> str:
+    """取 key:keyring 优先,回退到 base64(旧记录 / 无后端时写入的)。"""
+    if name:
+        kr = _keyring()
+        if kr is not None:
+            try:
+                got = kr.get_password(SERVICE, name)
+                if got:
+                    return got
+            except Exception:
+                pass
+    return deobf(obf_key)
+
+
+def delete(name: str) -> None:
+    if not name:
+        return
+    kr = _keyring()
+    if kr is None:
+        return
+    try:
+        kr.delete_password(SERVICE, name)
+    except Exception:
+        pass
+
+
+def rename(old: str, new: str) -> bool:
+    """改名时搬迁凭据。True = 已搬过去。"""
+    if not old or not new or old == new:
+        return False
+    kr = _keyring()
+    if kr is None:
+        return False
+    try:
+        key = kr.get_password(SERVICE, old)
+    except Exception:
+        return False
+    if not key:
+        return False
+    if store(new, key):
+        delete(old)
+        return True
+    return False

package/python/foxclaw/core/sessions.py

@@ -0,0 +1,157 @@
+"""
+会话存储(SessionStore)—— 让对话有历史。
+
+背景:此前对话完全无状态,前端只在内存里存 `_chatHistory`,**刷新即丢**,也没有
+"所有会话"可回看。本模块把每个会话落盘成一个 JSON 文件(`<data_dir>/sessions/<id>.json`),
+提供 建/列/读/追加/改名/删 六个操作。
+
+设计取舍:
+  · 用 JSON 文件而非 SQLite —— 会话是低频写、小体量、便于人肉查看/备份/迁移;
+  · **线程安全**:对话跑在 `chat-stream` 后台线程,与 FastAPI 请求线程并发 → 全局 RLock
+    (与项目"任何跨线程共享状态必须加锁"的铁律一致);
+  · 标题自动从首条用户消息提炼,用户也可改名;
+  · 列表按 updated_at 倒序,只回轻字段(不回 messages,避免列表接口负载爆炸)。
+"""
+from __future__ import annotations
+import json
+import re
+import threading
+import time
+import uuid
+from pathlib import Path
+
+
+def _now() -> float:
+    return time.time()
+
+
+def derive_title(text: str, limit: int = 24) -> str:
+    """从首条用户消息提炼会话标题:截到首个句读、限长。"""
+    s = " ".join(str(text or "").split()).strip()
+    if not s:
+        return "新会话"
+    s = re.split(r"[。！？!?\n\r]", s, 1)[0].strip()
+    return (s[:limit] or "新会话")
+
+
+class SessionStore:
+    """文件式会话存储。所有公开方法线程安全。"""
+
+    def __init__(self, base_dir):
+        self.base = Path(base_dir)
+        self.base.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.RLock()
+
+    # ── 内部 ──────────────────────────────────────────────
+    def _path(self, sid: str) -> Path:
+        # 只允许我们自己生成的 id 形态,杜绝 ../ 之类路径穿越
+        if not re.fullmatch(r"[A-Za-z0-9_-]{1,64}", str(sid or "")):
+            raise ValueError("非法会话 id")
+        return self.base / f"{sid}.json"
+
+    def _read(self, sid: str) -> dict | None:
+        try:
+            p = self._path(sid)
+            if not p.exists():
+                return None
+            with open(p, "r", encoding="utf-8") as f:
+                return json.load(f)
+        except Exception:
+            return None
+
+    def _write(self, data: dict):
+        p = self._path(data["id"])
+        tmp = p.with_suffix(".tmp")
+        with open(tmp, "w", encoding="utf-8") as f:
+            json.dump(data, f, ensure_ascii=False, indent=1)
+        tmp.replace(p)          # 原子替换,防写一半崩坏
+
+    # ── 公开 API ──────────────────────────────────────────
+    def create(self, title: str = "", agent_id: str = "supervisor") -> dict:
+        sid = uuid.uuid4().hex[:12]
+        data = {"id": sid, "title": (title or "新会话")[:60], "agent_id": agent_id,
+                "created_at": _now(), "updated_at": _now(), "messages": []}
+        with self._lock:
+            self._write(data)
+        return self.brief(data)
+
+    def list(self, limit: int = 50) -> list:
+        out = []
+        with self._lock:
+            for p in self.base.glob("*.json"):
+                try:
+                    with open(p, "r", encoding="utf-8") as f:
+                        out.append(self.brief(json.load(f)))
+                except Exception:
+                    continue
+        out.sort(key=lambda x: x.get("updated_at") or 0, reverse=True)
+        return out[:max(1, int(limit))]
+
+    @staticmethod
+    def brief(d: dict) -> dict:
+        """列表用的轻字段(不含 messages)。"""
+        msgs = d.get("messages") or []
+        last = ""
+        for m in reversed(msgs):
+            if m.get("content"):
+                last = str(m["content"])[:60]
+                break
+        return {"id": d.get("id"), "title": d.get("title") or "新会话",
+                "agent_id": d.get("agent_id") or "supervisor",
+                "created_at": d.get("created_at"), "updated_at": d.get("updated_at"),
+                "message_count": len(msgs), "last": last}
+
+    def get(self, sid: str) -> dict | None:
+        with self._lock:
+            return self._read(sid)
+
+    def append(self, sid: str, role: str, content: str, attachments: list = None) -> bool:
+        """追加一条消息;会话不存在则忽略。首条用户消息会顺带定标题。
+        attachments(可选)= 聊天附件元数据 [{name,size,mime,url}];只落盘轻字段(不存 text,
+        避免会话文件随附件正文膨胀),供「会话历史」回看时渲染附件卡片。"""
+        if role not in ("user", "assistant") or not content:
+            return False
+        with self._lock:
+            d = self._read(sid)
+            if d is None:
+                return False
+            msgs = d.setdefault("messages", [])
+            msg = {"role": role, "content": str(content), "ts": _now()}
+            if attachments:
+                atts = [
+                    {"name": str(a.get("name", ""))[:200],
+                     "size": int(a.get("size") or 0),
+                     "mime": str(a.get("mime", ""))[:100],
+                     "url": str(a.get("url", ""))[:500]}
+                    for a in attachments if isinstance(a, dict)
+                ]
+                if atts:
+                    msg["attachments"] = atts
+            msgs.append(msg)
+            # 标题仍是默认值时,用首条用户消息提炼
+            if role == "user" and (not d.get("title") or d["title"] == "新会话"):
+                d["title"] = derive_title(content)
+            d["updated_at"] = _now()
+            self._write(d)
+            return True
+
+    def rename(self, sid: str, title: str) -> bool:
+        with self._lock:
+            d = self._read(sid)
+            if d is None:
+                return False
+            d["title"] = (title or "新会话")[:60]
+            d["updated_at"] = _now()
+            self._write(d)
+            return True
+
+    def delete(self, sid: str) -> bool:
+        with self._lock:
+            try:
+                p = self._path(sid)
+                if p.exists():
+                    p.unlink()
+                    return True
+            except Exception:
+                pass
+            return False