foxclaw 0.1.2 → 0.1.4

package/python/foxclaw/skills/lifecycle.py

@@ -18,20 +18,20 @@ from collections import deque
 from dataclasses import dataclass
 from typing import Callable, Optional, Literal
 
+from .hooks_spec import HookEvent
 
-# ============ 断路器 ============
 
 CircuitState = Literal["closed", "open", "half_open"]
 
 
 @dataclass
 class _BreakerEntry:
-    failures: int = 0                 # closed 态的连续失败计数
+    failures: int = 0
     state: CircuitState = "closed"
-    opened_at: float = 0.0            # 进入 open 的时刻(用于冷却计时)
-    probe_in_flight: bool = False     # half_open 态:是否已有探针在执行(只放一个)
-    probe_started_at: float = 0.0     # 探针放行的时刻(用于探针超时自愈)
-    probe_successes: int = 0          # half_open 态:已累计的探针成功数
+    opened_at: float = 0.0
+    probe_in_flight: bool = False
+    probe_started_at: float = 0.0
+    probe_successes: int = 0
 
 
 class CircuitBreaker:
@@ -48,10 +48,10 @@ class CircuitBreaker:
                  recovery_threshold: int = 1, probe_timeout: float = 60.0):
         self.threshold = threshold
         self.cooldown = cooldown
-        self.recovery_threshold = max(1, recovery_threshold)  # 恢复需连续成功几次
-        self.probe_timeout = probe_timeout   # 探针超过此时长未记账 → 视为丢失,释放
+        self.recovery_threshold = max(1, recovery_threshold)
+        self.probe_timeout = probe_timeout
         self._entries: dict[str, _BreakerEntry] = {}
-        self._lock = threading.RLock()    # allow/record 可能跨线程,需加锁
+        self._lock = threading.RLock()
 
     def _get(self, sid: str) -> _BreakerEntry:
         if sid not in self._entries:
@@ -71,17 +71,14 @@ class CircuitBreaker:
                 return True
             if e.state == "open":
                 if time.time() - e.opened_at >= self.cooldown:
-                    # 冷却满 → 真正进入 half_open,放行第一个探针
                     e.state = "half_open"
                     e.probe_in_flight = True
                     e.probe_started_at = time.time()
                     e.probe_successes = 0
                     return True
                 return False
-            # half_open:已有探针在飞 → 拒绝其余;否则放行一个新探针
             if e.state == "half_open":
                 if e.probe_in_flight:
-                    # 探针超时未记账(调用方崩溃/漏记)→ 视为丢失,释放以免永久卡死
                     if time.time() - e.probe_started_at >= self.probe_timeout:
                         e.probe_in_flight = False
                     else:
@@ -98,11 +95,9 @@ class CircuitBreaker:
                 e.probe_in_flight = False
                 e.probe_successes += 1
                 if e.probe_successes >= self.recovery_threshold:
-                    # 探针连续成功达标 → 恢复
                     e.state = "closed"
                     e.failures = 0
                     e.probe_successes = 0
-                # 否则保持 half_open,等下一个探针
             else:
                 e.failures = 0
                 e.state = "closed"
@@ -111,7 +106,6 @@ class CircuitBreaker:
         with self._lock:
             e = self._get(sid)
             if e.state == "half_open":
-                # 探针失败 → 回到 open,重新计冷却
                 e.state = "open"
                 e.opened_at = time.time()
                 e.probe_in_flight = False
@@ -126,7 +120,6 @@ class CircuitBreaker:
         with self._lock:
             e = self._get(sid)
             state = e.state
-            # open 但冷却已满 → 对外显示 half_open(下次 allow 会真正转入)
             if e.state == "open" and time.time() - e.opened_at >= self.cooldown:
                 state = "half_open"
             return {"state": state, "failures": e.failures,
@@ -154,20 +147,11 @@ class CircuitBreaker:
             return False
 
 
-# ============ 生命周期钩子 ============
-
-HookEvent = Literal["before_tool_call", "after_tool_call", "on_error", "on_loop",
-                    "session_start", "agent_start", "agent_end", "session_end",
-                    "before_message_write",
-                    # 向后兼容的旧名 + E2 语义别名(内部规整为标准名)
-                    "pre_skill", "post_skill", "pre_reasoning", "task_complete"]
-
-
 @dataclass
 class Hook:
     event: HookEvent
-    matcher: str                 # skill id / glob;'*' 匹配全部
-    handler: Callable            # 宿主提供的处理函数
+    matcher: str
+    handler: Callable
     name: str = ""
 
     def matches(self, skill_id: str) -> bool:
@@ -176,10 +160,10 @@ class Hook:
 
 @dataclass
 class HookResult:
-    blocked: bool = False        # 仅 pre_skill 可阻断
+    blocked: bool = False
     reason: str = ""
     modified_args: Optional[dict] = None
-    additional_context: Optional[str] = None   # E2:CONTEXT_HOOKS(pre_reasoning/agent_start)注入的推理上下文
+    additional_context: Optional[str] = None
 
 
 class HookManager:
@@ -195,18 +179,13 @@ class HookManager:
     def __init__(self, timeout: float = 10.0, audit_limit: int = 2000):
         self.timeout = timeout
         self._hooks: list[Hook] = []
-        # 【深审修复·长期运行泄漏】audit_log 原为普通 list、只增不减:每次 skill invoke 触发
-        # pre/post/error/loop 等钩子都 append,长跑(尤其 V2 管线内 dispatch 高频用工具)无界
-        # 增长 → 内存泄漏(与 TruthCrystallizer._pending 同类)。改有界 deque:保留最近 N 条,
-        # 溢出自动丢弃最老的;deque.append 原子 ⇒ 并发 fire 也线程安全,无需额外锁。
         self.audit_log: deque = deque(maxlen=max(100, audit_limit))
 
     def register(self, event: HookEvent, handler: Callable,
                  matcher: str = "*", name: str = ""):
         from .hooks_spec import normalize_hook, is_valid_hook
-        norm = normalize_hook(event)   # 旧名(pre_skill)→ 标准名(before_tool_call)
+        norm = normalize_hook(event)
         if not is_valid_hook(norm):
-            # 非法钩子名(可能拼写错误)→ 记录警告,避免静默失效难以排查
             self.audit_log.append({
                 "event": event, "hook": name or getattr(handler, "__name__", "?"),
                 "matcher": matcher, "duration_ms": 0, "timed_out": False,
@@ -225,7 +204,6 @@ class HookManager:
         except Exception as e:
             err = str(e)
         dt = time.time() - t0
-        # 超时只记录(同步 hook 无法真正中断,但记录超时供审计)
         timed_out = dt > self.timeout
         self.audit_log.append({
             "event": hook.event, "hook": hook.name, "matcher": hook.matcher,
@@ -234,7 +212,7 @@ class HookManager:
         })
         return {} if err else outcome
 
-    def fire(self, event: HookEvent, skill_id: str = "", ctx: dict = None) -> HookResult:
+    def fire(self, event: HookEvent, skill_id: str = "", ctx: dict | None = None) -> HookResult:
         """触发某事件的所有匹配 hook。仅 before_tool_call(原 pre_skill)的 block 生效;
         CONTEXT_HOOKS(pre_reasoning/agent_start)返回的 additional_context 会被收集拼接。
 
@@ -245,18 +223,16 @@ class HookManager:
         """
         from .hooks_spec import (normalize_hook, BLOCKING_HOOKS, TOOL_SCOPED_HOOKS,
                                  CONTEXT_HOOKS)
-        event = normalize_hook(event)   # 旧名/标准名统一
+        event = normalize_hook(event)
         ctx = dict(ctx or {}, event=event, skill_id=skill_id)
         result = HookResult()
         ctx_parts = []
         for hook in self._hooks:
             if hook.event != event:
                 continue
-            # 工具级钩子按 skill_id 过滤(matcher)
             if event in TOOL_SCOPED_HOOKS and not hook.matches(skill_id):
                 continue
             out = self._run_one(hook, ctx)
-            # 仅有阻断权的钩子(before_tool_call)的 block / modified_args 生效
             if event in BLOCKING_HOOKS:
                 if out.get("block"):
                     result.blocked = True
@@ -264,7 +240,6 @@ class HookManager:
                     return result
                 if out.get("modified_args") is not None:
                     result.modified_args = out["modified_args"]
-            # 可注入上下文的钩子:收集 additional_context(兼容驼峰 additionalContext)
             if event in CONTEXT_HOOKS:
                 inj = out.get("additional_context") or out.get("additionalContext")
                 if inj:
@@ -274,5 +249,4 @@ class HookManager:
         return result
 
     def recent_audit(self, n: int = 20) -> list:
-        # deque 不支持负索引切片,先快照成 list(原子快照,并发安全)再取尾 N 条
         return list(self.audit_log)[-n:]

package/python/foxclaw/skills/markdown_skill.py

@@ -4,6 +4,7 @@ import re
 import threading
 from dataclasses import dataclass, field, asdict
 import yaml
+from typing import Any
 
 
 @dataclass
@@ -15,11 +16,11 @@ class MarkdownSkill:
     body: str = ""
     enabled: bool = True
     source: str = "user"
-    version: str = ""                                  # OpenClaw 包的版本(_meta.json/frontmatter),可空
-    builtin: bool = False                              # 随包分发的内置技能(repo skills/*/SKILL.md)
+    version: str = ""
+    builtin: bool = False
 
     def to_dict(self) -> dict:
-        d = asdict(self); d["trust"] = "low"; return d   # 指令注入=提示词操纵面,信任=低
+        d = asdict(self); d["trust"] = "low"; return d
 
     def to_meta(self) -> dict:
         d = self.to_dict(); d.pop("body", None); return d
@@ -29,7 +30,7 @@ def _slug(s: str) -> str:
     return re.sub(r"[^a-z0-9]+", "_", (s or "").lower()).strip("_") or "skill"
 
 
-def parse_skill_md(text: str, id: str = None) -> MarkdownSkill:
+def parse_skill_md(text: str, id: str | None = None) -> MarkdownSkill:
     """解析 SKILL.md(--- yaml frontmatter --- + 正文)。缺 name/description → ValueError。"""
     text = (text or "").lstrip("").strip()
     m = re.match(r"^---\s*\n(.*?)\n---\s*\n?(.*)$", text, re.DOTALL)
@@ -65,7 +66,7 @@ def load_builtin_dir(reg: MarkdownSkillRegistry, root) -> list:
     用户已安装的同 id 技能优先(不覆盖),内置只是缺省值。
     """
     from pathlib import Path
-    loaded = []
+    loaded: list[Any] = []
     try:
         base = Path(root)
         if not base.is_dir():
@@ -74,7 +75,7 @@ def load_builtin_dir(reg: MarkdownSkillRegistry, root) -> list:
             try:
                 s = parse_skill_md(p.read_text(encoding="utf-8", errors="replace"))
             except Exception:
-                continue                   # 单个技能坏掉不影响其余
+                continue
             if not s.builtin or reg.get(s.id) is not None:
                 continue
             reg.register(s)
@@ -88,7 +89,7 @@ class MarkdownSkillRegistry:
     def __init__(self):
         self._skills = {}
         self._lock = threading.RLock()
-        self.policy = None                     # 全局封杀策略(宿主注入);被封的不参与注入
+        self.policy = None
 
     def register(self, s: MarkdownSkill):
         with self._lock:
@@ -119,7 +120,7 @@ class MarkdownSkillRegistry:
             if not s.enabled:
                 continue
             if pol is not None and pol.is_blocked(s.id):
-                continue                       # 被封杀 → 不注入(kill-switch)
+                continue
             if s.triggers:
                 if any(k.lower() in t_low for k in s.triggers):
                     out.append(s)
@@ -164,7 +165,7 @@ def extract_skill_package(zip_bytes: bytes, max_uncompressed: int = 2_000_000):
     if not skill_name:
         raise ValueError("包内未找到 SKILL.md")
     skill_md = zf.read(skill_name).decode("utf-8", "replace")
-    meta = {}
+    meta: dict[str, Any] = {}
     meta_name = next((n for n in zf.namelist() if n.lower().endswith("_meta.json")), None)
     if meta_name:
         try:

package/python/foxclaw/skills/mcp_client.py

@@ -11,7 +11,6 @@ from mcp.client.streamable_http import streamablehttp_client
 from mcp.client.sse import sse_client
 
 
-# ── async→sync 桥:单例后台 loop 线程 ──────────────────────────
 class _Bridge:
     def __init__(self):
         self._loop = asyncio.new_event_loop()
@@ -27,7 +26,7 @@ class _Bridge:
         try:
             return fut.result(timeout=timeout)
         except BaseException:
-            fut.cancel()   # 超时/异常必须取消协程,否则挂起的连接会一直留在 loop 里泄漏
+            fut.cancel()
             raise
 
 
@@ -43,7 +42,6 @@ def _get_bridge() -> _Bridge:
         return _bridge
 
 
-# ── SSRF 防线:连接(含重定向的每一跳)都校验目标 host 不是内网/本地/元数据 ──────
 async def _ssrf_request_hook(request):
     """httpx 请求钩子:对每个即将发出的请求(初始 + 重定向 follow-up)校验 host。
     堵 redirect-SSRF + DNS 重绑定 + 配置漂移(恶意 server 把你导去内网/云元数据)。"""
@@ -59,12 +57,11 @@ def _safe_httpx_factory(headers=None, timeout=None, auth=None):
         headers=headers,
         timeout=timeout if timeout is not None else httpx.Timeout(30.0),
         auth=auth,
-        follow_redirects=True,                          # 允许(合法同源尾斜杠跳转),但每跳过钩子
+        follow_redirects=True,
         event_hooks={"request": [_ssrf_request_hook]},
     )
 
 
-# ── 底层 async 助手(测试可 monkeypatch 这两个) ─────────────────
 @asynccontextmanager
 async def _connect(url, headers, transport):
     if transport == "sse":
@@ -98,14 +95,13 @@ def _norm(cfg: dict) -> dict:
             "transport": cfg.get("transport") or "streamable_http"}
 
 
-# ── 工具 → SkillSpec(fail-closed) ─────────────────────────────
 def _get(tool, key, default=None):
     """兼容 dict(守门人序列化后) 与 mcp.types.Tool 对象(直连回退路径)。"""
     return tool.get(key, default) if isinstance(tool, dict) else getattr(tool, key, default)
 
 
 def tool_to_spec(server_id: str, tool):
-    from . import SkillSpec
+    from . import SideEffect, SkillSpec
     ann = _get(tool, "annotations", None)
     if isinstance(ann, dict):
         ro = ann.get("readOnlyHint")
@@ -113,12 +109,13 @@ def tool_to_spec(server_id: str, tool):
     else:
         ro = getattr(ann, "readOnlyHint", None) if ann else None
         de = getattr(ann, "destructiveHint", None) if ann else None
+    se: SideEffect
     if ro is True:
         se, destr = "read", False
     elif de is True:
         se, destr = "write", True
     else:
-        se, destr = "write", False          # fail-closed:无注解按有副作用
+        se, destr = "write", False
     tname = _get(tool, "name", "") or ""
     return SkillSpec(
         id=f"mcp__{server_id}__{tname}", name=tname,
@@ -129,7 +126,6 @@ def tool_to_spec(server_id: str, tool):
     )
 
 
-# ── 供 SkillAdapter 的客户端代理 ──────────────────────────────
 class _ClientProxy:
     def __init__(self, mgr, sid):
         self._mgr, self._sid = mgr, sid
@@ -140,8 +136,6 @@ class _ClientProxy:
             raise RuntimeError(f"MCP server {self._sid} 未登记")
         from foxclaw.core.tracing import span as _span, current_traceparent
         with _span("mcp.call_tool", server=self._sid, tool=str(tool)):
-            # 跨进程传播:带上 W3C traceparent,对端(外部 MCP server)若支持即可接上同一条链。
-            # 这是 Foxclaw 唯一真实的跨进程边界,也是"分布式追踪"在本系统里唯一有意义之处。
             headers = dict(cfg["headers"] or {})
             tp = current_traceparent()
             if tp:

package/python/foxclaw/skills/mcp_store.py

@@ -28,9 +28,6 @@ class McpStore:
     def save(self, servers: list):
         with self._lock:
             try:
-                # 【P-Muse·第4步】守门人模式下主进程只存元数据(headers 为空),正常不触发。
-                # 一旦有 headers 非空,说明走的是回退路径(或误传凭证)——明文凭证即将落盘,
-                # 主动告警,消除"凭证静默落盘、重启后才暴露"的隐患。
                 if any(dict(s.get("headers") or {}) for s in servers):
                     print("[McpStore] ⚠ 检测到 headers 凭证,将明文落盘到 "
                           f"{self._path.name}(当前为回退路径/未启用守门人)。",

package/python/foxclaw/skills/permission.py

@@ -16,25 +16,20 @@ from typing import Literal, Optional
 
 Decision = Literal["allow", "ask", "deny"]
 
-# 【P5-1】ask 的结构化原因码。此前 ask + requires_confirmation=True 只有一个语义:
-# 「用户确认后就能执行」。但 Stage 1 的「缺参数」不是「需确认」——用户确认一百次
-# 也补不上参数,必须先补数据。reason_code 让调用方(前端/编排层/审计)能区分:
-MISSING_PARAMS = "MISSING_PARAMS"                # 缺必填参数,不可通过确认绕过(先补数据)
-DESTRUCTIVE_CONFIRM = "DESTRUCTIVE_CONFIRM"      # 不可逆操作,需确认
-SIDE_EFFECT_CONFIRM = "SIDE_EFFECT_CONFIRM"      # write/send/pay 副作用,需确认
-ASK_RULE = "ASK_RULE"                            # 命中宿主 ask 规则
-EXTERNAL_CONFIRM = "EXTERNAL_CONFIRM"            # 外部调用,需确认
-TAINT_CONFIRM = "TAINT_CONFIRM"                  # 会话已取回敏感数据,外发/副作用须二次确认
-# deny / allow 侧文稿未定义 code,保守留 "":deny 的铁律语义(deny 不可覆盖)已由
-# decision + stage 充分表达,不擅自扩大枚举面。
+MISSING_PARAMS = "MISSING_PARAMS"
+DESTRUCTIVE_CONFIRM = "DESTRUCTIVE_CONFIRM"
+SIDE_EFFECT_CONFIRM = "SIDE_EFFECT_CONFIRM"
+ASK_RULE = "ASK_RULE"
+EXTERNAL_CONFIRM = "EXTERNAL_CONFIRM"
+TAINT_CONFIRM = "TAINT_CONFIRM"
 
 
 @dataclass
 class PermissionRules:
     """宿主提供的规则集。deny 优先级最高且不可覆盖。"""
-    deny: list = field(default_factory=list)    # skill id / glob,命中即拒绝
-    ask: list = field(default_factory=list)     # 命中需确认
-    allow: list = field(default_factory=list)   # 命中放行
+    deny: list = field(default_factory=list)
+    ask: list = field(default_factory=list)
+    allow: list = field(default_factory=list)
 
     @staticmethod
     def _match(patterns: list, skill_id: str) -> bool:
@@ -54,11 +49,10 @@ class PermissionRules:
 @dataclass
 class PermissionDecision:
     decision: Decision
-    stage: int                  # 哪个阶段做出的决定(1-4)
+    stage: int
     reason: str = ""
-    trust_downgrade: bool = False   # 结果是否须按「不可信」处理(MCP/远程)
+    trust_downgrade: bool = False
     requires_confirmation: bool = False
-    # 【P5-1】ask 的结构化原因码(见模块顶部常量);非 ask 或文稿未定义的情形为 ""
     reason_code: str = ""
 
     def to_dict(self) -> dict:
@@ -85,9 +79,6 @@ def evaluate(skill, args: dict, rules: Optional[PermissionRules] = None,
     rules = rules or PermissionRules()
     sid = skill.id
 
-    # ---------- Stage 1: validate(输入合法性)----------
-    # 参数 schema 基本校验:声明的必填参数是否齐全
-    # 兼容两种 params 格式:{"k": "str"}(简单)或 {"k": {"required": True}}(详细)
     params = getattr(skill, "params", {}) or {}
     missing = []
     for k, spec in params.items():
@@ -95,59 +86,37 @@ def evaluate(skill, args: dict, rules: Optional[PermissionRules] = None,
         if required and k not in (args or {}):
             missing.append(k)
     if missing:
-        # 校验失败 → 优雅降级为 ask(不是安全拒绝,是数据不全)
-        # 【P5-1】MISSING_PARAMS:确认无法绕过缺参数,调用方须先补数据
         return PermissionDecision("ask", 1,
             reason=f"缺少必填参数: {', '.join(missing)}",
             requires_confirmation=True, reason_code=MISSING_PARAMS)
 
-    # ---------- Stage 2: rule-match(deny > ask > allow 铁律)----------
     if rules.hits_deny(sid):
         return PermissionDecision("deny", 2, reason=f"命中 deny 规则(不可覆盖): {sid}")
     ask_by_rule = rules.hits_ask(sid)
     allow_by_rule = rules.hits_allow(sid)
-    # deny 不命中时,ask 优先于 allow
 
-    # ---------- Stage 3: capability(能力检查,Fail-closed)----------
-    side_effect = getattr(skill, "side_effect", "write")    # 未声明 → 按有副作用(fail-closed)
+    side_effect = getattr(skill, "side_effect", "write")
     destructive = getattr(skill, "destructive", False)
     external = getattr(skill, "external", False)
-    # read_only 字段默认 None → 按 side_effect 推断(read 即只读);显式 True/False 则尊重
     _ro = getattr(skill, "read_only", None)
     read_only = (side_effect == "read") if _ro is None else _ro
-    # 单一真源(P6 修复):信任分级由 SkillSpec.trust_level() 唯一裁定。此前 permission 另存一份
-    # TRUST_LEVEL dict,与 trust_level() 重复且含死 key(bundled/remote —— kind 永不取此二值);对 3 个
-    # 合法 SkillKind(local/web_api/mcp)二者 downgrade 行为完全一致,故收敛为单一真源、行为不变。
-    # duck-typed skill 无 trust_level 方法时 fail-closed 当低信任。
-    # 【P5-0】trust_level() 抛异常 → 当低信任(fail-closed),不让权限管线崩。
-    # 第三方 skill 的 trust_level() 若有 bug(如 AttributeError),原实现会让异常直接冒泡、
-    # evaluate 崩溃,用户看到「调用失败」而非「权限拒绝」——这是 fail-open。改为兜住异常、
-    # 按最低信任(low)处理:无法判定信任等级时,宁可保守。
     _tl = getattr(skill, "trust_level", None)
     try:
         trust = _tl() if callable(_tl) else "low"
     except Exception:
         trust = "low"
-    downgrade = trust == "low"   # 低信任(mcp/远程)结果须按不可信处理
+    downgrade = trust == "low"
 
-    # readonly 模式:非只读一律拒绝
     if mode == "readonly" and not read_only:
         return PermissionDecision("deny", 3,
             reason="readonly 模式下禁止非只读操作", trust_downgrade=downgrade)
 
-    # destructive 永不自动放行(即使有 allow 规则也要确认)
     if destructive and not confirmed:
         return PermissionDecision("ask", 3,
             reason="不可逆(destructive)操作,必须用户确认",
             trust_downgrade=downgrade, requires_confirmation=True,
             reason_code=DESTRUCTIVE_CONFIRM)
 
-    # Stage 3.5 污点门槛(Muse 式「碰过敏感数据 → 外发动作追加确认」):
-    # 会话已取回 ≥threshold 的用户数据,再外发/副作用 → 即使工具本身可信也强制确认,
-    # 防「模型把用户隐私塞进 send/write/external」外泄。置于 trusted 之前:
-    # 污点是结构性约束,trusted 只信任工具本身,不豁免「携带敏感数据外发」。
-    # [P-Muse·确认放行] `not confirmed`:此闸防的是**静默**外发,用户显式确认后必须放行,
-    # 否则「问一次 → 确认 → 再问一次」永远出不去(与上方 destructive 的判定口径一致)。
     if taint_threshold and taint_level >= taint_threshold and not confirmed:
         if side_effect in ("write", "send", "pay") or external:
             return PermissionDecision("ask", 3,
@@ -155,26 +124,22 @@ def evaluate(skill, args: dict, rules: Optional[PermissionRules] = None,
                 trust_downgrade=downgrade, requires_confirmation=True,
                 reason_code=TAINT_CONFIRM)
 
-    # trusted 模式:跳过 ask,只保留 deny(上面已查)+ destructive(上面已查)
     if mode == "trusted":
         return PermissionDecision("allow", 3,
             reason="trusted 模式放行", trust_downgrade=downgrade)
 
-    # ---------- Stage 4: confirm(确认)----------
     needs_confirm = (
         ask_by_rule or external or side_effect in ("write", "send", "pay")
     )
     if needs_confirm and not confirmed:
         why = ("命中 ask 规则" if ask_by_rule else
                "外部调用" if external else f"{side_effect} 副作用")
-        # 【P5-1】三个分支各自的结构化原因码
         code = (ASK_RULE if ask_by_rule else
                 EXTERNAL_CONFIRM if external else SIDE_EFFECT_CONFIRM)
         return PermissionDecision("ask", 4,
             reason=f"需确认: {why}", trust_downgrade=downgrade,
             requires_confirmation=True, reason_code=code)
 
-    # 放行:显式 allow 规则,或只读无副作用,或已确认
     reason = ("命中 allow 规则" if allow_by_rule else
               "只读无副作用" if read_only else "已确认")
     return PermissionDecision("allow", 4, reason=reason, trust_downgrade=downgrade)