superagent-build 0.1.0__py3-none-any.whl

agent/__init__.py

@@ -0,0 +1,14 @@
+"""自研 Super Agent——治理内嵌 + Watchdog + 主动阈值的任务执行层。
+
+模块图：
+    store.py        持久层（WAL+FULL、receipts、outbox）
+    model.py        聚合根（Thread/Ticket/Mandate/Assessment）
+    admission.py    两级准入（规则 gate + 研判硬校验）
+    outbox.py       效果三角投递（先存后做 + 退避）
+    tickets.py      Ticket 仓储与订阅扇出
+    executor.py     worker 会话抽象（EchoExecutor 测试位）
+    engine.py       编排（pass 循环、恢复）
+    governance.py   写作用域治理（内嵌版）
+    watchdog.py     跑偏检测（规则层 + judge）
+    proactivity.py  主动性开口阈值（p*(t)，observe 模式）
+"""

agent/admission.py

@@ -0,0 +1,116 @@
+"""两级准入：第一级确定性规则 gate，第二级模型研判（带硬校验）。
+
+对齐原型 policy.ts / admission.ts 的语义（见 superagent-dig/01）：
+- explicit：白名单用户 + 明确 @/指令 → 直接显式接单；
+- mention：白名单用户提到但未显式指令 → 需研判；
+- broadcast：非定向 → 默认忽略（可被 observe 模式记录）；
+- bot 门：bot/CI 消息一律不进 eval（机器门 machineGate）；
+- follow-up：开放 ticket 所在线程上、同一个人的后续消息 → 不开新 eval，
+  直接作为该 ticket 的输入（原型 policy.ts:206-207）。
+
+第二级研判产 Assessment，硬校验（原型 policy.ts:40-61 的铁律）：
+1. matched_rule 必须恰好命中一条规则（0 条或 2 条都拒）；
+2. accept 必须 intent_evidence 非空；
+3. 研判声明的规则必须真实存在于 gate 输出里（防幻觉规则名）。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from .model import Assessment, Input
+
+
+# ---------- 配置 ----------
+
+@dataclass
+class AdmissionConfig:
+    whitelist: list[str] = field(default_factory=list)   # 用户 id 白名单
+    explicit_markers: tuple[str, ...] = ("/do", "/task", "@agent")  # 显式指令前缀
+    bot_allowlist: list[str] = field(default_factory=list)  # 允许进来的 bot（默认全拒）
+
+
+# ---------- 第一级：规则 gate ----------
+
+@dataclass
+class GateResult:
+    route: str          # explicit / mention / broadcast / bot / follow_up
+    matched_rules: list[str]
+    open_ticket_id: Optional[str] = None  # follow_up 命中的开放 ticket
+
+
+def gate(inp: Input, cfg: AdmissionConfig,
+         thread_open_tickets: Optional[dict[str, str]] = None) -> GateResult:
+    """thread_open_tickets: thread_key -> 开放 ticket id（无则为空 dict）。"""
+    thread_open_tickets = thread_open_tickets or {}
+
+    # bot 门：机器消息不进 eval，除非显式白名单
+    if inp.is_bot and inp.thread_key not in cfg.bot_allowlist:
+        return GateResult("bot", [])
+
+    # follow-up：同线程已有开放 ticket 的人消息 → 附加到既有 ticket
+    if inp.is_human and inp.thread_key in thread_open_tickets:
+        return GateResult("follow_up", ["follow_up"],
+                          open_ticket_id=thread_open_tickets[inp.thread_key])
+
+    if not inp.is_human:
+        return GateResult("bot", [])
+
+    whitelisted = inp.id.split(":", 1)[0] in cfg.whitelist or inp.thread_key in cfg.whitelist
+    if not whitelisted:
+        return GateResult("broadcast", [])
+
+    is_explicit = any(inp.text.startswith(m) or f" {m}" in inp.text
+                      for m in cfg.explicit_markers)
+    if is_explicit:
+        return GateResult("explicit", ["whitelist_user", "explicit_marker"])
+    return GateResult("mention", ["whitelist_user"])
+
+
+# ---------- 第二级：研判硬校验 ----------
+
+def validate_assessment(a: Assessment, gate_result: GateResult) -> tuple[bool, str]:
+    """返回 (ok, reason)。ok=False 时调用方必须拒绝 accept（fail-closed）。"""
+    # 铁律1：matched_rule 恰好一条
+    if a.matched_rule is None or not isinstance(a.matched_rule, str):
+        return False, "missing_rule"
+    # 铁律2：accept 必须 intent_evidence 非空
+    if a.accepted and not a.intent_evidence.strip():
+        return False, "accept_without_evidence"
+    # 铁律3：研判引用的规则必须来自 gate 实际输出（防幻觉规则名）
+    if a.matched_rule not in gate_result.matched_rules:
+        return False, f"hallucinated_rule:{a.matched_rule}"
+    # deny 不需要证据，但 accept + broadcast 路由不允许（broadcast 无授权）
+    if a.accepted and gate_result.route == "broadcast":
+        return False, "accept_on_broadcast"
+    return True, "ok"
+
+
+def decide(inp: Input, cfg: AdmissionConfig,
+           thread_open_tickets: Optional[dict[str, str]] = None,
+           assessor=None) -> tuple[str, Optional[Assessment]]:
+    """完整准入决策。返回 (disposition, assessment)。
+
+    assessor: Callable(Input, GateResult) -> Assessment
+      — None 时用默认保守策略（explicit 即接，mention/broadcast 拒），
+        即"研判层缺位时 fail-closed"。
+    disposition: accept / follow_up / rejected_bot / rejected_broadcast / rejected_eval / observe
+    """
+    g = gate(inp, cfg, thread_open_tickets)
+    if g.route == "bot":
+        return "rejected_bot", None
+    if g.route == "follow_up":
+        return "follow_up", None
+    if g.route == "explicit":
+        return "accept", Assessment(True, "explicit_marker",
+                                    intent_evidence="whitelisted explicit marker",
+                                    confidence=1.0)
+
+    # mention / broadcast：需要研判层
+    if assessor is None:
+        return "rejected_eval", None  # 无研判层 → fail-closed
+    a = assessor(inp, g)
+    ok, reason = validate_assessment(a, g)
+    if not ok:
+        return f"rejected_eval:{reason}", a
+    return ("accept", a) if a.accepted else ("rejected_eval", a)

agent/assessor.py

@@ -0,0 +1,188 @@
+"""I2：两级准入的第二级——LLM 研判层（严格 JSON 契约 + fail-closed）。
+
+对齐原型 admission-context.ts 的有界上下文语义：
+- 窗口 = trigger 前 5 条 + trigger 本身 + 后 5 条；
+- 整体拼接超 max_chars 时从头部逐条丢弃（最老的先丢），trigger 及其后文不丢；
+- 任何解析失败 / 网络异常 / 超时 / 幻觉规则名 → fail-closed（accepted=False），
+  matched_rule 回落 gate_result.matched_rules[0]，空则回落 route 本身。
+
+铁律（与 admission.validate_assessment 对齐）：
+- matched_rule 只能从 gate_result.matched_rules 里选（防幻觉）；
+- assessor 缺位或失联时绝不 accept（研判层缺位 fail-closed）。
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Callable, Optional
+
+from .admission import GateResult
+from .model import Assessment, Input
+
+# transport: OpenAI chat completions 请求体 -> 响应体（可注入 fake 做零网络测试）
+Transport = Callable[[dict], dict]
+
+SYSTEM_PROMPT = (
+    "你是 superagent-build 的准入研判层（admission assessor）。"
+    "你只输出一个严格 JSON 对象，不输出任何其他文字、注释或 markdown 代码栅栏。"
+    "JSON 字段：accepted(bool)、matched_rule(str)、intent_evidence(str)、"
+    "scope_note(str)、confidence(float, 0~1)。"
+    "matched_rule 必须且只能从用户消息给出的候选规则列表中选择，禁止编造规则名。"
+    "拒绝时 matched_rule 仍须从候选列表中选，intent_evidence 可为空。"
+)
+
+
+def build_admission_context(inputs: list[Input], trigger: Input,
+                            max_chars: int = 4000,
+                            before: int = 5, after: int = 5) -> str:
+    """有界线程上下文：trigger 前 before 条 + trigger + 后 after 条。
+
+    超过 max_chars 时从头部逐条丢弃（最老的先丢），trigger 附近内容保留。
+    trigger 不在 inputs 里时，退化为保留最后 before+after+1 条的尾部窗口。
+    """
+    idx = next((i for i, m in enumerate(inputs) if m.id == trigger.id), -1)
+    if idx < 0:
+        window = list(inputs[-(before + after + 1):])
+        trigger_idx_in_window = None
+    else:
+        lo = max(0, idx - before)
+        hi = min(len(inputs), idx + after + 1)
+        window = inputs[lo:hi]
+        trigger_idx_in_window = idx - lo
+
+    # 行号用原始列表位置（从 1 起），截断后仍可读出被丢弃的范围
+    base = max(0, idx) if idx >= 0 else max(0, len(inputs) - len(window))
+    lines = [(f"[{base + i + 1}] {m.text}", i) for i, m in enumerate(window)]
+
+    def joined(items) -> str:
+        return "\n".join(t for t, _ in items)
+
+    # 从头部逐条丢弃非 trigger 行，直到塞进预算（保 trigger 附近内容）
+    kept = list(lines)
+    while len(joined(kept)) > max_chars and kept:
+        drop_i = next((k for k, (_, w) in enumerate(kept)
+                       if trigger_idx_in_window is None or w != trigger_idx_in_window),
+                      None)
+        if drop_i is None:
+            break
+        kept.pop(drop_i)
+        if trigger_idx_in_window is not None:
+            # trigger 已是窗口内唯一不可丢行；其后内容随行保留
+            pass
+    text = joined(kept)
+    if len(text) > max_chars:
+        # 兜底：全部行都不可丢仍超界（单条超长），硬截尾部保 trigger 一侧
+        text = text[-max_chars:]
+    return text
+
+
+def _extract_content(resp: dict) -> str:
+    choice = (resp.get("choices") or [{}])[0]
+    msg = choice.get("message") or {}
+    content = msg.get("content")
+    if not isinstance(content, str):
+        raise ValueError("response missing choices[0].message.content")
+    return content
+
+
+def _parse_strict_json(content: str) -> dict:
+    """容忍模型套 markdown 代码栅栏，但内容必须是合法 JSON 对象。"""
+    text = content.strip()
+    if text.startswith("```"):
+        # 去掉 ```json / ``` 围栏
+        body = text.strip("`").lstrip()
+        if body.lower().startswith("json"):
+            body = body[4:]
+        text = body.strip().rstrip("`").strip()
+    data = json.loads(text)
+    if not isinstance(data, dict):
+        raise ValueError("assessor output is not a JSON object")
+    return data
+
+
+def _fail_closed(gate_result: GateResult, reason: str) -> Assessment:
+    fallback = (gate_result.matched_rules[0]
+                if gate_result.matched_rules else gate_result.route)
+    return Assessment(accepted=False, matched_rule=fallback,
+                      intent_evidence=f"assessor_unavailable: {reason}",
+                      scope_note="fail-closed: 研判层不可用，默认拒绝",
+                      confidence=0.0)
+
+
+class LLMAssessor:
+    """Callable(Input, GateResult) -> Assessment。
+
+    研判 prompt 只允许输出严格 JSON；解析失败 / 网络异常 / 超时 / 幻觉规则名
+    一律 fail-closed，绝不 accept。
+    """
+
+    def __init__(self, model: str = "deepseek-v4.1-flash",
+                 endpoint: str = "http://127.0.0.1:3425/v1/chat/completions",
+                 api_key: str = "",
+                 timeout: float = 20.0,
+                 transport: Optional[Transport] = None):
+        self.model = model
+        self.endpoint = endpoint
+        self.api_key = api_key
+        self.timeout = timeout
+        self._transport: Transport = transport if transport is not None else self._http_transport
+
+    # ---------- 默认 HTTP 传输（真实环境用；测试注入 fake 不走这里） ----------
+
+    def _http_transport(self, payload: dict) -> dict:
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        req = urllib.request.Request(
+            self.endpoint,
+            data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
+            headers=headers, method="POST")
+        with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+            if resp.status != 200:
+                raise RuntimeError(f"assessor_endpoint_http_{resp.status}")
+            return json.loads(resp.read().decode("utf-8"))
+
+    # ---------- 研判 ----------
+
+    def __call__(self, inp: Input, gate_result: GateResult) -> Assessment:
+        prompt = (
+            f"候选规则列表（matched_rule 只能从中选择）："
+            f"{json.dumps(gate_result.matched_rules, ensure_ascii=False)}\n"
+            f"gate 路由：{gate_result.route}\n"
+            f"触发消息（id={inp.id}, thread={inp.thread_key}）：\n{inp.text}\n\n"
+            "只输出严格 JSON：{\"accepted\": bool, \"matched_rule\": str(从候选规则列表选), "
+            "\"intent_evidence\": str(accept 时必填非空), \"scope_note\": str, "
+            "\"confidence\": float}。"
+        )
+        payload = {
+            "model": self.model,
+            "messages": [
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": prompt},
+            ],
+            "temperature": 0,
+            "stream": False,
+        }
+        try:
+            resp = self._transport(payload)
+            data = _parse_strict_json(_extract_content(resp))
+        except Exception as e:  # 解析失败 / 网络异常 / 超时 → fail-closed
+            return _fail_closed(gate_result, f"{type(e).__name__}: {e}")
+
+        matched_rule = data.get("matched_rule")
+        # 防幻觉铁律：模型给的规则名必须真实存在于 gate 输出
+        if matched_rule not in gate_result.matched_rules:
+            return _fail_closed(gate_result, f"hallucinated_rule:{matched_rule}")
+
+        try:
+            accepted = bool(data["accepted"])
+            intent_evidence = str(data.get("intent_evidence", "") or "")
+            scope_note = str(data.get("scope_note", "") or "")
+            confidence = float(data.get("confidence", 0.0) or 0.0)
+        except (KeyError, TypeError, ValueError) as e:
+            return _fail_closed(gate_result, f"malformed_assessment: {e}")
+
+        return Assessment(accepted=accepted, matched_rule=matched_rule,
+                          intent_evidence=intent_evidence,
+                          scope_note=scope_note, confidence=confidence)

agent/calibration.py

@@ -0,0 +1,252 @@
+"""主动性校准机制（迭代 I5）：给开口事件一个真证据源 + 校准闭环。
+
+背景（任务⑤建模，见 superagent-dig/05-proactivity-modeling.md）：
+- 开口判定 confidence ≥ p*(t) = (c_false + c_speak) / (u_eff(t) + c_false)。
+- engine.py 里原先硬编码 confidence=0.95 —— 那是个假确证度，没有证据支撑。
+- observe 模式攒下的日志就是"该不该说"的标注数据；用它反推能达标的参数
+  (c_false, c_speak, lam)，校准目标是开口 precision ≥ target（默认 0.8）。
+
+三个组件：
+1) ConfidenceEstimator —— 多证据源加权合成确证度（替代硬编码 0.95）。
+2) LabelStore         —— append-only JSONL 标注存储（observe 日志的人工标注）。
+3) calibrate()        —— 网格搜索参数，重放判定，挑出开口 precision 达标的第一组。
+
+设计约束：纯 stdlib、确定性、无网络、无 sleep。校准重放直接复用
+proactivity.ProactivityEngine，把时钟钉在 max(created_at) 以剥离衰减干扰。
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Optional
+
+# ---------- ConfidenceEstimator 常量 ----------
+
+# 默认证据源键（缺省会参与加权平均）：
+#   watchdog_pass        watchdog 复核通过率
+#   worker_verified      worker 自证比例
+#   historical_precision 历史开口准确率
+DEFAULT_SOURCES = ("watchdog_pass", "worker_verified", "historical_precision")
+
+_NEUTRAL = 0.5          # 缺证据源时的中性值
+_MISSING_DISCOUNT = 0.8  # 有源缺失时对结果打的折
+_EMPTY_CONSERVATIVE = 0.4  # 空 evidence 的保守值
+
+
+class ConfidenceEstimator:
+    """证据源 → 确证度 p ∈ [0,1] 的合成器。
+
+    行为：
+    - 配置的证据源逐个取 evidence 里的值；缺失的源按 0.5 中性值参与，并对
+      最终加权平均乘 0.8 打折（缺证据要保守）。
+    - 空 evidence 直接返回 0.4（最保守，连有多少源都不知道）。
+    - 结果始终 clamp 到 [0,1]（宽容越界输入，避免脏数据撑爆阈值判定）。
+
+    weights: 可选 {"源名": 权重}。None → 三个默认源各 1.0；显式给出则以其为
+             唯一证据源集合（可用于单源/自定义源场景）。
+    """
+
+    def __init__(self, weights: Optional[dict] = None):
+        if weights is None:
+            self.weights: dict[str, float] = {k: 1.0 for k in DEFAULT_SOURCES}
+        else:
+            self.weights = dict(weights)
+
+    def estimate(self, evidence: dict) -> float:
+        if not evidence:
+            return _EMPTY_CONSERVATIVE
+
+        total = 0.0
+        total_w = 0.0
+        missing = False
+        for src, w in self.weights.items():
+            if w <= 0:
+                continue
+            if src in evidence:
+                val = float(evidence[src])
+            else:
+                val = _NEUTRAL
+                missing = True
+            total += w * val
+            total_w += w
+
+        if total_w <= 0:
+            return _EMPTY_CONSERVATIVE
+
+        score = total / total_w
+        if missing:
+            score *= _MISSING_DISCOUNT
+        # clamp 到 [0,1]
+        if score < 0.0:
+            return 0.0
+        if score > 1.0:
+            return 1.0
+        return score
+
+
+# ---------- LabelStore 常量 ----------
+
+VALID_LABELS = ("speak_ok", "speak_bad", "wait_ok", "wait_bad")
+
+
+class LabelStore:
+    """append-only 标注存储。
+
+    - path=None → 纯内存（self._mem）。
+    - path=str  → 追加写 JSONL（每行一条记录；不覆写、不删除）。
+    - 每条记录 = decision_dict 的浅拷贝 + 覆盖写入的 "label" 字段，
+      这样 load() 读回的记录可直接喂给 calibrate()（含 utility/confidence/
+      created_at/label）。
+    """
+
+    def __init__(self, path: Optional[str] = None):
+        self.path = path
+        self._mem: list[dict] = []
+        if path is not None:
+            parent = os.path.dirname(os.path.abspath(path))
+            if parent:
+                os.makedirs(parent, exist_ok=True)
+
+    def append(self, decision_dict: dict, label: str) -> None:
+        if label not in VALID_LABELS:
+            raise ValueError(
+                f"非法 label: {label!r}，仅允许 {VALID_LABELS}")
+        record = dict(decision_dict)
+        record["label"] = label
+        if self.path is None:
+            self._mem.append(record)
+            return
+        with open(self.path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(record, ensure_ascii=False) + "\n")
+
+    def load(self) -> list[dict]:
+        if self.path is None:
+            return list(self._mem)
+        if not os.path.exists(self.path):
+            return []
+        out: list[dict] = []
+        with open(self.path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                out.append(json.loads(line))
+        return out
+
+    def stats(self) -> dict:
+        recs = self.load()
+        counts = {lb: 0 for lb in VALID_LABELS}
+        for r in recs:
+            lb = r.get("label")
+            if lb in counts:
+                counts[lb] += 1
+        so = counts["speak_ok"]
+        sb = counts["speak_bad"]
+        denom = so + sb
+        precision = (so / denom) if denom > 0 else None
+        result: dict = dict(counts)
+        result["speak_precision"] = precision
+        return result
+
+
+# ---------- calibrate ----------
+
+DEFAULT_GRID = {
+    "c_false": [0.5, 1.0, 2.0],
+    "c_speak": [0.1, 0.2, 0.5],
+    "lam": [0.05, 0.1, 0.2],
+}
+
+
+def _replay_precision(labels: list[dict], c_false: float, c_speak: float,
+                      lam: float, now: float) -> tuple[float, int]:
+    """用一组参数重放全部标注，返回 (开口 precision, n_speak)。
+
+    判定直接复用 ProactivityEngine（observe=False，时钟钉在 now）：
+      - action == "speak" 记一次开口；
+      - 其中人工 label 为 "speak_ok" 的算命中；
+      - precision = 命中数 / n_speak；n_speak==0 时记 0.0（不开口没有可证明的精度）。
+    """
+    from .proactivity import (CandidateEvent, ProactivityConfig,
+                              ProactivityEngine)
+
+    cfg = ProactivityConfig(lam=lam, c_false=c_false, c_speak=c_speak,
+                            observe=False)
+    engine = ProactivityEngine(cfg, clock=lambda: now)
+
+    n_speak = 0
+    tp = 0
+    for r in labels:
+        ev = CandidateEvent(
+            event_id=str(r.get("event_id", "?")),
+            utility=float(r["utility"]),
+            confidence=float(r["confidence"]),
+            created_at=float(r["created_at"]),
+        )
+        decision = engine.evaluate(ev)
+        if decision.action == "speak":
+            n_speak += 1
+            if r.get("label") == "speak_ok":
+                tp += 1
+
+    precision = (tp / n_speak) if n_speak > 0 else 0.0
+    return precision, n_speak
+
+
+def calibrate(labels: list[dict], target_precision: float = 0.8,
+              grid: Optional[dict] = None) -> dict:
+    """网格搜索 (c_false, c_speak, lam)，找出开口 precision 达标的第一组。
+
+    返回：
+      达标 → {"calibrated": True, "c_false", "c_speak", "lam",
+              "achieved_precision", "n_speak"}
+      不达标 → {"calibrated": False, "best_precision", "best_params", "n_speak"}
+
+    要求 n_speak > 0 才算达标（"从不开口"没有可证明的精度，不能靠沉默刷分）。
+    """
+    g = grid or DEFAULT_GRID
+    cf_list = list(g["c_false"])
+    cs_list = list(g["c_speak"])
+    lam_list = list(g["lam"])
+
+    if not labels:
+        return {"calibrated": False, "best_precision": None,
+                "best_params": None, "n_speak": 0}
+
+    # 固定时钟：now = max(created_at)，剥离"事件存放时间"造成的衰减干扰。
+    now = max(float(r["created_at"]) for r in labels)
+
+    best_precision = -1.0
+    best_params: Optional[dict] = None
+    best_n_speak = 0
+
+    for c_false in cf_list:
+        for c_speak in cs_list:
+            for lam in lam_list:
+                precision, n_speak = _replay_precision(
+                    labels, c_false, c_speak, lam, now)
+                # 记录最优组（同精度优先更多开口，避免"零开口"占位）
+                if (precision > best_precision
+                        or (precision == best_precision
+                            and n_speak > best_n_speak)):
+                    best_precision = precision
+                    best_params = {"c_false": c_false, "c_speak": c_speak,
+                                   "lam": lam}
+                    best_n_speak = n_speak
+                # 达标（必须有开口且 precision ≥ target）→ 返回第一组
+                if n_speak > 0 and precision >= target_precision:
+                    return {
+                        "calibrated": True,
+                        "c_false": c_false,
+                        "c_speak": c_speak,
+                        "lam": lam,
+                        "achieved_precision": precision,
+                        "n_speak": n_speak,
+                    }
+
+    return {
+        "calibrated": False,
+        "best_precision": best_precision,
+        "best_params": best_params,
+        "n_speak": best_n_speak,
+    }