foxclaw 0.1.0 → 0.1.3

package/python/foxclaw/skills/permission.py

@@ -0,0 +1,145 @@
+"""
+工具权限管线 (Permission Pipeline) —— HHS 标准 skill-guard 的代码落地。
+
+把抽象的「四阶段权限管线」实现为可运行代码:
+  Stage 1 validate    —— 输入合法性(参数 schema)
+  Stage 2 rule-match  —— deny > ask > allow 优先级铁律
+  Stage 3 capability  —— read_only / destructive / external,Fail-closed
+  Stage 4 confirm      —— 有副作用/危险操作需确认
+
+对应 docs/internal/HARNESS_STANDARD.md 的 A 类工具权限护栏。
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Literal, Optional
+
+
+Decision = Literal["allow", "ask", "deny"]
+
+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)
+    ask: list = field(default_factory=list)
+    allow: list = field(default_factory=list)
+
+    @staticmethod
+    def _match(patterns: list, skill_id: str) -> bool:
+        import fnmatch
+        return any(fnmatch.fnmatch(skill_id, p) for p in patterns)
+
+    def hits_deny(self, sid: str) -> bool:
+        return self._match(self.deny, sid)
+
+    def hits_ask(self, sid: str) -> bool:
+        return self._match(self.ask, sid)
+
+    def hits_allow(self, sid: str) -> bool:
+        return self._match(self.allow, sid)
+
+
+@dataclass
+class PermissionDecision:
+    decision: Decision
+    stage: int
+    reason: str = ""
+    trust_downgrade: bool = False
+    requires_confirmation: bool = False
+    reason_code: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "decision": self.decision, "stage": self.stage, "reason": self.reason,
+            "trust_downgrade": self.trust_downgrade,
+            "requires_confirmation": self.requires_confirmation,
+            "reason_code": self.reason_code,
+        }
+
+
+def evaluate(skill, args: dict, rules: Optional[PermissionRules] = None,
+             confirmed: bool = False, mode: str = "strict",
+             taint_level: int = 0, taint_threshold: int = 0) -> PermissionDecision:
+    """四阶段权限管线。返回 allow / ask / deny。
+
+    skill: SkillSpec(需有 id / side_effect / kind,及可选 destructive/external/read_only)
+
+    【P-Muse·污点门槛】taint_level = 本会话已取回数据的最高敏感度(见
+    core.injection_guard.taint_level);taint_threshold = 触发二次确认的阈值。
+    两者默认 0 = 关闭,既有调用方行为逐字不变。仅当「污点达标 且 动作为外发/副作用」时,
+    在 Stage 3 强制升级为 ask(TAINT_CONFIRM)——对齐 Muse「碰过敏感数据 → 动态提门槛」。
+    """
+    rules = rules or PermissionRules()
+    sid = skill.id
+
+    params = getattr(skill, "params", {}) or {}
+    missing = []
+    for k, spec in params.items():
+        required = isinstance(spec, dict) and spec.get("required")
+        if required and k not in (args or {}):
+            missing.append(k)
+    if missing:
+        return PermissionDecision("ask", 1,
+            reason=f"缺少必填参数: {', '.join(missing)}",
+            requires_confirmation=True, reason_code=MISSING_PARAMS)
+
+    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)
+
+    side_effect = getattr(skill, "side_effect", "write")
+    destructive = getattr(skill, "destructive", False)
+    external = getattr(skill, "external", False)
+    _ro = getattr(skill, "read_only", None)
+    read_only = (side_effect == "read") if _ro is None else _ro
+    _tl = getattr(skill, "trust_level", None)
+    try:
+        trust = _tl() if callable(_tl) else "low"
+    except Exception:
+        trust = "low"
+    downgrade = trust == "low"
+
+    if mode == "readonly" and not read_only:
+        return PermissionDecision("deny", 3,
+            reason="readonly 模式下禁止非只读操作", trust_downgrade=downgrade)
+
+    if destructive and not confirmed:
+        return PermissionDecision("ask", 3,
+            reason="不可逆(destructive)操作,必须用户确认",
+            trust_downgrade=downgrade, requires_confirmation=True,
+            reason_code=DESTRUCTIVE_CONFIRM)
+
+    if taint_threshold and taint_level >= taint_threshold and not confirmed:
+        if side_effect in ("write", "send", "pay") or external:
+            return PermissionDecision("ask", 3,
+                reason="会话已取回用户敏感数据,外发/副作用动作需二次确认(污点防护)",
+                trust_downgrade=downgrade, requires_confirmation=True,
+                reason_code=TAINT_CONFIRM)
+
+    if mode == "trusted":
+        return PermissionDecision("allow", 3,
+            reason="trusted 模式放行", trust_downgrade=downgrade)
+
+    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} 副作用")
+        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)
+
+    reason = ("命中 allow 规则" if allow_by_rule else
+              "只读无副作用" if read_only else "已确认")
+    return PermissionDecision("allow", 4, reason=reason, trust_downgrade=downgrade)

package/python/foxclaw/skills/pipeline.py

@@ -0,0 +1,354 @@
+"""
+AHS 执行链 (Execution Pipeline) —— Agent Harness Skills 标准的全面落地。
+
+把 6 个元 skill 串成一条可运行的执行链:
+
+  task → [router 选主skill] → 复杂? → [planner 拆解]
+                                    → [composition 编排多skill]
+       每步 skill 执行都过 [guard 权限] + [breaker 断路] + [hooks 钩子]
+       全程 IO 遵循 [execution-contract],结果可审计
+
+router / planner / composition 在这里实现;guard / breaker / hooks 复用
+permission.py + lifecycle.py;contract 复用 SkillResult。
+"""
+from __future__ import annotations
+import asyncio
+import inspect
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+from ..planning import planner as P
+
+
+@dataclass
+class RouteResult:
+    primary: Optional[str] = None
+    confidence: float = 0.0
+    candidates: list = field(default_factory=list)
+    fallback: Optional[str] = None
+    needs_composition: bool = False
+    reason: str = ""
+
+
+def route(task: str, registry, fallback_id: str | None = None) -> RouteResult:
+    """skill-router:把 skill 适配成通用候选,交统一引擎 trigger_route 打分选择。
+    算法(否定过滤触发命中 0.8 + 描述领域匹配 0.2)现由 foxclaw.planning 单一真源提供。"""
+    skills = registry.all()
+    if not skills:
+        return RouteResult(reason="注册表为空")
+    cands = [P.ScoredCandidate(
+                id=s.id,
+                triggers=getattr(s, "triggers", []) or [],
+                description=getattr(s, "description", "") or "")
+             for s in skills]
+    r = P.trigger_route(task, cands, fallback_id=fallback_id)
+    return RouteResult(primary=r.primary, confidence=r.confidence,
+                       candidates=r.candidates, fallback=r.fallback,
+                       needs_composition=r.needs_composition, reason=r.reason)
+
+
+@dataclass
+class PlanTask:
+    id: str
+    name: str
+    suggested_skill: Optional[str] = None
+    dependencies: list = field(default_factory=list)
+
+
+@dataclass
+class Plan:
+    intent: str
+    tasks: list = field(default_factory=list)
+    flow_type: str = "sequential"
+    steps: list = field(default_factory=list)
+    needs_input: bool = False
+    missing: list = field(default_factory=list)
+
+
+def plan(task: str, registry) -> Plan:
+    """planner:把任务拆成结构化计划。拆分/并行标记与算法由 foxclaw.planning 单一真源提供。
+
+    - 含并行连接词(同时/分别/并行)→ 拆成**无依赖**子任务,flow_type=parallel;
+    - 含顺序连接词(然后/接着…)→ 拆成**线性依赖链**,flow_type=sequential;
+    - 都没有 → 单步。
+    依赖关系决定能否并行:parallel 的子任务 dependencies 为空,sequential 的链式依赖前一步。
+    """
+    task = (task or "").strip()
+    if not task:
+        return Plan(intent="", needs_input=True, missing=["task"])
+
+    if any(k in task for k in P.PARALLEL_TRIGGERS):
+        parts = P.split_on(task, P.PARALLEL_TRIGGERS + P.LIST_SEPS)
+        flow = "parallel" if len(parts) > 1 else "sequential"
+    else:
+        parts = P.split_on(task, P.SPLIT_MARKERS)
+        flow = "sequential"
+    if len(parts) <= 1:
+        parts, flow = [task], "sequential"
+
+    tasks, steps = [], []
+    for i, p in enumerate(parts, 1):
+        r = route(p, registry)
+        tid = f"T{i}"
+        deps = [f"T{i-1}"] if (i > 1 and flow == "sequential") else []
+        tasks.append(PlanTask(id=tid, name=p, suggested_skill=r.primary,
+                              dependencies=deps))
+        steps.append(tid)
+
+    return Plan(intent=task, tasks=tasks, flow_type=flow, steps=steps)
+
+
+@dataclass
+class StageResult:
+    stage: int
+    skill_id: str
+    result: dict
+
+
+@dataclass
+class CompositionResult:
+    mode: str
+    stages: list = field(default_factory=list)
+    final_output: dict = field(default_factory=dict)
+    failed: list = field(default_factory=list)
+    rolled_back: bool = False
+    rollback_clean: bool = True
+    rollback_log: list = field(default_factory=list)
+    needs_manual: list = field(default_factory=list)
+    pending_confirmation: Optional[dict] = None
+    completed_steps: list = field(default_factory=list)
+
+    @property
+    def is_pending(self) -> bool:
+        """【P2-2】是否处于待确认暂停态。"""
+        return self.pending_confirmation is not None
+
+    @property
+    def is_failed(self) -> bool:
+        return bool(self.failed)
+
+
+def _build_args(skill, task_text: str, upstream: dict) -> dict:
+    """把任务文本映射到 skill 声明的参数。
+
+    简化策略:单参数 skill → 把任务文本(或提取的算式)塞给那个参数;
+    多参数 skill → 交给 skill 自己解析(传 task + upstream)。
+    真实系统里这一步由 LLM 做参数抽取;此处做轻量映射保证可运行。
+    """
+    params = skill.params or {}
+    if not params:
+        return {}
+    if "expression" in params:
+        m = re.search(r"[-+*/().\d\s]+", task_text)
+        expr = (m.group(0).strip() if m else task_text)
+        return {"expression": expr or task_text}
+    if len(params) == 1:
+        only = next(iter(params))
+        return {only: task_text}
+    return {"task": task_text, "upstream_outputs": dict(upstream)}
+
+
+def _rollback(executed, registry, res: CompositionResult):
+    """逆序回滚已执行且有副作用的步骤。
+
+    executed: [(skill_id, output)] 按执行顺序。
+    只回滚有副作用(非只读)的;有 compensate 的调用补偿,无的标记需人工处理。
+    """
+    res.rolled_back = True
+    for sid, output in reversed(executed):
+        skill = registry.get(sid)
+        if skill is None:
+            continue
+        side_effect = getattr(skill, "side_effect", "read")
+        if side_effect == "read":
+            continue
+        comp = getattr(skill, "compensate", None)
+        if comp is not None:
+            try:
+                comp(output)
+                res.rollback_log.append({"skill": sid, "status": "compensated",
+                                         "detail": "已调用补偿动作撤销副作用"})
+            except Exception as e:
+                res.rollback_log.append({"skill": sid, "status": "compensate_failed",
+                                         "detail": f"补偿失败: {e}"})
+                res.rollback_clean = False
+                res.needs_manual.append(sid)
+        else:
+            res.rollback_log.append({"skill": sid, "status": "manual_required",
+                                     "detail": f"{side_effect} 操作无补偿动作,需人工处理"})
+            res.rollback_clean = False
+            res.needs_manual.append(sid)
+
+
+def _invoke(adapter, skill, args: dict, confirmed: bool, confirm_nonce: str):
+    """调 `adapter.invoke`,老 adapter 自动降级为 4 参旧签名。
+
+    测试/第三方 adapter 常只实现 `invoke(skill, args, confirmed=, mode=)`;用签名探测
+    而不是 try/except TypeError —— 后者会把 invoke 内部真正的 TypeError 当"签名不兼容"吞掉。
+    """
+    fn = adapter.invoke
+    try:
+        params = inspect.signature(fn).parameters
+        accepts = ("confirm_nonce" in params
+                   or any(p.kind is p.VAR_KEYWORD for p in params.values()))
+    except (TypeError, ValueError):
+        accepts = False
+    if accepts:
+        return fn(skill, args, confirmed=confirmed, confirm_nonce=confirm_nonce)
+    return fn(skill, args, confirmed=confirmed)
+
+
+def compose(plan_obj: Plan, registry, adapter, confirmed: bool = False,
+            resume_state: dict | None = None) -> CompositionResult:
+    """skill-composition:按计划顺序执行各 skill。
+
+    结束态三种:
+      · success —— 全部成功
+      · pending —— 遇到 needs_confirmation,**暂停(不回滚)**,待用户确认后续跑
+      · failed  —— 遇到 blocked/circuit_open/error/timeout,逆序回滚补偿
+
+    【P2-2】needs_confirmation 不再当失败处理:暂停而非回滚,避免撤销已完成的
+    有效步骤(反例:创建日程已成功、发邮件待确认,旧逻辑会把日程回滚掉)。
+    可选 resume_state(上次 compose 的 pending_confirmation)用于从断点续跑:
+    恢复已完成步骤的 upstream/executed 现场,跳过 resume_at 之前的步骤。
+    """
+    res = CompositionResult(mode=plan_obj.flow_type)
+    upstream = {}
+    executed = []
+
+    resume_at = None
+    if resume_state:
+        for tid, sid, output in resume_state.get("completed_steps", []):
+            upstream[sid] = output
+            executed.append((sid, output))
+            res.completed_steps.append((tid, sid, output))
+        resume_at = resume_state.get("resume_at")
+
+    for i, t in enumerate(plan_obj.tasks, 1):
+        if resume_at:
+            if t.id != resume_at:
+                continue
+            resume_at = None
+        sid = t.suggested_skill
+        if not sid or not registry.get(sid):
+            res.failed.append(t.id); continue
+        skill = registry.get(sid)
+        call_args = _build_args(skill, t.name, upstream)
+        _nonce = (resume_state or {}).get("confirm_nonce", "") or ""
+        out = _invoke(adapter, skill, call_args, confirmed, _nonce)
+        res.stages.append(StageResult(stage=i, skill_id=sid, result=out.to_dict()))
+        if out.success:
+            upstream[sid] = out.output
+            executed.append((sid, out.output))
+            res.completed_steps.append((t.id, sid, out.output))
+        elif out.status == "needs_confirmation":
+            res.pending_confirmation = {
+                "task_id": t.id,
+                "skill_id": sid,
+                "stage": i,
+                "message": out.message,
+                "args": call_args,
+                "completed_steps": list(res.completed_steps),
+                "resume_at": t.id,
+                "confirm_nonce": getattr(out, "confirm_nonce", "") or "",
+                "confirm_expires_at": getattr(out, "confirm_expires_at", 0.0) or 0.0,
+            }
+            res.final_output = {
+                "pending": True,
+                "at": t.id,
+                "completed": [s[0] for s in res.completed_steps],
+            }
+            return res
+        else:
+            res.failed.append(t.id)
+            res.final_output = {"error": out.message, "failed_at": t.id}
+            _rollback(executed, registry, res)
+            return res
+    res.final_output = upstream
+    return res
+
+
+@dataclass
+class PipelineResult:
+    task: str
+    route: dict
+    plan: dict
+    composition: dict
+    success: bool
+    summary: str
+
+    @property
+    def pending_confirmation(self) -> dict | None:
+        """【P2-2】待确认状态(若无则 None)。结构见 compose 的 pending_confirmation。"""
+        return self.composition.get("pending_confirmation")
+
+    @property
+    def is_pending(self) -> bool:
+        """【P2-2】是否处于待确认暂停态(此时 success=False,但语义是"暂停等确认")。"""
+        return self.pending_confirmation is not None
+
+
+class AHSPipeline:
+    """AHS 执行链编排器:一条龙跑通 router→planner→composition,全程过 guard+breaker+hooks。"""
+
+    def __init__(self, registry, adapter):
+        self.registry = registry
+        self.adapter = adapter
+
+    def run(self, task: str, confirmed: bool = False,
+            resume_state: dict | None = None, confirm_nonce: str = "") -> PipelineResult:
+        """同步执行。【P2-2】resume_state 用于从待确认状态断点续跑
+        (传上次返回的 pending_confirmation;确认后调 run(task, confirmed=True, resume_state=...))。
+
+        `confirm_nonce`(关键操作):compose 会把它并进 resume_state 传给 adapter 校验;
+        也可以直接放在 resume_state 里(pending_confirmation 已带出该字段)。
+        """
+        if confirm_nonce:
+            resume_state = {**(resume_state or {}), "confirm_nonce": confirm_nonce}
+        self.adapter.hooks.fire("session_start", "", {"task": task})
+
+        r = route(task, self.registry)
+
+        p = plan(task, self.registry)
+
+        c = compose(p, self.registry, self.adapter,
+                    confirmed=confirmed, resume_state=resume_state)
+
+        self.adapter.hooks.fire("session_end", "", {"task": task})
+
+        success = not c.failed and bool(c.stages) and not c.pending_confirmation
+        if c.pending_confirmation:
+            summary = (f"执行 {len(c.stages)} 步,待确认:"
+                       f"{c.pending_confirmation['skill_id']}")
+        elif c.failed:
+            summary = f"执行 {len(c.stages)} 步,部分失败:{','.join(c.failed)}"
+        else:
+            summary = f"执行 {len(c.stages)} 步,全部成功"
+        return PipelineResult(
+            task=task,
+            route={"primary": r.primary, "confidence": r.confidence,
+                   "needs_composition": r.needs_composition},
+            plan={"intent": p.intent, "steps": p.steps,
+                  "tasks": [{"id": t.id, "name": t.name, "skill": t.suggested_skill}
+                            for t in p.tasks]},
+            composition={"mode": c.mode, "stages": len(c.stages),
+                         "failed": c.failed, "final": c.final_output,
+                         "rolled_back": c.rolled_back, "rollback_clean": c.rollback_clean,
+                         "rollback_log": c.rollback_log, "needs_manual": c.needs_manual,
+                         "pending_confirmation": c.pending_confirmation,
+                         "completed_steps": [s[0] for s in c.completed_steps]},
+            success=success, summary=summary)
+
+    async def run_async(self, task: str, confirmed: bool = False,
+                        resume_state: dict | None = None,
+                        confirm_nonce: str = "") -> PipelineResult:
+        """【P2-1】异步入口:把同步 run 放到线程池,避免阻塞事件循环。
+
+        内部用 asyncio.to_thread 包装,故 run 里的同步 IO(MCP/Web API/本地 handler)
+        不会阻塞调用方的事件循环。async 调用方(如 /api/ahs/run)应调本方法。
+        注意:asyncio.to_thread 会复制当前 contextvars 到子线程(如 skill actor),
+        子线程异常原样抛回 await 处——两者都是想要的行为。
+        """
+        return await asyncio.to_thread(self.run, task, confirmed, resume_state,
+                                       confirm_nonce)

package/python/foxclaw/skills/policy.py

@@ -0,0 +1,74 @@
+"""全局技能策略:deny 封杀 + allow 白名单(治理 kill-switch,借鉴 OpenClaw plugins.deny/allow)。
+deny 压倒一切;allow 非空则只放行白名单内。user 层持久化 <data_dir>/skill_policy.json。
+E1 分层:另有 **policy 层** deny(管理员锁定,env FOXCLAW_POLICY_DENY + <data_dir>/policy.json,与
+user 层物理分开),**不可被运行时 undeny 撤销**;经 core/config.py 的 LayeredConfig 合并(policy∪user)。"""
+from __future__ import annotations
+import json
+import threading
+from pathlib import Path
+
+
+class SkillPolicy:
+    def __init__(self, data_dir):
+        self._path = Path(data_dir) / "skill_policy.json"
+        self._lock = threading.RLock()
+        self._deny: set = set()
+        self._allow: set = set()
+        from ..core.config import LayeredConfig, load_policy_layer
+        policy_layer = load_policy_layer(data_dir)
+        self._layers = LayeredConfig(policy=policy_layer, user={"deny": self._deny})
+        self._load()
+
+    def is_blocked(self, skill_id: str) -> bool:
+        with self._lock:
+            if skill_id in self._layers.merged_set("deny"):
+                return True
+            if self._allow and skill_id not in self._allow:
+                return True
+            return False
+
+    def deny(self, skill_id: str):
+        with self._lock:
+            self._deny.add(skill_id)
+        self._save()
+
+    def undeny(self, skill_id: str) -> bool:
+        with self._lock:
+            if skill_id in self._layers.policy_locked("deny"):
+                return False
+            existed = skill_id in self._deny
+            self._deny.discard(skill_id)
+        self._save()
+        return existed
+
+    def set_allow(self, ids):
+        with self._lock:
+            self._allow = set(ids or [])
+        self._save()
+
+    def snapshot(self) -> dict:
+        with self._lock:
+            return {"deny": sorted(self._deny), "allow": sorted(self._allow),
+                    "policy_deny": sorted(self._layers.policy_locked("deny"))}
+
+    def _load(self):
+        if not self._path.exists():
+            return
+        try:
+            d = json.loads(self._path.read_text(encoding="utf-8"))
+            self._deny.clear()
+            self._deny.update(d.get("deny") or [])
+            self._allow = set(d.get("allow") or [])
+        except Exception:
+            pass
+
+    def _save(self):
+        with self._lock:
+            payload = {"deny": sorted(self._deny), "allow": sorted(self._allow)}
+        try:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            tmp = self._path.with_suffix(".tmp")
+            tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=1), encoding="utf-8")
+            tmp.replace(self._path)
+        except Exception:
+            pass

package/python/foxclaw/skills/review.py

@@ -0,0 +1,72 @@
+"""安装审核门:技能注册前的治理审核(对齐 OpenClaw security.installPolicy)。
+非杀毒——远程 URL 无法扫描;做 SSRF 预检/域名黑名单/明文告警/副作用与信任提示,
+产出 allow|warn|deny,风险项要求用户显式确认。"""
+from __future__ import annotations
+import os
+import ipaddress
+import socket
+from urllib.parse import urlparse
+
+
+def _host_deny() -> set:
+    return {h.strip().lower() for h in os.environ.get("FOXCLAW_SKILL_HOST_DENY", "").split(",") if h.strip()}
+
+
+def _is_internal_host(host: str) -> bool:
+    if not host:
+        return True
+    if host.lower() == "localhost":
+        return True
+    try:
+        infos = socket.getaddrinfo(host, None)
+    except Exception:
+        return False
+    for info in infos:
+        try:
+            addr = ipaddress.ip_address(info[4][0])
+        except ValueError:
+            continue
+        if addr.is_private or addr.is_loopback or addr.is_link_local or addr.is_reserved:
+            return True
+        if str(addr) == "169.254.169.254":
+            return True
+    return False
+
+
+def review_install(spec) -> dict:
+    """返回 {verdict: allow|warn|deny, reasons: [...], warnings: [...]}。"""
+    reasons, warnings = [], []
+    if spec.kind == "web_api":
+        host = (urlparse(spec.endpoint).hostname or "").lower()
+        if host in _host_deny():
+            reasons.append(f"域名 {host} 在黑名单")
+        if not spec.allow_local and _is_internal_host(host):
+            reasons.append(f"endpoint 指向内网/本地/元数据地址({host or '?'}),已拦截(SSRF)")
+        if spec.endpoint.startswith("http://"):
+            warnings.append("使用明文 HTTP,传输不加密")
+    if spec.kind == "mcp":
+        warnings.append("MCP 来源为外部低信任,其返回内容不应被当作指令执行")
+    if spec.side_effect in ("write", "send", "pay") or spec.destructive:
+        warnings.append(f"该技能有副作用({spec.side_effect}{'/不可逆' if spec.destructive else ''}),会真实影响外部")
+    if reasons:
+        return {"verdict": "deny", "reasons": reasons, "warnings": warnings}
+    if warnings:
+        return {"verdict": "warn", "reasons": [], "warnings": warnings}
+    return {"verdict": "allow", "reasons": [], "warnings": []}
+
+
+def review_mcp_server(url: str) -> dict:
+    """MCP server 接入审核。外部低信任 → 恒 warn(需确认);内网/元数据/黑名单 → deny。"""
+    from urllib.parse import urlparse
+    reasons, warnings = [], []
+    host = (urlparse(url).hostname or "").lower()
+    if host in _host_deny():
+        reasons.append(f"域名 {host} 在黑名单")
+    if _is_internal_host(host):
+        reasons.append(f"MCP url 指向内网/本地/元数据地址({host or '?'}),已拦截(SSRF)")
+    if url.startswith("http://"):
+        warnings.append("使用明文 HTTP,传输不加密")
+    warnings.append("接入外部 MCP server,其返回内容为外部不可信数据,不应被当作指令执行")
+    if reasons:
+        return {"verdict": "deny", "reasons": reasons, "warnings": warnings}
+    return {"verdict": "warn", "reasons": [], "warnings": warnings}