foxclaw 0.1.2 → 0.1.3

package/python/foxclaw/core/recovery.py

@@ -50,25 +50,22 @@ def _pid_alive(pid: int) -> bool:
         handle = kernel32.OpenProcess(
             PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
         if not handle:
-            return False       # 打不开句柄 = 进程不存在(或无权限)→ 保守判不存活
+            return False
         try:
             code = wintypes.DWORD()
             if not kernel32.GetExitCodeProcess(handle, ctypes.byref(code)):
                 return False
-            # STILL_ACTIVE=259 表示仍在运行。极少数进程恰以 259 退出会被误判存活,
-            # 但这是"只读探测"的可接受代价——绝不误杀才是首要目标(psutil 同此取舍)。
             return code.value == STILL_ACTIVE
         finally:
             kernel32.CloseHandle(handle)
 
-    # POSIX
     try:
         os.kill(pid, 0)
         return True
     except ProcessLookupError:
         return False
     except PermissionError:
-        return True       # 存在但无权限 → 视为存活
+        return True
     except Exception:
         return False
 
@@ -79,14 +76,13 @@ class TaskRecord:
     description: str
     pid: int
     started: float
-    status: str = "in_progress"        # in_progress / done / failed / interrupted
+    status: str = "in_progress"
     session_id: str = ""
     channel: str = ""
     finished: float = 0.0
-    boot_id: str = ""                  # 哪次启动产生的(防 pid 复用误判)
-    # 【P2-4】恢复策略字段
-    retryable: bool = False            # 调用方标记"可安全重试"(无副作用/幂等)
-    start_count: int = 1               # 同一 task_id 被 start 的次数(重复 start 保留最后一次)
+    boot_id: str = ""
+    retryable: bool = False
+    start_count: int = 1
 
     def to_dict(self) -> dict:
         return asdict(self)
@@ -95,10 +91,10 @@ class TaskRecord:
 @dataclass
 class RecoveryPlan:
     """【P2-4】恢复计划:把中断任务分类,调用方(API 层/前端)据此决定动作。"""
-    retryable: list = field(default_factory=list)      # 可重试的 task_id
-    notify_user: list = field(default_factory=list)    # 需通知用户的(来自某个渠道)
-    needs_manual: list = field(default_factory=list)   # 需人工处理的(保守默认)
-    details: list = field(default_factory=list)        # [{task_id,description,channel,...,action}]
+    retryable: list = field(default_factory=list)
+    notify_user: list = field(default_factory=list)
+    needs_manual: list = field(default_factory=list)
+    details: list = field(default_factory=list)
 
     def to_dict(self) -> dict:
         return asdict(self)
@@ -107,20 +103,17 @@ class RecoveryPlan:
 class RestartRecovery:
     """任务生命周期日志 + 启动恢复扫描。"""
 
-    def __init__(self, log_path: str, current_pid: int = None, boot_id: str = None,
+    def __init__(self, log_path: str, current_pid: int | None = None, boot_id: str | None = None,
                  spine=None, fsync: bool = True):
         self.log_path = log_path
         self.current_pid = current_pid or os.getpid()
-        # boot_id:每次启动唯一。任务记录带上它,扫描时"非本次启动的 in_progress"
-        # 即属于上一次运行 —— 比单纯靠 pid 可靠(pid 会被 OS 复用)。
         import uuid
         self.boot_id = boot_id or uuid.uuid4().hex[:16]
-        self._active: dict[str, TaskRecord] = {}   # 当前进程内进行中的任务
-        self._spine = spine                        # 【P2-4】审计脊柱(可空,None 静默)
-        self._fsync = fsync                        # 【P2-4】fsync 可配(默认开=崩溃安全;高频场景可关)
+        self._active: dict[str, TaskRecord] = {}
+        self._spine = spine
+        self._fsync = fsync
         os.makedirs(os.path.dirname(log_path) or ".", exist_ok=True)
 
-    # ── 任务生命周期 ──────────────────────────────────────
     def task_started(self, task_id: str, description: str,
                      session_id: str = "", channel: str = "",
                      retryable: bool = False) -> TaskRecord:
@@ -142,7 +135,6 @@ class RestartRecovery:
                       "status": status, "pid": self.current_pid,
                       "finished": time.time()})
 
-    # ── 步骤级 checkpoint(P1 断点可续)─────────────────────
     def record_step(self, task_id: str, step: dict) -> None:
         """记一条「已完成的步骤」。管线每完成一个 stage、工具轮每完成一个工具调用各落一条,
         崩溃/断连后 `steps_of()` 能回答「跑到哪一步」,也让续跑知道哪些步骤不必重做。
@@ -171,7 +163,7 @@ class RestartRecovery:
                     try:
                         ev = json.loads(line)
                     except Exception:
-                        continue        # 末行可能写一半(append 崩溃),跳过
+                        continue
                     if ev.get("event") == "step" and ev.get("task_id") == task_id:
                         out.append({k: v for k, v in ev.items()
                                     if k not in ("event", "task_id")})
@@ -179,7 +171,6 @@ class RestartRecovery:
             return out
         return out[-limit:] if limit else out
 
-    # ── 启动恢复扫描 ──────────────────────────────────────
     def scan_interrupted(self) -> list[TaskRecord]:
         """启动时调用:重建日志状态,找出被中断的任务。
 
@@ -194,9 +185,7 @@ class RestartRecovery:
             if rec.status != "in_progress":
                 continue
             if rec.boot_id == self.boot_id:
-                continue        # 本次启动自己的任务,跳过
-            # 非本次启动的 in_progress = 上次运行遗留 = 被中断
-            # (pid 是否存活作为辅助信息记录,但不作为唯一判据)
+                continue
             rec.status = "interrupted"
             interrupted.append(rec)
             self._append({"event": "interrupted", "task_id": task_id,
@@ -220,7 +209,7 @@ class RestartRecovery:
                     try:
                         ev = json.loads(line)
                     except Exception:
-                        continue        # 跳过损坏行(append 模式下末行可能写一半)
+                        continue
                     self._apply_event(records, ev)
         except Exception:
             pass
@@ -233,7 +222,6 @@ class RestartRecovery:
             return
         kind = ev.get("event")
         if kind == "start":
-            # 【P2-4】同一 task_id 多次 start:保留最后一次,但累计 start_count
             existing = records.get(tid)
             start_count = (existing.start_count + 1) if existing else 1
             records[tid] = TaskRecord(
@@ -249,7 +237,7 @@ class RestartRecovery:
             if kind == "finish":
                 records[tid].finished = ev.get("finished", 0)
 
-    def plan_recovery(self, interrupted: list = None) -> RecoveryPlan:
+    def plan_recovery(self, interrupted: list | None = None) -> RecoveryPlan:
         """【P2-4】给中断任务分类,返回恢复计划(不改 scan_interrupted 的返回,兼容)。
 
         分类规则:
@@ -304,9 +292,9 @@ class RestartRecovery:
                 f.write(json.dumps(entry, ensure_ascii=False) + "\n")
                 f.flush()
                 if self._fsync:
-                    os.fsync(f.fileno())     # 落盘,防崩溃丢最后一条
+                    os.fsync(f.fileno())
         except Exception:
-            pass        # 日志失败不影响主流程
+            pass
 
     def compact_log(self, keep_recent_days: float = 7):
         """压实日志:丢弃已完成且超过 N 天的记录,防文件无限膨胀。
@@ -317,7 +305,6 @@ class RestartRecovery:
         cutoff = time.time() - keep_recent_days * 86400
         keep = []
         for rec in records.values():
-            # 保留:仍在进行的,或最近有活动(开始或完成)的
             last_activity = max(rec.started, rec.finished or 0)
             if rec.status == "in_progress" or last_activity >= cutoff:
                 keep.append({"event": "start", **rec.to_dict()})
@@ -331,7 +318,7 @@ class RestartRecovery:
             with open(tmp, "w", encoding="utf-8") as f:
                 for e in keep:
                     f.write(json.dumps(e, ensure_ascii=False) + "\n")
-                for e in steps:              # 保留任务的 step 事件随记录一起搬走
+                for e in steps:
                     f.write(json.dumps(e, ensure_ascii=False) + "\n")
             os.replace(tmp, self.log_path)
         except Exception:

package/python/foxclaw/core/scheduler.py

@@ -9,45 +9,46 @@
 """
 from __future__ import annotations
 from dataclasses import dataclass
+from typing import Optional
 
 
 @dataclass
 class TaskIntent:
     """任务意图:粗粒度类别 + 三个亲和度提示。"""
-    category: str                 # reasoning / memory / workflow / tool
+    category: str
     confidence: float
-    memory_affinity: float        # 记忆依赖度
-    reasoning_depth: float        # 推理深度提示
+    memory_affinity: float
+    reasoning_depth: float
 
 
 @dataclass
 class TaskFeatures:
-    complexity: float             # 复杂度
-    memory_dependency: float      # 记忆依赖
-    tool_cost: float              # 工具成本
-    reasoning_depth: float        # 推理深度
-    urgency: float                # 紧急度
-    expected_runtime: float       # 预期耗时
+    complexity: float
+    memory_dependency: float
+    tool_cost: float
+    reasoning_depth: float
+    urgency: float
+    expected_runtime: float
 
 
 @dataclass
 class SystemContext:
     """系统负载上下文。主管据此调整优先级、决定是否抢占。"""
-    active_agents: int = 0        # 当前活跃 Agent 数
-    queue_depth: int = 0          # 待处理任务队列深度
-    system_load: float = 0.1      # 系统负载 0-1
+    active_agents: int = 0
+    queue_depth: int = 0
+    system_load: float = 0.1
 
 
 @dataclass
 class ScheduleDecision:
-    priority: float               # 最终优先级 0-1
-    route_hint: str               # 路由倾向:agent / tool / workflow
-    execution_mode: str           # preemptive(抢占) / standard(标准)
-    preemptible: bool             # 是否可触发抢占
-    expected_budget: float        # 预期预算(耗时×优先级修正)
-    intent: TaskIntent = None
-    features: TaskFeatures = None
-    preemption_reason: str = None
+    priority: float
+    route_hint: str
+    execution_mode: str
+    preemptible: bool
+    expected_budget: float
+    intent: Optional[TaskIntent] = None
+    features: Optional[TaskFeatures] = None
+    preemption_reason: Optional[str] = None
     reason: str = ""
 
     def to_dict(self) -> dict:
@@ -63,7 +64,6 @@ class ScheduleDecision:
 class CognitiveScheduler:
     """意图感知的认知调度器。"""
 
-    # 意图识别关键词(粗分类)
     _REASONING = ["规划", "计划", "分析", "设计", "推理", "为什么", "怎么办", "策略", "方案"]
     _MEMORY = ["记得", "记忆", "之前", "上次", "回忆", "查一下我", "我说过"]
     _WORKFLOW = ["然后", "接着", "之后", "依次", "批量", "流程", "再然后", "下一步"]
@@ -86,7 +86,6 @@ class CognitiveScheduler:
             complexity, tool_cost, urgency, runtime = 0.7, 0.6, 0.65, 0.8
         elif intent.category == "memory":
             complexity, tool_cost, urgency, runtime = 0.5, 0.2, 0.55, 0.6
-        # 紧急词加成
         if any(w in task for w in ["紧急", "立刻", "马上", "尽快", "急"]):
             urgency = min(1.0, urgency + 0.3)
         return TaskFeatures(complexity, intent.memory_affinity, tool_cost,
@@ -117,16 +116,14 @@ class CognitiveScheduler:
             return "tool"
         return "agent" if priority > 0.35 else "tool"
 
-    def preemption_reason(self, priority: float, ctx: SystemContext) -> str:
-        # 阈值匹配实际优先级范围(本调度器优先级多在 0.4 以内,
-        # 原 0.55/0.7 几乎不可达,会让抢占形同虚设)
+    def preemption_reason(self, priority: float, ctx: SystemContext) -> str | None:
         if priority > 0.35 and ctx.active_agents >= 3:
             return "高优先级 + Agent 压力大"
         if priority > 0.4 and ctx.queue_depth >= 2:
             return "高优先级 + 队列积压"
         return None
 
-    def schedule(self, task: str, ctx: SystemContext = None) -> ScheduleDecision:
+    def schedule(self, task: str, ctx: SystemContext | None = None) -> ScheduleDecision:
         """主入口:给一个任务做完整调度决策。"""
         ctx = ctx or SystemContext()
         intent = self.parse_intent(task)

package/python/foxclaw/core/secrets.py

@@ -22,8 +22,6 @@ import base64
 
 SERVICE = "foxclaw.llm"
 
-# 后端探测结果缓存(含失败):每个请求都 import + 探测一次没必要。
-# 失败也缓存是有意的 —— 没有可用后端时不该反复重试。
 _kr_cache = None
 _kr_probed = False
 
@@ -37,7 +35,6 @@ def _keyring():
     try:
         import keyring
         from keyring.backends.fail import Keyring as _FailBackend
-        # 默认后端是 Fail 时说明系统上没有可用凭据库(典型:无桌面会话的 Linux)
         if isinstance(keyring.get_keyring(), _FailBackend):
             _kr_cache = None
         else:

package/python/foxclaw/core/sessions.py

@@ -15,6 +15,7 @@
 from __future__ import annotations
 import json
 import re
+import builtins
 import threading
 import time
 import uuid
@@ -42,9 +43,7 @@ class SessionStore:
         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"
@@ -64,9 +63,8 @@ class SessionStore:
         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)          # 原子替换,防写一半崩坏
+        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,
@@ -105,7 +103,8 @@ class SessionStore:
         with self._lock:
             return self._read(sid)
 
-    def append(self, sid: str, role: str, content: str, attachments: list = None) -> bool:
+    def append(self, sid: str, role: str, content: str,
+               attachments: builtins.list | None = None) -> bool:
         """追加一条消息;会话不存在则忽略。首条用户消息会顺带定标题。
         attachments(可选)= 聊天附件元数据 [{name,size,mime,url}];只落盘轻字段(不存 text,
         避免会话文件随附件正文膨胀),供「会话历史」回看时渲染附件卡片。"""
@@ -128,7 +127,6 @@ class SessionStore:
                 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()

package/python/foxclaw/core/settings.py

@@ -45,8 +45,6 @@ from functools import lru_cache
 from pathlib import Path
 from typing import Any, Iterable, Mapping, Sequence
 
-# provider → 需要的环境变量(与 core/model_router.PROVIDER_ENV 保持一致;
-# 这里重复一份是为了让 settings 不依赖 model_router —— 那会拖入 LLM SDK 的导入)。
 PROVIDER_KEY_ENV: dict[str, str] = {
     "anthropic": "ANTHROPIC_API_KEY",
     "openai": "OPENAI_API_KEY",
@@ -58,8 +56,6 @@ PROVIDER_KEY_ENV: dict[str, str] = {
     "generic": "LLM_API_KEY",
 }
 
-# 只检查这些前缀下的"未知键":它们属于本项目或本项目专用的厂商约定,
-# 出现没人读的名字几乎必然是拼错。像 `PATH` / `HOME` 这类系统变量不在此列。
 OWNED_PREFIXES = (
     "FOXCLAW_", "BAIDU_", "AMAP_", "LLM_", "GENERIC_LLM_",
     "MINIMAX_", "LOCAL_LLM_", "HKC_", "HMR_",
@@ -75,10 +71,10 @@ class Opt:
     """一个环境变量的声明。kind 只描述**解析方式**,不代表业务语义。"""
 
     name: str
-    kind: str = "str"                  # str | int | float | csv | choice
+    kind: str = "str"
     default: Any = ""
     group: str = "其他"
-    hint: str = ""                     # 期望格式 / 示例(拼进出错信息)
+    hint: str = ""
     choices: Sequence[str] = ()
     secret: bool = False
     lo: float | None = None
@@ -86,10 +82,6 @@ class Opt:
 
 
 SPECS: tuple[Opt, ...] = (
-    # lo/hi 只给**调用点自己不兜底**的项。像 TRACE_RETAIN 已有 max(100, ...)、
-    # BAIDU_SEARCH_TIMEOUT 已有 max(5, ...):在那里再报一次范围错,等于把"clamp"
-    # 变成"整条配置作废退默认",反而更糟。
-    # ── 模型 ────────────────────────────────────────────────────────────────
     Opt("LLM_PROVIDER", "choice", "", "模型",
         "anthropic / openai / deepseek / google / qwen / local / minimax / generic",
         tuple(PROVIDER_KEY_ENV)),
@@ -109,9 +101,10 @@ SPECS: tuple[Opt, ...] = (
     Opt("LLM_API_KEY", "str", "", "模型", "generic(通用 openai 兼容)的 key", secret=True),
     Opt("LLM_BASE_URL", "str", "", "模型", "generic 的 base_url,如 https://host/v1"),
     Opt("LOCAL_LLM_BASE", "str", "", "模型", "本地推理服务的 base_url"),
-    # ── 服务 ────────────────────────────────────────────────────────────────
     Opt("FOXCLAW_PORT", "int", 8000, "服务", "HTTP 监听端口", lo=1, hi=65535),
     Opt("FOXCLAW_DATA_DIR", "str", "", "服务", "数据目录(默认 <仓库>/foxclaw_data)"),
+    Opt("FOXCLAW_CLAWHUB_REGISTRY", "str", "", "服务",
+        "ClawHub 地址(默认 https://clawhub.ai;内网镜像或自建 registry 填这里)"),
     Opt("FOXCLAW_IMPORT_ROOTS", "csv", "", "服务",
         "额外允许的导入目录(逗号分隔);不配则只有数据目录内的文件可被导入"),
     Opt("FOXCLAW_API_KEY", "str", "", "服务",
@@ -127,7 +120,6 @@ SPECS: tuple[Opt, ...] = (
     Opt("FOXCLAW_STREAM_RATE", "int", 60, "服务", "流式端点每分钟上限", lo=0),
     Opt("FOXCLAW_STREAM_CONCURRENCY", "int", 4, "服务", "流式并发上限", lo=1),
     Opt("FOXCLAW_SHADOW_ROUNDS", "int", 20, "服务", "影子推演轮数", lo=1),
-    # ── 工具 / 追踪 ─────────────────────────────────────────────────────────
     Opt("FOXCLAW_TOOL_TIMEOUT", "float", 45.0, "工具",
         "单个工具调用硬超时(秒);可小于 1(测试用),调用点会兜 >0"),
     Opt("FOXCLAW_TRACE_SLOW_MS", "float", 1000.0, "追踪", "超过多少毫秒算慢请求", lo=0),
@@ -135,12 +127,10 @@ SPECS: tuple[Opt, ...] = (
         "非慢请求的采样率 0~1;超出范围由调用点 clamp,不在这里报错"),
     Opt("FOXCLAW_TRACE_RETAIN", "int", 5000, "追踪",
         "内存里保留的 trace 条数;调用点已有 max(100, ...) 兜底"),
-    # ── 搜索 ────────────────────────────────────────────────────────────────
     Opt("BAIDU_SEARCH_KEY", "str", "", "搜索", "百度 AI 搜索的 key", secret=True),
     Opt("BAIDU_SEARCH_MODEL", "str", "", "搜索", "百度搜索用的模型名"),
     Opt("BAIDU_SEARCH_BASE", "str", "", "搜索", "百度搜索的 base_url"),
     Opt("BAIDU_SEARCH_TIMEOUT", "int", 45, "搜索", "秒;调用点已有 max(5, ...) 兜底"),
-    # ── 渠道 ────────────────────────────────────────────────────────────────
     Opt("FOXCLAW_CHANNEL_TRUSTED_SENDERS", "csv", "", "渠道",
         "逗号分隔的可信发送者:<id> / <channel>:<id> / <channel>:*"),
     Opt("FOXCLAW_CHANNEL_TRUST_ALL", "str", "", "渠道",
@@ -148,27 +138,24 @@ SPECS: tuple[Opt, ...] = (
     Opt("FOXCLAW_CHANNEL_SIGNING_SECRET", "str", "", "渠道",
         "出站 HMAC 密钥;留空 = 不签", secret=True),
     Opt("FOXCLAW_CHANNEL_SIGNING_KEY_ID", "str", "", "渠道", "密钥轮换标识"),
-    # ── 浏览器 ──────────────────────────────────────────────────────────────
     Opt("FOXCLAW_BROWSER_ALLOW_PRIVATE", "str", "", "浏览器",
         "1/true/yes 才允许访问内网地址"),
 )
 
 SPEC_BY_NAME: dict[str, Opt] = {o.name: o for o in SPECS}
 
-# 会在启动/运行早期被读、且类型写错就会崩的少数几个 —— 供 serve 预检快速拦截。
 FATAL_CODES = ("type", "choice", "range")
 
 
 @dataclass
 class Issue:
-    level: str                 # "error" | "warn"
-    code: str                  # type / choice / range / provider_key / unknown_key ...
+    level: str
+    code: str
     name: str
     message: str
-    hint: str = ""             # 修复建议(可为空)
+    hint: str = ""
 
     def __str__(self) -> str:
-        # 只用 ASCII 记号:Windows 控制台默认 GBK,✓/✗/⚠ 会抛 UnicodeEncodeError
         mark = "ERROR" if self.level == "error" else " WARN"
         head = f"[{mark}] {self.name}: {self.message}" if self.name else f"[{mark}] {self.message}"
         return f"{head}\n          → {self.hint}" if self.hint else head
@@ -178,7 +165,7 @@ def _caller() -> str:
     """当前 `get_*` 的调用点(文件:行)。只在出错路径上求值,不进热路径。"""
     try:
         f = inspect.currentframe()
-        for _ in range(3):                      # 跳过 get_* → _parse → _caller 自身
+        for _ in range(3):
             if f is None:
                 return ""
             f = f.f_back
@@ -210,16 +197,16 @@ def _parse(opt: Opt, raw: str, where: str = "") -> Any:
         return value
 
     if opt.kind == "choice":
-        value = text.lower()
-        if value not in opt.choices:
+        choice = text.lower()
+        if choice not in opt.choices:
             raise ConfigError(
                 f'值 "{raw}" 不在允许范围内。可选:{" / ".join(opt.choices)}{suffix}')
-        return value
+        return choice
 
     if opt.kind == "csv":
         return [s.strip() for s in text.split(",") if s.strip()]
 
-    return raw                                  # str:保留原样(尾部空格可能有意义,如口令)
+    return raw
 
 
 def _opt(name: str) -> Opt:
@@ -251,7 +238,7 @@ _warned: set[str] = set()
 _log = logging.getLogger("foxclaw.config")
 
 
-def get_safe(name: str, default: Any = None) -> Any:
+def get_safe(name: str, default: Any | None = None) -> Any:
     """可降级的读取:值非法时**退默认值并要求日志警告一次**,不抛异常。
 
     给"配置错不该拖垮主流程"的地方用(trace 采样、工具超时、搜索超时):这些点
@@ -262,12 +249,12 @@ def get_safe(name: str, default: Any = None) -> Any:
     fallback = opt.default if default is None else default
     raw = os.environ.get(name)
     if raw is None or not raw.strip():
-        return fallback                          # 未设置/空串:用调用方给的兜底
+        return fallback
     try:
         return _parse(opt, raw, _caller())
     except ConfigError as e:
         if name not in _warned:
-            _warned.add(name)                    # 只喊一次:tracing 是每请求调用
+            _warned.add(name)
             _log.warning("[config] %s", e)
         return fallback
 
@@ -297,8 +284,6 @@ def known_keys() -> frozenset[str]:
     只在 `check()` / `show()` 这类诊断路径调用,不进请求路径;结果缓存在本进程内。
     """
     pkg = Path(__file__).resolve().parent.parent
-    # vendor/(HKC/HMR)在仓库根,不在包内:它们自己读 HMR_*/HKC_* 变量,不一起扫就会把
-    # 正常配置报成"拼错的键"。wheel 里没有 vendor/ → 扫描自然为空,不影响安装后的行为。
     roots = [pkg] + ([pkg.parent / "vendor"] if (pkg.parent / "vendor").is_dir() else [])
     found: set[str] = set(SPEC_BY_NAME)
     files: list[Path] = []
@@ -308,7 +293,7 @@ def known_keys() -> frozenset[str]:
     for path in files:
         try:
             tree = ast.parse(path.read_text(encoding="utf-8", errors="replace"))
-        except SyntaxError:                      # 语法坏掉的文件留着给 CI 报,这里跳过
+        except SyntaxError:
             continue
         for node in ast.walk(tree):
             if isinstance(node, ast.Call):
@@ -401,7 +386,6 @@ def check(env: Mapping[str, str] | None = None) -> list[Issue]:
         except ConfigError as e:
             code = "choice" if opt.kind == "choice" else (
                 "range" if ("下限" in str(e) or "上限" in str(e)) else "type")
-            # 密钥不回显原值,免得把半截口令打进日志
             msg = str(e)
             if is_secret(opt.name):
                 msg = f"值 {mask(raw)} 不合法(原始值已脱敏)"

package/python/foxclaw/core/shared_write.py

@@ -42,21 +42,12 @@ from typing import Iterable, Optional
 MODE_ENV = "FOXCLAW_SHARED_WRITE_MODE"
 VALID_MODES = ("audit", "warn", "enforce")
 
-# 与写入方无关、任何 Agent 都可写的 facet(设计上就该跨 Agent 共享的东西):
-#   preference     —— 用户偏好:base.py 明确以 shared=True 写入,意在跨会话跨 Agent 生效
-#   truth_pipeline —— 真值管线沉淀(truth_pipeline.py),写入方是 agent_id="system"
 GLOBAL_ALLOWED_FACETS = frozenset({"preference", "truth_pipeline"})
 
-# 各 Agent 的「职责域」允许 facet。facet 取自一次写入的 {type:<记忆类型>} ∪ tags,
-# 支持 fnmatch 通配(如 finance.* 可匹配 finance.budget)。
-#
-# 注意:这是**起始假设**,不是已验证的结论 —— 默认 audit 模式的目的正是用真实流量验证它。
 DEFAULT_SHARED_WRITE_ALLOWED = {
-    "supervisor": {"*"},      # 主管:分发/协调记录,语义上允许任意
-    "system":     {"*"},      # 系统(真值管线、后台任务)
+    "supervisor": {"*"},
+    "system":     {"*"},
     "finance":    {"finance.*"},
-    # 行政并入办公后,办公学习 Agent 同时拥有学习与行程两个写域;
-    # 助手已下放为技能(不再有独立 agent_id),不再单列 ACL 条目。
     "office":     {"learning.*", "itinerary.*", "schedule.*"},
 }
 
@@ -90,8 +81,8 @@ class SharedWritePolicy:
     无状态、无锁、纯函数式判定 —— 并发安全直接成立,也便于单独测试。
     """
 
-    def __init__(self, allowed: dict = None, mode: str = None,
-                 global_facets: Iterable[str] = None):
+    def __init__(self, allowed: dict | None = None, mode: str | None = None,
+                 global_facets: Iterable[str] | None = None):
         self.allowed = {k: set(v) for k, v in
                         (allowed or DEFAULT_SHARED_WRITE_ALLOWED).items()}
         self.global_facets = set(global_facets if global_facets is not None
@@ -99,13 +90,11 @@ class SharedWritePolicy:
         self.mode = self._resolve_mode(mode)
 
     @staticmethod
-    def _resolve_mode(mode: str = None) -> str:
+    def _resolve_mode(mode: str | None = None) -> str:
         """显式入参 > 环境变量 > 默认 audit。非法值一律回落到 audit(保守:不拦截)。"""
         m = (mode or os.environ.get(MODE_ENV, "") or "audit").strip().lower()
         return m if m in VALID_MODES else "audit"
 
-    # 纯标记类 tag:描述"这条记忆的归属/去向",不描述"内容是什么"。
-    # 让它们参与内容域匹配只会稀释策略表 —— 尤其 "shared" 在本闸门语境下恒为真,零信息量。
     _MARKER_TAGS = ("agent:", "shared")
 
     @staticmethod
@@ -126,9 +115,9 @@ class SharedWritePolicy:
             out.append(t)
         return tuple(dict.fromkeys(out))
 
-    def evaluate(self, agent_id: str = None, memory_type: str = "concept",
-                 tags: Iterable[str] = None) -> Decision:
-        facets = self.facets_of(memory_type, tags)
+    def evaluate(self, agent_id: str | None = None, memory_type: str = "concept",
+                 tags: Iterable[str] | None = None) -> Decision:
+        facets = self.facets_of(memory_type, tags or ())
         who = agent_id or "unknown"
 
         if any(fnmatch.fnmatchcase(f, p) for f in facets for p in self.global_facets):
@@ -142,9 +131,9 @@ class SharedWritePolicy:
         return Decision(False, f"{who} 的职责域不含 {list(facets)}", self.mode, facets)
 
 
-def guard_shared_write(backend, agent_id: str, content: str,
+def guard_shared_write(backend, agent_id: str | None, content: str,
                        memory_type: str = "concept",
-                       tags: Iterable[str] = None) -> Optional[Decision]:
+                       tags: Iterable[str] | None = None) -> Optional[Decision]:
     """共享层写入的统一闸门 —— 必须在**真正落库之前**调用。
 
     行为分三档:
@@ -170,7 +159,6 @@ def guard_shared_write(backend, agent_id: str, content: str,
                 "allowed": decision.allowed,
                 "reason": decision.reason,
                 "mode": decision.mode,
-                # 只留摘要哈希 + 短预览,不把共享层正文原样灌进事件流
                 "content_sha": hashlib.sha256(
                     str(content or "").encode("utf-8")).hexdigest()[:16],
                 "content_preview": str(content or "")[:60],
@@ -187,7 +175,7 @@ def guard_shared_write(backend, agent_id: str, content: str,
     return decision
 
 
-def attach(backend, policy: SharedWritePolicy = None, spine=None) -> SharedWritePolicy:
+def attach(backend, policy: SharedWritePolicy | None = None, spine=None) -> SharedWritePolicy:
     """把策略挂到记忆后端(HMRAdapter / MockHMR 皆可)。返回生效的策略实例。
 
     用挂载而非构造函数注入,是因为装配顺序:memory_adapter 在 event_spine **之前**创建,