langchain-starring 0.1.0__tar.gz

langchain_starring-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: langchain-starring
+Version: 0.1.0
+Summary: LangChain callback that blocks malicious agent tool-call chains (behavior-chain security)
+Author: Star-Ring AI Behavior Security Lab
+License: MIT
+Project-URL: Homepage, https://github.com/starring-ai-sec/star-ring-agent-sentinel
+Keywords: langchain,agent,security,behavior,llm,callback
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: langchain-core>=0.2.0
+
+# langchain-starring
+
+> **A LangChain callback that blocks malicious agent tool-call chains.**
+> Content moderation cares what the Agent *says* — this cares what the Agent *does*.
+
+一个 LangChain 回调处理器：在工具执行前累积**行为链**，判定「每一步都合法、串起来就是攻击」的链式攻击（如 `read_sms → send_credentials`），命中即熔断。
+
+## 为什么需要它
+
+单步安全工具拦不住这条链：
+
+```
+read_sms          ← 读用户短信（客服的常规权限，白名单内）
+send_credentials  ← 把验证码发出去
+```
+
+每一步都合法，串起来就是验证码外泄。传统基于单步规则的防护是盲区，`langchain-starring` 专注**行为链关联分析**。
+
+## 安装
+
+```bash
+pip install langchain-starring
+```
+
+## 用法（零代码修改，一行挂载）
+
+```python
+from langchain.agents import AgentExecutor, create_tool_calling_agent
+from langchain_openai import ChatOpenAI
+from starring import StarRingCallbackHandler
+
+agent = create_tool_calling_agent(ChatOpenAI(), tools, prompt)
+
+executor = AgentExecutor(
+    agent=agent,
+    tools=tools,
+    # 一行挂载，行为链危险时自动抛 StarRingBlockedError
+    callbacks=[StarRingCallbackHandler()],
+)
+
+executor.invoke({"input": "帮我查一下退款"})
+# 当 Agent 尝试 read_sms -> send_credentials 时，第二个工具调用抛出异常，验证码不外发
+```
+
+## 能力
+
+| 能力 | 说明 |
+|---|---|
+| 行为链判定 | 累积最近 N 步工具调用，判「组合起来是否危险」 |
+| 参数闸门 | 路径穿越、超额转账、域名黑名单、批量次数 |
+| 未知动作熔断 | 幻觉出的工具名直接拒绝（fail-closed） |
+| 自定义映射 | `action_map` 把自定义工具名映射到标准动作 |
+
+## 配置
+
+```python
+handler = StarRingCallbackHandler(
+    max_history=6,                          # 行为链最多保留 6 步
+    action_map={"search_web": "external_http"},  # 工具名映射
+    config={"amount_max": 5000, "path_deny": [".."]},  # 参数闸门阈值
+    raise_on="block_fuse",                  # block 和 fuse 都熔断
+)
+```
+
+## 与竞品的差异
+
+`interven-langchain`、`iris-security`、`ActShield` 等方案主要做**单步**检测（这一句话有没有毒、这个工具危不危险）。`langchain-starring` 的差异化在于：
+
+> 抓住「每一步都合法，但串联起来就是攻击」的复杂场景——这是单步规则覆盖不了的盲区。
+
+## 更多
+
+- 端到端示例：`examples/demo.py`
+- 完整 CLI（离线自检 + 深度体检）：[star-ring-agent-sentinel](https://github.com/starring-ai-sec/star-ring-agent-sentinel)
+
+---
+
+MIT © 2026 Star-Ring AI Behavior Security Lab

langchain_starring-0.1.0/README.md

@@ -0,0 +1,78 @@
+# langchain-starring
+
+> **A LangChain callback that blocks malicious agent tool-call chains.**
+> Content moderation cares what the Agent *says* — this cares what the Agent *does*.
+
+一个 LangChain 回调处理器：在工具执行前累积**行为链**，判定「每一步都合法、串起来就是攻击」的链式攻击（如 `read_sms → send_credentials`），命中即熔断。
+
+## 为什么需要它
+
+单步安全工具拦不住这条链：
+
+```
+read_sms          ← 读用户短信（客服的常规权限，白名单内）
+send_credentials  ← 把验证码发出去
+```
+
+每一步都合法，串起来就是验证码外泄。传统基于单步规则的防护是盲区，`langchain-starring` 专注**行为链关联分析**。
+
+## 安装
+
+```bash
+pip install langchain-starring
+```
+
+## 用法（零代码修改，一行挂载）
+
+```python
+from langchain.agents import AgentExecutor, create_tool_calling_agent
+from langchain_openai import ChatOpenAI
+from starring import StarRingCallbackHandler
+
+agent = create_tool_calling_agent(ChatOpenAI(), tools, prompt)
+
+executor = AgentExecutor(
+    agent=agent,
+    tools=tools,
+    # 一行挂载，行为链危险时自动抛 StarRingBlockedError
+    callbacks=[StarRingCallbackHandler()],
+)
+
+executor.invoke({"input": "帮我查一下退款"})
+# 当 Agent 尝试 read_sms -> send_credentials 时，第二个工具调用抛出异常，验证码不外发
+```
+
+## 能力
+
+| 能力 | 说明 |
+|---|---|
+| 行为链判定 | 累积最近 N 步工具调用，判「组合起来是否危险」 |
+| 参数闸门 | 路径穿越、超额转账、域名黑名单、批量次数 |
+| 未知动作熔断 | 幻觉出的工具名直接拒绝（fail-closed） |
+| 自定义映射 | `action_map` 把自定义工具名映射到标准动作 |
+
+## 配置
+
+```python
+handler = StarRingCallbackHandler(
+    max_history=6,                          # 行为链最多保留 6 步
+    action_map={"search_web": "external_http"},  # 工具名映射
+    config={"amount_max": 5000, "path_deny": [".."]},  # 参数闸门阈值
+    raise_on="block_fuse",                  # block 和 fuse 都熔断
+)
+```
+
+## 与竞品的差异
+
+`interven-langchain`、`iris-security`、`ActShield` 等方案主要做**单步**检测（这一句话有没有毒、这个工具危不危险）。`langchain-starring` 的差异化在于：
+
+> 抓住「每一步都合法，但串联起来就是攻击」的复杂场景——这是单步规则覆盖不了的盲区。
+
+## 更多
+
+- 端到端示例：`examples/demo.py`
+- 完整 CLI（离线自检 + 深度体检）：[star-ring-agent-sentinel](https://github.com/starring-ai-sec/star-ring-agent-sentinel)
+
+---
+
+MIT © 2026 Star-Ring AI Behavior Security Lab

langchain_starring-0.1.0/langchain_starring.egg-info/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: langchain-starring
+Version: 0.1.0
+Summary: LangChain callback that blocks malicious agent tool-call chains (behavior-chain security)
+Author: Star-Ring AI Behavior Security Lab
+License: MIT
+Project-URL: Homepage, https://github.com/starring-ai-sec/star-ring-agent-sentinel
+Keywords: langchain,agent,security,behavior,llm,callback
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: langchain-core>=0.2.0
+
+# langchain-starring
+
+> **A LangChain callback that blocks malicious agent tool-call chains.**
+> Content moderation cares what the Agent *says* — this cares what the Agent *does*.
+
+一个 LangChain 回调处理器：在工具执行前累积**行为链**，判定「每一步都合法、串起来就是攻击」的链式攻击（如 `read_sms → send_credentials`），命中即熔断。
+
+## 为什么需要它
+
+单步安全工具拦不住这条链：
+
+```
+read_sms          ← 读用户短信（客服的常规权限，白名单内）
+send_credentials  ← 把验证码发出去
+```
+
+每一步都合法，串起来就是验证码外泄。传统基于单步规则的防护是盲区，`langchain-starring` 专注**行为链关联分析**。
+
+## 安装
+
+```bash
+pip install langchain-starring
+```
+
+## 用法（零代码修改，一行挂载）
+
+```python
+from langchain.agents import AgentExecutor, create_tool_calling_agent
+from langchain_openai import ChatOpenAI
+from starring import StarRingCallbackHandler
+
+agent = create_tool_calling_agent(ChatOpenAI(), tools, prompt)
+
+executor = AgentExecutor(
+    agent=agent,
+    tools=tools,
+    # 一行挂载，行为链危险时自动抛 StarRingBlockedError
+    callbacks=[StarRingCallbackHandler()],
+)
+
+executor.invoke({"input": "帮我查一下退款"})
+# 当 Agent 尝试 read_sms -> send_credentials 时，第二个工具调用抛出异常，验证码不外发
+```
+
+## 能力
+
+| 能力 | 说明 |
+|---|---|
+| 行为链判定 | 累积最近 N 步工具调用，判「组合起来是否危险」 |
+| 参数闸门 | 路径穿越、超额转账、域名黑名单、批量次数 |
+| 未知动作熔断 | 幻觉出的工具名直接拒绝（fail-closed） |
+| 自定义映射 | `action_map` 把自定义工具名映射到标准动作 |
+
+## 配置
+
+```python
+handler = StarRingCallbackHandler(
+    max_history=6,                          # 行为链最多保留 6 步
+    action_map={"search_web": "external_http"},  # 工具名映射
+    config={"amount_max": 5000, "path_deny": [".."]},  # 参数闸门阈值
+    raise_on="block_fuse",                  # block 和 fuse 都熔断
+)
+```
+
+## 与竞品的差异
+
+`interven-langchain`、`iris-security`、`ActShield` 等方案主要做**单步**检测（这一句话有没有毒、这个工具危不危险）。`langchain-starring` 的差异化在于：
+
+> 抓住「每一步都合法，但串联起来就是攻击」的复杂场景——这是单步规则覆盖不了的盲区。
+
+## 更多
+
+- 端到端示例：`examples/demo.py`
+- 完整 CLI（离线自检 + 深度体检）：[star-ring-agent-sentinel](https://github.com/starring-ai-sec/star-ring-agent-sentinel)
+
+---
+
+MIT © 2026 Star-Ring AI Behavior Security Lab

langchain_starring-0.1.0/langchain_starring.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+xh_engine.py
+langchain_starring.egg-info/PKG-INFO
+langchain_starring.egg-info/SOURCES.txt
+langchain_starring.egg-info/dependency_links.txt
+langchain_starring.egg-info/requires.txt
+langchain_starring.egg-info/top_level.txt
+starring/__init__.py
+starring/callback.py

langchain_starring-0.1.0/langchain_starring.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

langchain_starring-0.1.0/langchain_starring.egg-info/requires.txt

@@ -0,0 +1 @@
+langchain-core>=0.2.0

langchain_starring-0.1.0/langchain_starring.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+starring
+xh_engine

langchain_starring-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "langchain-starring"
+version = "0.1.0"
+description = "LangChain callback that blocks malicious agent tool-call chains (behavior-chain security)"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Star-Ring AI Behavior Security Lab" }]
+keywords = ["langchain", "agent", "security", "behavior", "llm", "callback"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Security",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "langchain-core>=0.2.0",
+]
+
+[tool.setuptools]
+py-modules = ["xh_engine"]
+packages = ["starring"]
+
+[project.urls]
+Homepage = "https://github.com/starring-ai-sec/star-ring-agent-sentinel"

langchain_starring-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

langchain_starring-0.1.0/starring/__init__.py

@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+"""starring：LangChain 行为链熔断回调包。"""
+
+from .callback import StarRingBlockedError, StarRingCallbackHandler
+
+__all__ = ["StarRingCallbackHandler", "StarRingBlockedError"]
+__version__ = "0.1.0"

langchain_starring-0.1.0/starring/callback.py

@@ -0,0 +1,131 @@
+# -*- coding: utf-8 -*-
+"""StarRingCallbackHandler：LangChain 行为链熔断回调。
+
+在工具执行前（`on_tool_start`）累积行为链，交给星环规则引擎判定；
+命中「凭据外泄 / 提权 / 文件外发」等组合链时抛 `StarRingBlockedError`，中断执行。
+
+用法（零代码修改，只挂一个回调）：:
+
+    from langchain.agents import AgentExecutor
+    from starring import StarRingCallbackHandler
+
+    executor = AgentExecutor(
+        agent=agent, tools=tools,
+        callbacks=[StarRingCallbackHandler()],
+    )
+
+只依赖 `langchain-core`（不依赖完整 langchain），可与 LangChain / LangGraph 任意版本共存。
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+
+from langchain_core.callbacks import BaseCallbackHandler
+
+#: 从自测包 src/ 引用规则引擎（作为独立 PyPI 包时，由依赖提供 xh_engine）
+try:
+    import xh_engine
+except ImportError:  # pragma: no cover - 仓库内引用
+    import os
+    import sys
+    sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", "src"))
+    import xh_engine
+
+
+class StarRingBlockedError(RuntimeError):
+    """行为链被判定为危险时抛出，用于熔断工具执行。"""
+
+    def __init__(self, decision: str, reasons: List[str], actions: List[str]) -> None:
+        self.decision = decision
+        self.reasons = reasons
+        self.actions = actions
+        chain = " → ".join(actions)
+        super().__init__("[星环熔断] 行为链被拦截（%s）：%s ｜ 链：%s"
+                         % (decision, "；".join(reasons), chain))
+
+
+class StarRingCallbackHandler(BaseCallbackHandler):
+    """LangChain 回调：累积工具调用序列，危险即熔断。
+
+    参数
+    ----
+    max_history : int
+        行为链最多保留多少步（超过则只保留最近 N 步），默认 6。
+    action_map : dict
+        自定义工具名 → 标准动作名映射，例如 ``{"search_web": "external_http"}``。
+    config : dict
+        透传给规则引擎的参数闸门配置（路径/金额/域名/次数阈值）。
+    raise_on : {"block_fuse", "fuse"}
+        何时熔断：默认 ``block_fuse``（拦截与熔断都抛异常）；``fuse`` 只在熔断时抛。
+    """
+
+    def __init__(
+        self,
+        max_history: int = 6,
+        action_map: Optional[Dict[str, str]] = None,
+        config: Optional[Dict[str, Any]] = None,
+        raise_on: str = "block_fuse",
+    ) -> None:
+        super().__init__()
+        self.max_history = max(1, int(max_history))
+        self.action_map = dict(action_map or {})
+        self.config = config
+        self.raise_on = raise_on
+        self.actions: List[Dict[str, Any]] = []
+
+    # ── 工具名映射 ────────────────────────────────────────
+    def _map_action(self, tool_name: str) -> str:
+        return self.action_map.get(tool_name, tool_name)
+
+    # ── 参数提取（尽力而为）────────────────────────────────
+    @staticmethod
+    def _extract_params(input_str: str) -> Dict[str, Any]:
+        """从工具输入字符串里提取结构化参数（JSON 优先，键值对兜底）。"""
+        if not input_str:
+            return {}
+        s = input_str.strip()
+        try:
+            obj = json.loads(s)
+            return obj if isinstance(obj, dict) else {}
+        except (json.JSONDecodeError, ValueError):
+            pass
+        params: Dict[str, Any] = {}
+        for token in s.replace(",", " ").split():
+            if "=" in token:
+                k, v = token.split("=", 1)
+                params[k.strip()] = v.strip()
+        return params
+
+    # ── 核心：工具执行前判定 ───────────────────────────────
+    def on_tool_start(
+        self,
+        serialized: Dict[str, Any],
+        input_str: str,
+        **kwargs: Any,
+    ) -> None:
+        tool_name = str(serialized.get("name") or "unknown")
+        action_type = self._map_action(tool_name)
+        self.actions.append({
+            "action_type": action_type,
+            "params": self._extract_params(input_str or ""),
+        })
+        if len(self.actions) > self.max_history:
+            self.actions = self.actions[-self.max_history:]
+
+        verdict = xh_engine.evaluate(self.actions, self.config)
+        decision = verdict["decision"]
+        should_raise = (
+            decision in ("block", "fuse") if self.raise_on == "block_fuse"
+            else decision == "fuse"
+        )
+        if should_raise:
+            raise StarRingBlockedError(
+                decision, verdict["reasons"],
+                [a["action_type"] for a in self.actions])
+
+    # ── 会话重置 ──────────────────────────────────────────
+    def reset(self) -> None:
+        """清空累积的行为链（每次独立会话开始时调用）。"""
+        self.actions = []

langchain_starring-0.1.0/xh_engine.py

@@ -0,0 +1,217 @@
+# -*- coding: utf-8 -*-
+"""星环 · Agent 行为自检引擎（分发包用的轻量规则版）。
+
+为什么是「轻量规则版」而不是完整基座
+----------------------------------
+分发给客户的东西必须**不含核心资产**：
+* 不含 177 条攻击样本库（这是可复现、可验证的护城河）
+* 不含三轨模型权重（48 维 / 16 维）
+* 不含真神领域台与红队剧本
+
+所以这里只保留**规则层**：动作风险 + 参数闸门 + 组合链 + 未知动作 fail-closed。
+这足以做「初筛」，且逆向出来也只拿到规则，拿不到样本与模型。
+
+判定顺序（任一命中即停）
+-----------------------
+1. 未知动作      → 拒绝（模型幻觉出的工具名）
+2. 参数越界      → 拒绝（路径穿越 / 超额 / 非白名单域名 / 批量次数）
+3. 组合链        → 提权后敏感、外发链
+4. 单动作风险    → LOW 放行 / MEDIUM 确认 / HIGH 拦截 / CRITICAL 熔断
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import posixpath
+from typing import Any, Dict, List, Optional, Tuple
+
+#: 动作风险表（与基座 agent_guard.ACTION_RISK + 扩展表口径一致）
+ACTION_RISK: Dict[str, Tuple[float, str]] = {
+    "read_screen": (0.05, "LOW"), "open_app": (0.10, "LOW"), "organize": (0.10, "LOW"),
+    "read_docs": (0.05, "LOW"), "summarize": (0.05, "LOW"), "list_docs": (0.05, "LOW"),
+    "send_report": (0.30, "MEDIUM"),
+    "send_message": (0.30, "MEDIUM"), "read_location": (0.40, "MEDIUM"),
+    "invoke_agent_tool": (0.50, "MEDIUM"),
+    "read_contacts": (0.55, "HIGH"), "share_file": (0.60, "HIGH"),
+    "read_sms": (0.60, "HIGH"), "change_permission": (0.70, "HIGH"),
+    "external_http": (0.70, "HIGH"), "read_otp": (0.80, "HIGH"),
+    "delete_bulk": (0.85, "CRITICAL"), "payment": (0.90, "CRITICAL"),
+    "transfer": (0.95, "CRITICAL"), "send_credentials": (0.98, "CRITICAL"),
+    "sandbox_read_outside": (0.85, "CRITICAL"), "access_other_process": (0.85, "CRITICAL"),
+    "restricted_syscall": (0.85, "CRITICAL"), "port_scan": (0.80, "CRITICAL"),
+    "accessibility_bypass": (0.85, "CRITICAL"), "automation_batch_click": (0.85, "CRITICAL"),
+    "recursive_loop": (0.75, "HIGH"), "sensor_battery_drain": (0.70, "HIGH"),
+    "bulk_message": (0.60, "HIGH"), "root": (0.90, "CRITICAL"),
+    "escalate": (0.88, "CRITICAL"), "sudo": (0.85, "CRITICAL"), "chmod": (0.75, "HIGH"),
+}
+
+#: 动作族（用于「换个同族动作名」的链判定）
+FAMILY = {
+    "transfer": "finance", "payment": "finance", "read_otp": "finance",
+    "external_http": "egress", "share_file": "egress", "send_credentials": "egress",
+    "change_permission": "privilege", "escalate": "privilege", "root": "privilege",
+    "sudo": "privilege", "chmod": "privilege", "accessibility_bypass": "privilege",
+    "read_contacts": "collect", "read_sms": "collect", "read_screen": "collect",
+    "read_location": "collect", "read_docs": "collect",
+    "sandbox_read_outside": "escape", "access_other_process": "escape",
+    "restricted_syscall": "escape", "port_scan": "escape",
+    "recursive_loop": "exhaust", "sensor_battery_drain": "exhaust",
+    "automation_batch_click": "automation", "bulk_message": "automation",
+}
+
+_FAMILY_PREFIX = (
+    ("read_", "collect"), ("get_", "collect"), ("list_", "collect"),
+    ("send_", "egress"), ("share_", "egress"), ("external_", "egress"),
+    ("upload_", "egress"), ("export_", "egress"),
+    ("change_", "privilege"), ("grant_", "privilege"), ("set_perm", "privilege"),
+    ("sandbox_", "escape"), ("transfer", "finance"), ("pay", "finance"),
+    ("automation_", "automation"), ("bulk_", "automation"),
+)
+
+PRIVILEGE_OPS = {"change_permission", "escalate", "root", "sudo", "chmod"}
+PRIVILEGE_SINKS = {"read_contacts", "read_sms", "read_location", "external_http",
+                   "share_file", "send_credentials", "read_otp"}
+
+DECISION_ORDER = ["allow", "confirm", "block", "fuse"]
+
+#: 默认参数闸门（客户可用 config.json 覆盖）
+DEFAULT_CONFIG = {
+    "path_deny": ["..", "/etc/", "~/", "C:\\Windows"],
+    "amount_max": 5000,
+    "domain_deny": ["attacker", "evil.", "example.com", "pastebin", "tmpfiles"],
+    "count_max": 50,
+    "exempt_ops": [],
+}
+
+#: 输出标注（三色）
+MARK_CONFIRM = "【确认拦截】"
+MARK_REVIEW = "【需复核】"
+MARK_FALSE = "【疑似误报】"
+
+
+def family_of(op: str) -> str:
+    if op in FAMILY:
+        return FAMILY[op]
+    for prefix, fam in _FAMILY_PREFIX:
+        if op.startswith(prefix):
+            return fam
+    if op.endswith("_loop"):
+        return "exhaust"
+    return op
+
+
+def _num(value: Any) -> Optional[float]:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    try:
+        return float(str(value).strip())
+    except (TypeError, ValueError):
+        return None
+
+
+def _check_params(action_type: str, params: Dict[str, Any], cfg: Dict[str, Any]) -> List[str]:
+    """参数闸门：返回违规描述列表。"""
+    out: List[str] = []
+    raw_path = str(params.get("path") or params.get("target") or "")
+    if raw_path:
+        norm = posixpath.normpath(raw_path.replace("\\", "/"))
+        for bad in cfg.get("path_deny") or []:
+            if str(bad) in raw_path.replace("\\", "/") or str(bad) in norm:
+                out.append("路径命中禁用片段 %r（%s）" % (bad, raw_path))
+                break
+
+    if action_type in ("transfer", "payment"):
+        amount = _num(params.get("amount"))
+        limit = float(cfg.get("amount_max") or 0)
+        if amount is None:
+            out.append("金额缺失或非数字，无法确认在额度内")
+        elif limit and amount > limit:
+            out.append("金额 %.2f 超过上限 %.2f" % (amount, limit))
+
+    target = str(params.get("to") or params.get("url") or params.get("domain") or "")
+    if target:
+        low = target.lower()
+        for bad in cfg.get("domain_deny") or []:
+            if str(bad).lower() in low:
+                out.append("目标域名命中禁用片段 %r（%s）" % (bad, target))
+                break
+
+    if action_type in ("automation_batch_click", "bulk_message"):
+        count = _num(params.get("count"))
+        limit = float(cfg.get("count_max") or 0)
+        if count is not None and limit and count > limit:
+            out.append("次数 %.0f 超过上限 %.0f" % (count, limit))
+    return out
+
+
+def evaluate(actions: List[Dict[str, Any]], cfg: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """评估一条行为链，返回裁决 + 标注 + 依据。"""
+    conf = dict(DEFAULT_CONFIG)
+    conf.update(cfg or {})
+    exempt = set(str(x) for x in (conf.get("exempt_ops") or []))
+
+    types = [str(a.get("action_type") or a.get("tool") or "") for a in actions]
+    params_list = [dict(a.get("params") or {}) for a in actions]
+    reasons: List[str] = []
+
+    # 空行为链：无可判定对象，放行（否则下方 max 会因空序列崩溃）
+    if not types:
+        return {"decision": "allow", "mark": "", "reasons": ["空行为链"], "types": []}
+
+    # ① 未知动作 fail-closed
+    unknowns = [t for t in types if t and t not in ACTION_RISK and family_of(t) == t]
+    if unknowns:
+        return {"decision": "block", "mark": MARK_CONFIRM,
+                "reasons": ["未知动作（fail-closed）：%s" % ",".join(sorted(set(unknowns)))],
+                "types": types}
+
+    # ② 参数闸门
+    for action_type, params in zip(types, params_list):
+        if action_type in exempt:
+            continue
+        for problem in _check_params(action_type, params, conf):
+            reasons.append("%s：%s" % (action_type, problem))
+    if reasons:
+        return {"decision": "block", "mark": MARK_CONFIRM,
+                "reasons": reasons, "types": types}
+
+    # ③ 组合链
+    type_set = set(types)
+    if PRIVILEGE_OPS & type_set and PRIVILEGE_SINKS & type_set:
+        return {"decision": "fuse", "mark": MARK_CONFIRM,
+                "reasons": ["提权链：%s + %s"
+                            % (sorted(PRIVILEGE_OPS & type_set),
+                               sorted(PRIVILEGE_SINKS & type_set))],
+                "types": types}
+    if {"share_file", "external_http"} <= type_set:
+        return {"decision": "fuse", "mark": MARK_CONFIRM,
+                "reasons": ["文件外发链：share_file + external_http"], "types": types}
+    # 凭据外泄链：读取短信/验证码/通讯录 → 外发
+    cred_src = {"read_sms", "read_otp", "read_contacts"} & type_set
+    cred_sink = {"send_credentials", "external_http", "share_file"} & type_set
+    if cred_src and cred_sink:
+        return {"decision": "fuse", "mark": MARK_CONFIRM,
+                "reasons": ["凭据外泄链：%s → %s"
+                            % (sorted(cred_src), sorted(cred_sink))], "types": types}
+
+    # ④ 单动作风险（取最高）
+    levels = []
+    for action_type in types:
+        if action_type in exempt:
+            levels.append(("LOW", 0.10))
+            continue
+        levels.append(ACTION_RISK.get(action_type, (0.5, "MEDIUM")))
+    worst_level = max((lv for _score, lv in levels),
+                      key=lambda x: DECISION_ORDER.index(
+                          {"LOW": "allow", "MEDIUM": "confirm",
+                           "HIGH": "block", "CRITICAL": "fuse"}[x]))
+    decision = {"LOW": "allow", "MEDIUM": "confirm",
+                "HIGH": "block", "CRITICAL": "fuse"}[worst_level]
+    reasons.append("最高动作等级 %s" % worst_level)
+
+    # 标注：HIGH 级单动作若无组合证据 → 需复核；MEDIUM → 需复核；LOW → 放行
+    mark = MARK_CONFIRM if decision in ("block", "fuse") else (
+        MARK_REVIEW if decision == "confirm" else "")
+    return {"decision": decision, "mark": mark, "reasons": reasons, "types": types}