xg-cli 1.0__py3-none-any.whl

xg/router/postprocess.py

@@ -0,0 +1,167 @@
+"""SmartRouter 后处理规则引擎（可解释的安全兜底）。
+
+规则与执行顺序来源：XG-docs/smart-docs/ADAPTIVE_ROUTING.md §7（1→6，先升后降、最后防降级）。
+
+与文档代码的一处有意差异：防降级规则按注释意图实现为
+``t = max(t, prev_tier - 1)``（600s 内最多比上一轮低 1 档）。
+文档示例代码的 ``t = min(t, prev_tier + 1)`` 实际限制的是"上升"，
+与其注释"不能比上一轮低超过 1 档"矛盾，此处以注释语义为准。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .features import code_blocks
+from .keywords import KEYWORDS
+
+TIER = ["Basic", "Enhanced", "Superior", "Ultimate"]
+
+# 防降级窗口（秒）：同会话内两次路由间隔小于该值时，档位最多下降 1 档
+ANTI_DOWNGRADE_WINDOW = 600
+# 迟滞窗口（秒，phase-04 A2）：窗口内档位变化超过 max_changes 次即冻结当前档
+HYSTERESIS_WINDOW = 60
+
+
+@dataclass
+class Hysteresis:
+    """会话内迟滞状态（稳定层，phase-04 A2）。
+
+    防短时震荡：同一会话窗口内档位变化超过 ``max_changes`` 次即冻结当前档，
+    直到窗口过期或命中硬规则（``forced``）才解冻。与 600s 防降级叠加复用，
+    但语义不同——防降级只限制"下降不能太快"，迟滞是"上下都不允许频繁变"。
+
+    由调用方按会话持有同一个实例，跨轮传入 ``postprocess``。导演顺序：
+    防降级在前、迟滞最后一道闸（压制包括 learned_rules 在内的所有后续变化）。
+    """
+
+    window: float = HYSTERESIS_WINDOW
+    max_changes: int = 1                     # 窗口内允许的档位变化次数，超过即冻结
+    prev_tier: int | None = None             # 上一轮最终档位索引
+    prev_ts: float | None = None             # 上一轮时间戳
+    change_count: int = 0                    # 当前窗口内已变化次数
+    last_change_ts: float | None = None      # 最近一次变化的时间戳
+    frozen_tier: int | None = None           # 命中冻结档位（None=未冻结）
+    frozen_ts: float | None = None           # 冻结开始时间
+
+    def step(self, target: int, forced: bool, ts: float = 0.0) -> int:
+        """对本次路由目标档位应用迟滞，返回最终档位索引。
+
+        ``target`` 为防降级后的目标档；``forced`` 为是否已被硬规则强制
+        （风险/长上下文/闲聊），硬规则输入允许突破冻结立即生效。
+        """
+        # 窗口过期：重置计数，解冻
+        if self.last_change_ts is not None and not forced:
+            if ts - self.last_change_ts > self.window:
+                self.change_count = 0
+                self.frozen_tier = None
+                self.frozen_ts = None
+
+        # 冻结持续期：非硬输入一律压回冻结档
+        if self.frozen_tier is not None and not forced:
+            if self.frozen_ts is not None and ts - self.frozen_ts <= self.window:
+                return self.frozen_tier
+            self.frozen_tier = None          # 冻结窗口过期，自动解冻
+            self.frozen_ts = None
+
+        prev = self.prev_tier
+        if prev is None or target == prev:
+            # 无历史或档位未变：不计数
+            self.prev_tier = target
+            self.prev_ts = ts
+            return target
+
+        # 档位将要变化
+        if forced:
+            # 硬规则强制：解冻并放行
+            self.frozen_tier = None
+            self.frozen_ts = None
+            self.change_count = 0
+        else:
+            self.change_count += 1
+            if self.change_count > self.max_changes:
+                # 触发冻结：压回上一档
+                self.frozen_tier = prev
+                self.frozen_ts = ts
+                self.last_change_ts = ts
+                self.change_count = 0
+                return prev                       # prev_tier 保持 prev
+            self.last_change_ts = ts
+
+        self.prev_tier = target
+        self.prev_ts = ts
+        return target
+
+
+def hit(text: str, cat: str) -> bool:
+    """判断文本是否命中某类关键词（英文转小写后子串匹配）。"""
+    t = text.lower()
+    return any(k in t for k in KEYWORDS[cat])
+
+
+def postprocess(tier_idx: int, text: str, f: dict,
+                prev_tier: int | None = None, prev_ts: float | None = None,
+                ts: float = 0.0, context_tokens: int = 0,
+                learned_rules=None, hysteresis=None) -> int:
+    """按顺序应用规则，返回最终档位索引 0..3。
+
+    ``learned_rules``（adaptive.LearnedRules，可选）在 6 条规则之后、且仅
+    在未被硬规则强制时应用：命中的 ±1 档微调永不覆盖风险/闲聊/长上下文硬规则
+    （phase-04 A1 验收约束）。
+    ``hysteresis``（Hysteresis，可选，phase-04 A2）作为最后一道闸应用：
+    session 内窗口变化超阈值即冻结当前档，直到窗口过期或命中硬规则才解冻；
+    不传即 A1 之前行为，与其它机制完全向后兼容。
+    """
+    t = tier_idx
+    forced = False  # 是否已被某条硬规则强制锁定（learned_rules 不再覆盖）
+
+    # 1) 风险旗标 → 强制 >= Superior
+    if hit(text, "risk"):
+        t = max(t, 2)
+        forced = True
+
+    # 2) 长上下文旗标 → 强制 >= Superior
+    blocks = code_blocks(text)
+    if (len(text) > 6000
+            or (blocks and max(len(b) for b in blocks) > 1500)
+            or context_tokens > 2000):
+        t = max(t, 2)
+        forced = True
+
+    # 3) 架构旗标 → 升一档
+    if hit(text, "arch"):
+        t = min(t + 1, 3)
+
+    # 4) 调试旗标 → 升一档
+    if hit(text, "debug"):
+        t = min(t + 1, 3)
+
+    # 5) 简短闲聊旗标 → 强制 <= Basic
+    if (hit(text, "chatty") and f["num_code_blocks"] == 0
+            and not hit(text, "teach") and not hit(text, "arch")
+            and not hit(text, "risk") and not hit(text, "planning")):
+        t = 0
+        forced = True
+
+    # 6) 防降级：同会话 600s 内，档位最多比上一轮低 1 档
+    if prev_tier is not None and prev_ts is not None and ts - prev_ts < ANTI_DOWNGRADE_WINDOW:
+        t = max(t, prev_tier - 1)
+
+    # 7) learned_rules 局部规则（第 4 期 A1）：仅未被硬规则强制时 ±1 档微调
+    if not forced and learned_rules is not None:
+        action = learned_rules.apply(f)
+        if action > 0:
+            t = min(t + 1, 3)
+        elif action < 0:
+            t = max(t - 1, 0)
+
+    # 8) 迟滞稳定层（第 4 期 A2）：最后一道闸，压制所有后续变化。
+    #    防降级在前、迟滞在后；冻结时连 learned_rules 的微调也一并压住。
+    if hysteresis is not None:
+        # 首轮用调用方传入的上一轮档态初始化内部 prev（迟滞自身跨轮维护）
+        if hysteresis.prev_tier is None and prev_tier is not None:
+            hysteresis.prev_tier = prev_tier
+            hysteresis.prev_ts = prev_ts if prev_ts is not None else ts
+        t = hysteresis.step(t, forced, ts)
+
+    return t

xg/router/rule_router.py

@@ -0,0 +1,77 @@
+"""SmartRouter 规则路由器（开局纯规则判断，零训练、零依赖）。
+
+评分公式与阈值来源：XG-docs/smart-docs/ADAPTIVE_ROUTING.md §6.1。
+
+与文档的两处有意差异（均为文档内部自相矛盾处，按注释意图/验证表修正）：
+1. Basic 档阈值取 ``s < 1.0`` 而非 ``s <= 1.0``：文档验证表中
+   "写个二分查找"（score=1）应落 Enhanced，``<=`` 会错判为 Basic。
+2. 防降级规则见 postprocess.py（不在本模块）。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# 分档阈值：score < 1.0 → Basic；<= 5.0 → Enhanced；<= 12.0 → Superior；其余 Ultimate
+_THRESHOLDS = (1.0, 5.0, 12.0)
+
+
+@dataclass(frozen=True)
+class RuleDecision:
+    """规则路由结果。"""
+
+    tier_idx: int      # 0..3 = Basic..Ultimate
+    score: float       # 加权总分（硬规则命中时为占位分数）
+    hard_rule: bool    # 是否由硬规则直接决定（不参与分数竞争）
+
+
+def rule_score(f: dict) -> float:
+    """对特征做加权求和，返回总分。"""
+    s = 0.0
+    s += min(f["len_chars"] // 100, 15) * 1.0        # 每 100 字符 +1（max 15）
+    s += min(f["num_code_blocks"], 4) * 8.0          # 每个代码块 +8（max 4）
+    s += f["num_json"] * 2.0                         # 每个 JSON/XML +2
+    s += f["num_lists"] * 1.5                        # 每个列表项 +1.5
+    s += f["num_arch_kw"] * 3.0                      # 每个架构词 +3
+    s += f["num_risk_kw"] * 5.0                      # 每个风险词 +5
+    s += f["num_planning_kw"] * 4.0                  # 每个规划词 +4
+    s += f["num_impl_kw"] * 1.0                      # 每个实现词 +1
+    s += f["num_teach_kw"] * 1.0                     # 每个教学词 +1
+    s += f["num_constraint_kw"] * 2.0                # 每个约束词 +2
+    s += f["is_chatty"] * -6.0                       # 闲聊直接扣大分
+    s += f["question_mark"] * -1.5                   # 疑问句略偏简单
+    return s
+
+
+def rule_route(f: dict) -> RuleDecision:
+    """硬规则优先（不参与分数竞争），其余按总分映射分档。"""
+    # 硬规则 1：有风险词 / 强架构 → 至少 Superior
+    if f["num_risk_kw"] >= 1 or f["num_arch_kw"] >= 2:
+        return RuleDecision(2, rule_score(f), True)
+    # 硬规则 2：大量代码块 / 超长文本 → Ultimate
+    if f["num_code_blocks"] >= 3 or f["len_chars"] > 12000:
+        return RuleDecision(3, rule_score(f), True)
+    # 硬规则 3：纯闲聊（无代码块、无教学/架构/风险词）→ Basic
+    if (f["is_chatty"] and f["num_code_blocks"] == 0 and f["num_teach_kw"] == 0
+            and f["num_arch_kw"] == 0 and f["num_risk_kw"] == 0):
+        return RuleDecision(0, rule_score(f), True)
+
+    # 软规则：按总分映射
+    s = rule_score(f)
+    if s < _THRESHOLDS[0]:
+        idx = 0
+    elif s <= _THRESHOLDS[1]:
+        idx = 1
+    elif s <= _THRESHOLDS[2]:
+        idx = 2
+    else:
+        idx = 3
+    return RuleDecision(idx, s, False)
+
+
+def confidence(decision: RuleDecision) -> float:
+    """规则路由的置信度估计：硬规则 1.0；软规则按分数到最近阈值的距离估。"""
+    if decision.hard_rule:
+        return 1.0
+    margin = min(abs(decision.score - b) for b in _THRESHOLDS)
+    return 0.5 + 0.5 * min(1.0, margin / 4.0)

xg/router/semantic.py

@@ -0,0 +1,138 @@
+"""SmartRouter 语义编码器（第 6 期 C2，ONNX Runtime 加载 bge 产物）。
+
+职责：把用户输入编码为 512 维语义向量，供 ml_router 精判时并入特征列
+（``[TF-IDF + 数值 + 语义]``）；任何缺依赖 / 缺产物 / 产物损坏 情形一律
+**静默回落**（encode 返回 None），行为退化为 ``ml_router`` 无语义时的原貌。
+
+导入保护（主进程零硬性 ML 依赖）：
+    onnxruntime / tokenizers / numpy 仅在 encode 运行期 import，任一把
+    import 失败即在初始化时把本编码器标记为不可用（available=False），
+    主进程绝不因缺依赖而报错。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_EMBED_DIM = 512  # bge-small-zh-v1.5 输出维度
+
+
+def _default_onnx_path() -> Path:
+    from ..adaptive.store import semantic_onnx_path
+    return semantic_onnx_path()
+
+
+class SemanticEncoder:
+    """ONNX 语义编码器；不可用时 encode 返回 None（静默回落）。"""
+
+    def __init__(self, onnx_path: Path | None = None) -> None:
+        self._path = onnx_path or _default_onnx_path()
+        self._session = None
+        self._tokenizer = None
+        # C3 观测：成功编码统计（每轮耗时 + 有效样本量），供 /smartRouter status 展示
+        self._calls = 0
+        self._total_ms = 0.0
+        self._last_ms = 0.0
+        self._load()
+
+    def _load(self) -> None:
+        """加载 ONNX session + tokenizer；任何异常 → 不可用。"""
+        if not self._path.exists():
+            return
+        try:
+            import onnxruntime  # noqa: PLC0415
+            from tokenizers import Tokenizer  # noqa: PLC0415
+            import numpy as np  # noqa: PLC0415
+
+            # bge 的 tokenizer 以 JSON 与产物同级目录存放（C1 导出时同目录）
+            tok_path = self._path.with_suffix(".json")
+            if not tok_path.exists():
+                return
+            tok = Tokenizer.from_file(str(tok_path))
+            sess = onnxruntime.InferenceSession(
+                str(self._path), providers=["CPUExecutionProvider"],
+            )
+            # 自检输出维度 = 512
+            out_meta = sess.get_outputs()[0].shape
+            dims = [d for d in out_meta if d not in (None, -1)]
+            if dims and dims[-1] != _EMBED_DIM:
+                return
+            self._session = sess
+            self._tokenizer = tok
+        except Exception:
+            self._session = None
+            self._tokenizer = None
+
+    @property
+    def available(self) -> bool:
+        return self._session is not None and self._tokenizer is not None
+
+    @property
+    def dim(self) -> int:
+        return _EMBED_DIM
+
+    @property
+    def artifact_exists(self) -> bool:
+        """产物（.onnx）是否存在于预期路径（C3 观测）。"""
+        return self._path.exists()
+
+    @property
+    def calls(self) -> int:
+        """成功完成编码的轮次数（有效样本量观测）。"""
+        return self._calls
+
+    @property
+    def avg_ms(self) -> float:
+        """累计平均每轮编码耗时（毫秒）。"""
+        return (self._total_ms / self._calls) if self._calls else 0.0
+
+    @property
+    def last_ms(self) -> float:
+        """最近一轮编码耗时（毫秒）。"""
+        return self._last_ms
+
+    def encode(self, text: str) -> list[float] | None:
+        """把整段文本编码为 512 维向量；不可用返回 None（静默回落）。
+
+        bge 取 first token（[CLS]）向量并做 L2 归一化；成功时记录轮次耗时。
+        """
+        if not self.available or not text:
+            return None
+        import time  # noqa: PLC0415
+        t0 = time.perf_counter()
+        try:
+            import numpy as np  # noqa: PLC0415
+            enc = self._tokenizer.encode(text)
+            ids = (enc.ids[:512] or [0]).__class__([  # 空输入兜底
+                i for i in enc.ids[:512]
+            ] or [0])[:512]
+            mask = [1] * len(ids)
+            input_ids = np.array([ids], dtype=np.int64)
+            attention = np.array([mask], dtype=np.int64)
+            feed = {"input_ids": input_ids, "attention_mask": attention}
+            # bge/BERT 常要求 token_type_ids；单段输入给全零
+            if "token_type_ids" in {i.name for i in self._session.get_inputs()}:
+                feed["token_type_ids"] = np.zeros_like(input_ids)
+            out = self._session.run(None, feed)[0]  # (1, seq, dim)
+            vec = out[0][0].astype(np.float64)  # [CLS]
+            norm = float(np.linalg.norm(vec))
+            if norm < 1e-9:
+                return [0.0] * _EMBED_DIM
+            self._last_ms = (time.perf_counter() - t0) * 1000.0
+            self._total_ms += self._last_ms
+            self._calls += 1
+            return (vec / norm).tolist()
+        except Exception:
+            return None
+
+
+def load_semantic_encoder(onnx_path: Path | None = None) -> SemanticEncoder:
+    """便捷工厂：缺依赖/缺产物时返回一个 available=False 的编码器。
+
+    未显式指定路径时，先尝试把随包语义产物（xg/assets/）落位到数据目录，
+    使 clone 后首启即可用语义通道；无随包产物或复制失败时静默跳过。
+    """
+    if onnx_path is None:
+        from ..adaptive.store import ensure_default_artifacts
+        ensure_default_artifacts()
+    return SemanticEncoder(onnx_path)

xg/safety/audit.py

@@ -0,0 +1,96 @@
+"""审计日志：统一 JSONL 记录 + 敏感字段脱敏。
+
+记录位置：<项目根>/.xg/audit.log
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit, urlunsplit
+from uuid import uuid4
+
+_SENSITIVE_KEY_RE = re.compile(r"^(api_key|apikey|token|authorization|password|secret|private_key)$", re.I)
+_BEARER_RE = re.compile(r"\b(Bearer\s+)[A-Za-z0-9._~+/=-]+", re.I)
+_SECRET_ASSIGN_RE = re.compile(
+    r"\b(api[_-]?key|access[_-]?token|auth(?:orization)?|password|secret)"
+    r"(\s*[:=]\s*)(?!Bearer\b)([^\s,;]+)",
+    re.I,
+)
+_REDACTED = "***"
+
+
+def _web_audit_value(key: str, value: Any) -> Any:
+    """Keep Web audit useful without retaining query tokens or full prompts."""
+    if key == "query" and isinstance(value, str):
+        return redact_text(value[:120])
+    if key in {"requested_url", "final_url", "url"} and isinstance(value, str):
+        try:
+            parts = urlsplit(value)
+            return urlunsplit((parts.scheme, parts.netloc, parts.path, "", ""))
+        except ValueError:
+            return value[:200]
+    if key in {"headers", "header", "authorization", "cookie", "set-cookie"}:
+        return _REDACTED
+    return value
+
+
+def redact_text(value: str) -> str:
+    """脱敏文本中的 Bearer token 与常见 key=value 形式敏感值。"""
+    value = _BEARER_RE.sub(r"\1***", value)
+    return _SECRET_ASSIGN_RE.sub(r"\1\2***", value)
+
+
+def redact(value: Any) -> Any:
+    """递归脱敏：敏感键名的值、文本中的 Bearer token（保留键名，脱敏值）。"""
+    if isinstance(value, dict):
+        return {
+            str(k): _REDACTED if _SENSITIVE_KEY_RE.match(str(k)) else redact(v)
+            for k, v in value.items()
+        }
+    if isinstance(value, list):
+        return [redact(v) for v in value]
+    if isinstance(value, str):
+        return redact_text(value)
+    return value
+
+
+class AuditLogger:
+    def __init__(self, log_path: str | Path, session_id: str | None = None) -> None:
+        self.log_path = Path(log_path)
+        self.session_id = session_id or uuid4().hex[:8]
+
+    def record(self, action: str, **fields: Any) -> None:
+        entry: dict[str, Any] = {
+            "time": datetime.now().isoformat(timespec="seconds"),
+            "session": self.session_id,
+            "action": action,
+        }
+        entry.update({k: redact(_web_audit_value(k, v) if action.startswith("web_") else v) for k, v in fields.items()})
+        try:
+            self.log_path.parent.mkdir(parents=True, exist_ok=True)
+            with self.log_path.open("a", encoding="utf-8") as f:
+                f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+        except OSError:
+            pass
+
+    def tool_call(self, tool: str, args: dict, ok: bool, duration_ms: int, approved: bool = True) -> None:
+        if tool.startswith("web_"):
+            args = {key: _web_audit_value(key, value) for key, value in args.items()}
+        self.record(
+            "tool_call",
+            tool=tool,
+            args=args,
+            approved=approved,
+            ok=ok,
+            duration_ms=duration_ms,
+        )
+
+    def approval(self, tool: str, args: dict, decision: str, reason: str = "") -> None:
+        self.record("approval", tool=tool, args=args, decision=decision, reason=reason)
+
+    def blocked(self, reason: str, **detail: Any) -> None:
+        self.record("blocked", reason=reason, **detail)

xg/safety/guards.py

@@ -0,0 +1,106 @@
+"""PathGuard / CommandGuard：策略层纯函数。
+
+策略层拒绝为终审：黑名单命令 / 越界路径不执行，且不可被 HITL 审批绕过。
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+# 受路径约束的工具：read / write / list / glob / grep
+PATH_TOOLS = {"read_file", "write_file", "list_dir", "glob_files", "grep_code"}
+
+
+@dataclass(frozen=True)
+class GuardResult:
+    ok: bool
+    reason: str = ""   # command_blacklist / path_outside_root
+    detail: str = ""
+
+
+# ---------- CommandGuard ----------
+
+_COMMAND_BLACKLIST_PATTERNS = [
+    # 对根/系统目录的递归删除
+    re.compile(r"\brm\s+(-rf|-fr)\s+/\s*$"),
+    re.compile(r"\brm\s+(-rf|-fr)\s+/\*"),
+    # 磁盘/分区级破坏
+    re.compile(r"\bmkfs\b"),
+    re.compile(r"\bdd\b.*\bof=/dev/"),
+    re.compile(r"\bformat\s+[a-z]:\\?"),
+    re.compile(r"\bdiskpart\b"),
+    re.compile(r"^\s*>\s*/dev/"),
+    # Windows 破坏性删除：递归删除 / 驱动盘根级
+    re.compile(r"\bdel\b.*\b/s\b"),
+    re.compile(r"\bdel\b.*\b[cd]:\\"),
+    re.compile(r"\brd\b.*\b/s\b"),
+    re.compile(r"\brd\b.*\b[cd]:\\"),
+    # 关机 / 重启
+    re.compile(r"\b(?:shutdown|reboot|halt|poweroff)\b"),
+    # fork bomb
+    re.compile(r":\(\)\s*\{\s*:\|:&\s*\}\s*;"),
+]
+
+
+def command_guard(command: str) -> GuardResult:
+    """校验命令是否命中黑名单。空命令放行（后续由工具层报错）。"""
+    if not command or not command.strip():
+        return GuardResult(ok=True)
+    lower = command.strip().lower()
+    for pattern in _COMMAND_BLACKLIST_PATTERNS:
+        if pattern.search(lower):
+            return GuardResult(ok=False, reason="command_blacklist", detail=command.strip())
+    return GuardResult(ok=True)
+
+
+# ---------- PathGuard ----------
+
+def _resolve_absolute(base: Path, raw: str) -> Path:
+    """把工具路径参数解析为绝对路径（解 symlink）。"""
+    p = Path(raw)
+    abs_path = p if p.is_absolute() else (base / p)
+    return abs_path.resolve()
+
+
+def path_guard(base: Path, tool_name: str, args: dict) -> GuardResult:
+    """校验路径工具的参数是否位于项目根内。"""
+    if tool_name not in PATH_TOOLS:
+        return GuardResult(ok=True)
+
+    targets: list[tuple[str, str]] = []
+    raw_path = args.get("path")
+    if raw_path:
+        targets.append(("path", str(raw_path)))
+    if tool_name in ("write_file", "execute_command"):
+        raw_cwd = args.get("cwd")
+        if raw_cwd:
+            targets.append(("cwd", str(raw_cwd)))
+
+    for label, raw in targets:
+        resolved = _resolve_absolute(base, raw)
+        if not _is_within(base, resolved):
+            return GuardResult(
+                ok=False,
+                reason="path_outside_root",
+                detail=f"{label}={raw}（解析为 {resolved}，不在项目根内）",
+            )
+    return GuardResult(ok=True)
+
+
+def _is_within(base: Path, target: Path) -> bool:
+    try:
+        target.relative_to(base.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def guard_tool_call(base: Path, tool_name: str, args: dict) -> GuardResult:
+    """策略层统一入口。"""
+    if tool_name == "execute_command":
+        return command_guard(str(args.get("command", "")))
+    if tool_name in PATH_TOOLS:
+        return path_guard(base, tool_name, args)
+    return GuardResult(ok=True)

xg/safety/hitl.py

@@ -0,0 +1,73 @@
+"""HITL 审批状态机。
+
+敏感度分级：never（不审）/ confirm（默认审）/ always（必审）。
+fail closed：策略启用但无审批回调时，需审批的操作一律拒绝。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Awaitable, Callable
+
+DEFAULT_APPROVAL_LEVELS = {
+    "read_file": "never",
+    "list_dir": "never",
+    "glob_files": "never",
+    "grep_code": "never",
+    "write_file": "confirm",
+    "execute_command": "always",
+    "web_search": "never",
+    "web_fetch": "never",
+}
+
+
+@dataclass
+class ApprovalDecision:
+    allow: bool
+    args: dict | None = None   # 改参后的参数（allow=True 时生效）
+    reason: str = ""           # user_approved / user_rejected / user_skipped / auto_allow / auto_deny_no_requester
+
+
+ApprovalRequester = Callable[[str, str, dict], Awaitable[ApprovalDecision]]
+
+
+class HITLPolicy:
+    """审批策略：是否启用、敏感度表、会话级全部放行、审批回调。"""
+
+    def __init__(
+        self,
+        enabled: bool = True,
+        levels: dict | None = None,
+        requester: ApprovalRequester | None = None,
+    ) -> None:
+        self.enabled = enabled
+        self.levels = dict(DEFAULT_APPROVAL_LEVELS)
+        if levels:
+            self.levels.update(levels)
+        self.requester = requester
+        self.session_allow_all = False
+
+    def sensitivity(self, tool_name: str) -> str:
+        return self.levels.get(tool_name, "never")
+
+    def requires_approval(self, tool_name: str) -> bool:
+        return self.enabled and not self.session_allow_all and self.sensitivity(tool_name) != "never"
+
+    async def decide(self, tool_name: str, args: dict) -> ApprovalDecision:
+        """对一次工具调用做审批决策。"""
+        if not self.requires_approval(tool_name):
+            return ApprovalDecision(allow=True, reason="auto_allow")
+        if self.requester is None:
+            # fail closed：无交互渠道，需审批的操作一律拒绝
+            return ApprovalDecision(allow=False, reason="auto_deny_no_requester")
+        return await self.requester(tool_name, self.sensitivity(tool_name), args)
+
+    def set_enabled(self, enabled: bool) -> None:
+        self.enabled = enabled
+
+    def allow_all(self) -> None:
+        """本会话全部放行。"""
+        self.session_allow_all = True
+
+    def reset_session(self) -> None:
+        self.session_allow_all = False

xg/skill/__init__.py

@@ -0,0 +1,9 @@
+"""Discoverable, read-only task skills."""
+
+from xg.skill.models import SkillConfig, SkillDocument, SkillInfo, SkillLoadRequest, SkillReference
+from xg.skill.registry import SkillRegistry
+
+__all__ = [
+    "SkillConfig", "SkillDocument", "SkillInfo", "SkillLoadRequest",
+    "SkillReference", "SkillRegistry",
+]