superagent-build 0.1.0__tar.gz

superagent_build-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: superagent-build
+Version: 0.1.0
+Summary: A measurable Super Agent kernel: two-stage admission, outbox delivery triangle, ticket persistence, write-scope governance, watchdog review, proactivity threshold, tick scheduler.
+Author: Liu Zewen
+License: MIT
+Keywords: agent,multi-agent,admission,outbox,governance,watchdog
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: openai
+
+# superagent-build — 自研 Super Agent（治理内嵌 + Watchdog + 主动阈值）
+
+> 定位：把 dsh-superagent-prototype（22k★）宣传了但没做的四件事真的做出来。
+> 证据链：拆解报告见 `../superagent-dig/01-prototype-dissection.md`（文章卖点兑现度表）。
+
+## 与原型的差异（本项目核心增量）
+
+| 能力 | 原型 | 本项目 |
+|---|---|---|
+| 跑偏检测 | 全库零实现 | `agent/watchdog.py`：Mandate 对照 + 确定性规则层 + judge 一票否决 |
+| 文件级冲突 | 只在 PR 层暴露 | `agent/governance.py`：写前 claim/check，未声明即 BLOCK |
+| 长期记忆 | 只写不读半成品 | `agent/store.py` 全量落库 + 判定留痕（ruling/watchdog 记录可审计） |
+| 主动性开口 | 无 | `agent/proactivity.py`：p*(t) 临界确证度 + observe 模式攒标注 |
+
+抄原型的（已验证扎实）：两级准入、先存后做 outbox 三角、纯幂等 receipt、follow-up 语义、
+bot 门、"Router 少说话"。
+
+## 架构
+
+```
+Input → intake（幂等 receipt）
+  → admission 两级：规则 gate（bot 门/白名单/显式指令/follow-up）
+                    → 研判层（mention 时，硬校验：恰好一条规则+证据+防幻觉规则名）
+  → accept → Decision → Ticket（订阅线程）→ Assignment → worker 会话
+  → worker report → Watchdog 复核（规则层 → judge）→ 治理判决 → 回复出站（outbox 三角）
+写前：pre_write → governance.check（未声明 scope 即 BLOCK，落 ruling）
+开口：任务完成等事件 → proactivity.evaluate → speak/wait/drop（observe 模式只记录）
+```
+
+## 运行自检（RED→GREEN 纪律：先注入违规证明会红，再验证放行）
+
+```bash
+python3 -m pytest tests/ -q             # 新套件：i1_i4 / i2 / i3 / i5 / i6 / integration
+python3 tests/test_store.py            # 老套件为自检脚本，逐个跑，末行 FAILURES: none 即过
+python3 tests/test_admission_outbox.py # 持久层：先存后做/幂等/退避/崩溃恢复
+python3 tests/test_e2e_m0.py           # 端到端：建票→派工→报告→回复→恢复
+python3 tests/test_governance.py       # 写作用域治理（M1）
+python3 tests/test_watchdog.py         # 跑偏检测（M2）
+python3 tests/test_proactivity.py      # 开口阈值（M3）
+```
+
+## 里程碑状态
+
+- [x] M0 骨架：准入/outbox/ticket/编排，端到端绿（test_e2e_m0）
+- [x] M1 治理内嵌：governance.py 接进 engine.pre_write + intake 携带 mandate_rules（test_e2e_m1）
+- [x] M2 Watchdog：接进 engine.on_worker_report（deviation → 判决留痕 + 票终止 + 不回复）（test_e2e_m2）
+- [x] M3 主动性：接进 engine（observe 模式先行，判定留痕含 p*/u_eff/confidence 三数）（test_e2e_m3）
+- [x] I1 状态回灌：崩溃恢复补上另一半——Tickets/Thread（含订阅）从 SQLite 重载 + seq 防撞号；
+      重启后同线程 follow_up 仍附加原票（test_i1_i4）
+- [x] I2 研判接真：assessor.py——LLMAssessor（OpenAI 兼容端点，transport 可注入）+
+      有界研判上下文（前5条+trigger+后5条，4000 字符封顶）；解析失败/幻觉规则名一律 fail-closed（test_i2_assessor）
+- [x] I3 真执行器：openai_executor.py——OpenAI 兼容 tool-loop worker + metrics.py 成本记账
+      （逐调用 CallRecord：tokens/延迟/成功率，JSONL 落盘）；对接位 = Magpie 网关（test_i3_executor）
+- [x] I4 复审环：deviation 不再一票终止——先给一轮修复机会（违规理由作为修复指令重投 worker，
+      复核转绿则照常回复），次数用尽才终止 + 落 governance ruling；max_repairs=0 保持 M2 旧契约（test_i1_i4）
+- [x] I5 校准机制：calibration.py——ConfidenceEstimator（证据源合成，已接进 engine 替换硬编码 0.95）+
+      LabelStore（observe 判定旁路自动攒标注）+ calibrate（网格搜索开口 precision≥0.8）（test_i5_calibration）
+- [x] I6 调度循环：scheduler.py——tick 驱动（max_workers 槽位/idle 超时回收/出站 pump），
+      engine 交付后写 idle_at；无 sleep 无线程，clock 注入可测（test_i6_scheduler）
+- [ ] M4 成本对接：`../superagent-dig/02-cost-experiment/framework.py` 的 harness 适配器位
+      （metrics.py 的 CallRecord 已是同构对接面）
+
+## 真实环境对接位（本仓库只含可测内核）
+
+- `openai_executor.py` 的 `OpenAICompatExecutor`：已实现 OpenAI 兼容 tool-loop worker（默认指向
+  Magpie 网关 `http://127.0.0.1:3425`），transport 可注入；换 endpoint/model 即换 worker；
+- `assessor.py` 的 `LLMAssessor`：已实现研判适配器（有界上下文 + fail-closed），接进 `Engine(assessor=...)` 即生效；
+- `watchdog.py` 的 `Judge` Protocol：接独立 LLM judge（语义层"答非所问"检测）；
+- `outbox.py` 的 `Deliverer`：接 GitHub/飞书通道（channelGone/channelIgnored 唯二合法放弃）；
+- `scheduler.py` 的 `Scheduler.tick`：外部主循环每轮调一次即可驱动全系统（无 sleep 无线程）；
+- `metrics.py` 的 `MetricsLedger`：逐调用成本记账（tokens/延迟/成功率，JSONL 落盘），
+  与 `../superagent-dig/02-cost-experiment/framework.py` 的 CallRecord 同构对接。

superagent_build-0.1.0/README.md

@@ -0,0 +1,72 @@
+# superagent-build — 自研 Super Agent（治理内嵌 + Watchdog + 主动阈值）
+
+> 定位：把 dsh-superagent-prototype（22k★）宣传了但没做的四件事真的做出来。
+> 证据链：拆解报告见 `../superagent-dig/01-prototype-dissection.md`（文章卖点兑现度表）。
+
+## 与原型的差异（本项目核心增量）
+
+| 能力 | 原型 | 本项目 |
+|---|---|---|
+| 跑偏检测 | 全库零实现 | `agent/watchdog.py`：Mandate 对照 + 确定性规则层 + judge 一票否决 |
+| 文件级冲突 | 只在 PR 层暴露 | `agent/governance.py`：写前 claim/check，未声明即 BLOCK |
+| 长期记忆 | 只写不读半成品 | `agent/store.py` 全量落库 + 判定留痕（ruling/watchdog 记录可审计） |
+| 主动性开口 | 无 | `agent/proactivity.py`：p*(t) 临界确证度 + observe 模式攒标注 |
+
+抄原型的（已验证扎实）：两级准入、先存后做 outbox 三角、纯幂等 receipt、follow-up 语义、
+bot 门、"Router 少说话"。
+
+## 架构
+
+```
+Input → intake（幂等 receipt）
+  → admission 两级：规则 gate（bot 门/白名单/显式指令/follow-up）
+                    → 研判层（mention 时，硬校验：恰好一条规则+证据+防幻觉规则名）
+  → accept → Decision → Ticket（订阅线程）→ Assignment → worker 会话
+  → worker report → Watchdog 复核（规则层 → judge）→ 治理判决 → 回复出站（outbox 三角）
+写前：pre_write → governance.check（未声明 scope 即 BLOCK，落 ruling）
+开口：任务完成等事件 → proactivity.evaluate → speak/wait/drop（observe 模式只记录）
+```
+
+## 运行自检（RED→GREEN 纪律：先注入违规证明会红，再验证放行）
+
+```bash
+python3 -m pytest tests/ -q             # 新套件：i1_i4 / i2 / i3 / i5 / i6 / integration
+python3 tests/test_store.py            # 老套件为自检脚本，逐个跑，末行 FAILURES: none 即过
+python3 tests/test_admission_outbox.py # 持久层：先存后做/幂等/退避/崩溃恢复
+python3 tests/test_e2e_m0.py           # 端到端：建票→派工→报告→回复→恢复
+python3 tests/test_governance.py       # 写作用域治理（M1）
+python3 tests/test_watchdog.py         # 跑偏检测（M2）
+python3 tests/test_proactivity.py      # 开口阈值（M3）
+```
+
+## 里程碑状态
+
+- [x] M0 骨架：准入/outbox/ticket/编排，端到端绿（test_e2e_m0）
+- [x] M1 治理内嵌：governance.py 接进 engine.pre_write + intake 携带 mandate_rules（test_e2e_m1）
+- [x] M2 Watchdog：接进 engine.on_worker_report（deviation → 判决留痕 + 票终止 + 不回复）（test_e2e_m2）
+- [x] M3 主动性：接进 engine（observe 模式先行，判定留痕含 p*/u_eff/confidence 三数）（test_e2e_m3）
+- [x] I1 状态回灌：崩溃恢复补上另一半——Tickets/Thread（含订阅）从 SQLite 重载 + seq 防撞号；
+      重启后同线程 follow_up 仍附加原票（test_i1_i4）
+- [x] I2 研判接真：assessor.py——LLMAssessor（OpenAI 兼容端点，transport 可注入）+
+      有界研判上下文（前5条+trigger+后5条，4000 字符封顶）；解析失败/幻觉规则名一律 fail-closed（test_i2_assessor）
+- [x] I3 真执行器：openai_executor.py——OpenAI 兼容 tool-loop worker + metrics.py 成本记账
+      （逐调用 CallRecord：tokens/延迟/成功率，JSONL 落盘）；对接位 = Magpie 网关（test_i3_executor）
+- [x] I4 复审环：deviation 不再一票终止——先给一轮修复机会（违规理由作为修复指令重投 worker，
+      复核转绿则照常回复），次数用尽才终止 + 落 governance ruling；max_repairs=0 保持 M2 旧契约（test_i1_i4）
+- [x] I5 校准机制：calibration.py——ConfidenceEstimator（证据源合成，已接进 engine 替换硬编码 0.95）+
+      LabelStore（observe 判定旁路自动攒标注）+ calibrate（网格搜索开口 precision≥0.8）（test_i5_calibration）
+- [x] I6 调度循环：scheduler.py——tick 驱动（max_workers 槽位/idle 超时回收/出站 pump），
+      engine 交付后写 idle_at；无 sleep 无线程，clock 注入可测（test_i6_scheduler）
+- [ ] M4 成本对接：`../superagent-dig/02-cost-experiment/framework.py` 的 harness 适配器位
+      （metrics.py 的 CallRecord 已是同构对接面）
+
+## 真实环境对接位（本仓库只含可测内核）
+
+- `openai_executor.py` 的 `OpenAICompatExecutor`：已实现 OpenAI 兼容 tool-loop worker（默认指向
+  Magpie 网关 `http://127.0.0.1:3425`），transport 可注入；换 endpoint/model 即换 worker；
+- `assessor.py` 的 `LLMAssessor`：已实现研判适配器（有界上下文 + fail-closed），接进 `Engine(assessor=...)` 即生效；
+- `watchdog.py` 的 `Judge` Protocol：接独立 LLM judge（语义层"答非所问"检测）；
+- `outbox.py` 的 `Deliverer`：接 GitHub/飞书通道（channelGone/channelIgnored 唯二合法放弃）；
+- `scheduler.py` 的 `Scheduler.tick`：外部主循环每轮调一次即可驱动全系统（无 sleep 无线程）；
+- `metrics.py` 的 `MetricsLedger`：逐调用成本记账（tokens/延迟/成功率，JSONL 落盘），
+  与 `../superagent-dig/02-cost-experiment/framework.py` 的 CallRecord 同构对接。

superagent_build-0.1.0/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 模式）
+"""

superagent_build-0.1.0/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)

superagent_build-0.1.0/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)