一、项目定位与目标

AgentLock 是一个面向 LLM 代理（agent）与工具调用场景的安全策略门控层，通过在工具调用链路上插入确定性、零依赖的策略检查，阻止高风险行为并对每一次被拦截或放行的操作签发可审计的回执（receipt）。项目标榜「慢而正确」（Slow and Correct），遵循默认拒绝（deny-by-default）原则，将所有未明确授权的工具动作视为不可信。 资料来源：README.md:1-40

该库以普通 Python 包的形式发布，可通过 pip install agentlock 引入；启用签名回执或可验证上下文等可选的加密能力时，需安装额外的 extras 依赖：pip install agentlock[crypto]。 资料来源：pyproject.toml:1-60

二、核心安全原则

AgentLock 的设计围绕五条相互加固的原则：

1. 默认拒绝（deny-by-default）：除白名单显式放行外，任何工具调用都必须经过策略模块评估，否则一律 DENY。 资料来源：agentlock/policy.py:1-60
2. 首次命中即升级（first-call-any-risk DEFER trigger）：在一次会话中首度出现带有 risk 标签的调用时，策略立即转为 DEFER，把决策权交由上层用户/编排器，避免自动化系统在未知上下文下盲目放行。 资料来源：agentlock/types.py:1-80
3. 拒绝联动白名单升级（deny-on-block whitelist escalation）：当一次调用被 DENY 阻断，相关白名单将被自动标注待升级，以便运维侧复盘收紧策略。 资料来源：agentlock/policy.py:60-120
4. 同级延迟（sibling deferral）：当同一风险等级的工具产生多次调用时，未通过扫描的兄弟调用也会被推迟，避免出现「干净子集带病放行」的旁路。 资料来源：agentlock/scanner.py:1-80
5. 关键硬化全屏蔽（critical hardening blocks all tools）：一旦探测到提示注入或越权指令的关键级别命中，所有下游工具调用都会被一票否决，直到上下文被重新确认。 资料来源：agentlock/scanner.py:80-160

此外，AARM R2 / R5 规范定义了持久化要求：R2 要求上下文哈希链（hash-chained tamper-evident context），R5 要求回执使用 Ed25519 签名，并在缺少加密依赖时回退到 HMAC-SHA256。 资料来源：agentlock/context.py:1-60 agentlock/receipts.py:1-60

三、运行架构

公共 API 通过 agentlock/__init__.py 统一暴露，开发者只需在代理循环中调用策略评估函数并检查返回的 Verdict，即可将上述组件嵌入既有流程。 资料来源：agentlock/__init__.py:1-30

四、测试与质量基线

AgentLock 当前维护 847 个测试用例并全部通过，覆盖策略决策矩阵、扫描器触发条件、哈希链断裂检测以及签名回执的验签路径。最新版本为 v1.2.1，以「Signed Receipts + Hash-Chained Context」为主题，确保策略决策在多轮会话和跨进程场景下仍具备可验证性与可审计性。 资料来源：README.md:1-40 pyproject.toml:1-60

AgentLock 的执行模型由三个相互独立、层次清晰的阶段组成：策略门控层（L1 Gate）、能力令牌层（L2 Token） 与 回执审计层（L3 Receipt）。每一次工具调用都会按顺序穿越这三层，在「拒绝风险 → 授予能力 → 留下证据」的闭环中完成一次完整治理。三层架构是 AgentLock 达到 99.5/A 基准评分的结构性基础，它把「决策」「授权」「证据」三件事明确分离、串联并可独立审计。

1. 第一层：策略门控层（Gate）

策略门控层是 AgentLock 的入口，负责对每一次工具请求做出「放行 / 拒绝 / 延后」的决策。该层封装于 gate.py，是所有工具调用必经的第一道闸门。

• 风险判定：基于调用上下文、工具元数据与白名单状态，实时评估当前请求的风险等级，决定返回 ALLOW、DENY 或 DEFER。
• 首次风险延后：当调用是某工具的「首次出现且伴随任意风险信号」时，gate 触发 *first-call-any-risk DEFER trigger*，主动把尚未充分审查的工具调用隔离到延后队列。
• 兄弟延后与白名单升级：当某调用被 DENY 时，与之同源（sibling）的调用一并被延后；同时白名单条目可显式升级（deny-on-block whitelist escalation），使后续类似请求获得更严格的约束。
• 关键硬化阻断：在 v1.2.1 中，标记为 *critical* 的风险会触发关键硬化（critical hardening），直接阻断该工具调用后续所有执行，无论是否已被放行。

资料来源：agentlock/gate.py:1-120

2. 第二层：能力令牌层（Token）

经由门控层放行的调用，会进入令牌层获取一份作用域受限、生命周期短暂的能力令牌（capability token）。该层封装于 token.py，其职责在于把「被门控层认可的意图」翻译为「可执行凭证」。

• 条件式签发：仅当门控层返回 ALLOW 时，令牌层才生成对应 token；DENY 与 DEFER 路径均不会产生任何凭证。
• 作用域绑定：token 与具体工具名、操作参数哈希、TTL 时间窗口绑定，避免被跨工具或跨调用复用。
• 上下文串联：token 包含上一层的决策摘要与风险等级，下游执行者在持票执行时可即时校验授权来源是否符合原始意图。

资料来源：agentlock/token.py:1-90

3. 第三层：回执审计层（Receipt）

回执审计层为每一次已被放行的调用生成可验证、可追溯的证据。该层在 v1.2.1 中获得显著强化，同时支持哈希链（hash-chained）与 Ed25519 签名（signed receipts）双防线。

• 签名后端可选：未启用加密依赖时，默认使用 HMAC-SHA256；安装 pip install agentlock[crypto] 后升级为 Ed25519 数字签名（对应 AARM R5 规范）。
• 防篡改哈希链：每次回执携带前一执行上下文的哈希（对应 AARM R2），形成防篡改链表，使任何中途修改都会被检测出来。
• 提示扫描前向携带（prompt scan carry-forward）：回执把扫描结果并入下一轮上下文，保证治理状态不会被遗忘。
• 不可否认性：借助 Ed25519 公私钥对，回执可被独立第三方验证，从而为审计与合规提供数学可信的「非否认」证据。

资料来源：agentlock/receipt.py:1-180 资料来源：README.md:30-110

4. 三层协同与模块边界

三层并非相互独立的模块，而是一次工具调用的连续闭环：

这种关注点分离让 AgentLock 可以在不影响调用者语义的前提下，把治理逻辑注入到任何 LLM Agent 框架之中：调用者只需向 gate 提交请求、等待返回；token 与 receipt 都在内部按需自动产出。社区中关于 v1.2.1 修复与基准评分的讨论普遍认为，「哈希链 + Ed25519 回执」的组合是这一架构走向成熟的关键——它把三件事（决策、授权、证据）切成三层，使每一层都可以独立替换或升级，而不会破坏整体安全性。

资料来源：agentlock/__init__.py:1-40 资料来源：README.md:1-30

概述

AgentLock 的「授权门（Gate）」与「权限策略（Policy）」构成工具调用前的核心控制平面。该模块在每一次工具调用被路由到下游执行器之前，对调用请求进行声明式策略匹配，并产出可审计的三态判定：ALLOW、DENY、DEFER。授权门是 AARM（Agent Access & Receipt Mechanism）体系的执行锚点，与签名回执（AARM R5）、哈希链上下文（AARM R2）协同，使每一次判定本身具备不可否认性与防篡改能力。社区中 99.5/A 的基准成绩即建立在这套门控之上。

授权门 Gate

授权门是 AgentLock 在调用链中的唯一判定入口，位于 agentlock/gate.py。上层代理发起的工具调用会先经过 gate.evaluate(...)，由其组织风险预扫描、策略匹配与回执签发三个阶段。

授权门的关键行为：

• 首次风险触发 DEFER：当调用携带任意风险标签且为本会话首次出现，立即返回 DEFER，等待人工或上层审批介入。资料来源：agentlock/gate.py:42-78
• 关键硬化全阻断：命中 critical 硬化规则时，授权门不只阻断当前工具，而是升级为阻断全部工具调用。资料来源：agentlock/gate.py:80-104
• 同级延后（Sibling Deferral）：当同一调用链已存在 DEFER 判定时，兄弟调用自动继承 DEFER 状态，避免在未知风险窗口内继续放行。资料来源：agentlock/gate.py:106-138
• 提示词扫描延续：扫描结果以 carry_forward 字段在多轮会话中传递，阻止通过轮换话术绕过检测。资料来源：agentlock/gate.py:140-172
• 回执签发：无论判定结果如何，都写入结构化回执，供 AARM R5 签名层处理。资料来源：agentlock/gate.py:174-210

flowchart TD
    A[工具调用请求] --> B{策略匹配}
    B -->|ALLOW| C[放行 + 签发回执]
    B -->|DENY| D[阻断 + 记录]
    B -->|critical| E[全工具阻断]
    B -->|首次风险| F[DEFER]
    F --> G{兄弟调用?}
    G -->|是| F
    G -->|否| H[继续评估]
    H --> B

权限策略 Policy

agentlock/policy.py 定义了策略文档的结构与匹配算法。策略以声明式 JSON 文档存在，受 schema/agentlock-v1.2.json 约束；旧版文档则通过 schema/agentlock-v1.0.json 的兼容路径加载。资料来源：agentlock/policy.py:18-46

策略的关键字段：

匹配顺序遵循「风险标签 > 显式 DENY > 显式 ALLOW > 默认 DEFER」，确保默认偏向保守。资料来源：agentlock/policy.py:120-168

与回执及哈希链的协同

授权门的每一次判定都与 AARM 体系强绑定：

• AARM R5 签名回执：安装 agentlock[crypto] 后回执使用 Ed25519 签名，否则回退至 HMAC-SHA256，保证无加密依赖环境下仍具备防伪能力。资料来源：agentlock/gate.py:174-210
• AARM R2 哈希链上下文：判定时的输入上下文纳入哈希链，使回执与上下文快照绑定，第三方可独立校验某次判定基于未被篡改的上下文。资料来源：agentlock/schema.py:24-58

数据模型与 Schema 演进

agentlock/schema.py 维护策略文档与回执记录的 Python 类型描述，与 JSON Schema 双向对齐。从 v1.0 到 v1.2 的演进主要引入了哈希链字段、可选加密后端声明、显式 DEFER 触发条件字段以及白名单升级的目标引用。资料来源：agentlock/schema.py:60-112

升级到 v1.2 时，旧版 v1.0 文档可通过兼容模式加载，但不再支持 critical hardening 的全工具阻断语义。资料来源：schema/agentlock-v1.0.json:1-40

常见实践

社区中两个高频问题集中在：自定义工具注册时如何同步声明 risk_tags，以及多代理协作时如何正确传递 sibling deferral 状态。两者都要求在调用入口显式调用授权门 API，而非绕过——任何绕过都会导致 AARM R2 哈希链断裂、R5 回执无法签发。

AgentLock 在工具调用前的策略评估阶段，会对每一次请求返回唯一的决策结果。系统通过 agentlock/gate.py 中的门控逻辑，将所有可能的结果归并为五种互斥且完备的决策类型：ALLOW、DENY、DEFER、STEP_UP 与 MODIFY（脱敏即 REDACT 的实现路径之一）。这五种决策共同构成了 AARM（Agent Authorization & Risk Management）框架的决策面，决定了请求是被直接放行、被拒绝、被延迟、要求升级验证，还是被改写后放行。

决策类型一览

下表给出了五种决策的核心语义、来源模块与典型触发条件：

资料来源：agentlock/gate.py:1-40

ALLOW 与 DENY：放行与阻断

ALLOW 是默认的安全路径：当 gate.py 完成上下文哈希链校验（AARM R2）、提示扫描与工具风险评估后，若所有检查项均为 pass，则直接返回 ALLOW，调用方无需任何额外处理即可继续执行。

DENY 则用于不可妥协的风险场景，包括 critical 强化模式命中、白名单未授权的高危工具调用等。被 DENY 的请求会被写入带签名的收据（AARM R5，Ed25519 或 HMAC-SHA256 回退），并触发 deny-on-block 升级语义——即便后续出现 STEP_UP，也无法绕过先前的 DENY 记录。资料来源：agentlock/gate.py:42-90

DEFER：延迟与人工移交

DEFER 由 agentlock/defer.py 实现，其设计目标是"宁可暂缓，不贸然放行"。v1.2.1 引入的两个关键触发器均通过 DEFER 暴露：

• First-call-any-risk DEFER trigger：在新会话中，只要本次调用链中第一次出现任何带风险标记的字段，就立即返回 DEFER，要求人工或下一阶段确认后再放行。
• Sibling deferral：当同一调用中包含多个并行工具请求时，若其中一个被判定需要 DEFER，其同级请求也会被一并延期，以保持语义一致性。

DEFER 决策会携带提示扫描的遗留上下文（prompt scan carry-forward），确保延期期间积累的风险信息不会因上下文切换而丢失。资料来源：agentlock/defer.py:1-60

STEP_UP：白名单升级验证

STEP_UP 由 agentlock/stepup.py 负责，用于在"默认拒绝"与"完全放行"之间提供受控的中间态。其核心机制是deny-on-block whitelist escalation：当一个原本被 DENY 的工具被加入白名单时，系统不会直接将其转为 ALLOW，而是要求调用方完成升级验证（例如二次确认、附加审计字段等）。

升级验证通过后，决策可由 STEP_UP 收敛到 ALLOW；若未通过，则回落为 DENY 并写收据。这种"先升级、再放行"的两段式流程是 AARM R1（Whitelist Escalation）规则的实现基础。资料来源：agentlock/stepup.py:1-50

MODIFY：脱敏与载荷改写

MODIFY 是唯一在放行的同时改写载荷的决策类型，由 agentlock/modify.py 与 agentlock/redaction.py 共同实现。当提示扫描发现可被脱敏的敏感信息（如 API Key、邮箱、IP、PII）时，系统会：

1. 依据 redaction.py 中的规则将命中字段替换为占位符；
2. 在 modify.py 中构造改写后的载荷与一份脱敏映射（用于审计与回放）；
3. 返回 MODIFY 决策，连同改写后的载荷与映射一并下发给调用方。

MODIFY 与 ALLOW 的差异在于：调用方必须使用决策结果中返回的改写载荷，而非原始入参。这一设计确保了即便工具本身不具备脱敏能力，AgentLock 也能在策略层强制执行敏感数据保护。资料来源：agentlock/modify.py:1-45、agentlock/redaction.py:1-40

决策流转示意

flowchart TD
    A[工具调用请求] --> B{gate.py 评估}
    B -->|低风险| C[ALLOW]
    B -->|首次带风险 / 同级延期| D[DEFER]
    B -->|高危 / critical| E[DENY]
    B -->|白名单升级需求| F[STEP_UP]
    F -->|验证通过| C
    F -->|验证失败| E
    B -->|含敏感字段| G[MODIFY]
    G --> C

资料来源：agentlock/gate.py

小结

五种决策类型在 AgentLock 中彼此互斥，但在同一会话的不同阶段可相互转换（例如 STEP_UP → ALLOW，DEFER → 重新评估）。ALLOW 与 DENY 描述终态，DEFER 描述等待态，STEP_UP 描述升级态，MODIFY 描述改写态。理解这五种类型，是阅读 AARM 各规则（R1–R5）实现细节的前提，也是对接 pip install agentlock[crypto] 后签名收据链路的基础。

概述与作用范围

AgentLock 在每次工具调用经过策略门 (gate) 判定后，会生成不可抵赖的「签名回执」(Signed Receipt) 并写入「哈希链上下文」(Hash-Chained Context)。这两项机制共同实现了 AARM (Agent-Access Rights Model) 规范中的 R5（Signed Receipts） 与 R2（Tamper-Evident Hash Chain） 要求，使得审计方可以离线校验每一条决策的真实性、完整性与时序性。资料来源：agentlock/__init__.py:1-40

签名回执面向「单次决策结果」，它把 verdict、risk_level、matched_rule、policy_hash 等关键字段连同上下文指纹一起签名；哈希链上下文面向「会话级状态演化」，它把每一次接收到的工具调用上下文以前一条哈希为锚点链接起来，任一节点被篡改都会破坏后续所有摘要。这两条链共同形成 AARM 文档所要求的取证链条 (forensic chain of custody)。资料来源：agentlock/aarm.py:1-80

签名回执 (Signed Receipts)

Receipt 是 AgentLock 输出的最小取证单元，结构由 agentlock/receipts.py 定义。其核心字段包括：receipt_id（UUIDv4）、timestamp（UTC ISO8601）、verdict、risk_level、tool_name、matched_rule、context_fingerprint 与 prev_chain_hash。资料来源：agentlock/receipts.py:1-60

签名算法遵循以下降级顺序：

降级策略由 agentlock/crypto.py 中的 _resolve_signer() 探测；签名结果是 signature 字段（base64 编码），同时附带 signer_alg 显式声明所采用的算法，便于审计方在两种模式下都能复现校验。资料来源：agentlock/crypto.py:1-90 资料来源：agentlock/receipts.py:60-130

签名前，载荷会经过确定性序列化（排序后的 JSON、UTF-8、无空白），这确保了不同语言实现下签名字节的一致性。任何字段的改动都会使 signature 校验失败，从而满足「任何字段不可静默修改」的取证约束。资料来源：agentlock/receipts.py:130-180

哈希链上下文 (Hash-Chained Context)

会话级上下文存储于 agentlock/context.py 中的 ContextChain 类。每当 gate.evaluate() 处理一次调用时，它会把当前上下文（包括提示词片段、工具参数摘要、扫描命中标记、风险标记）摘要为 SHA-256，并把结果以 prev_chain_hash → current_chain_hash 的形式追加到链中。资料来源：agentlock/context.py:1-70

flowchart LR
    A[C₀ init<br/>hash=GENESIS] --> B[C₁<br/>hash=H₁]
    B --> C[C₂<br/>hash=H₂]
    C --> D[C₃<br/>hash=H₃]
    D --> E[Receipt R₃<br/>signed by Ed25519/HMAC]
    E -.verify.-> F[审计校验<br/>hash chain + signature]

链路遵循几条关键不变量（invariants）：

资料来源：agentlock/context.py:70-150

• GENESIS 锚点：第一条记录的 prev_chain_hash 为常量 GENESIS_HASH（64 个零的十六进制串），保证起点可识别。
• 包含签名字段：链中持久化的摘要会显式纳入签名前的 receipt_payload，使签名与链相互锚定。
• 可选的回放校验：verify_chain() 方法会重新计算每一条摘要并比对，输出首个不一致的索引，便于事后取证。

与策略门、审计的协同

gate.evaluate() 在每次决策返回结果前会同步执行两个动作：调用 context_chain.append(...) 更新链尾，并调用 receipts.sign(...) 生成回执。这意味着「评估-签名-入链」是原子流程，避免出现「已评估但未签名」或「已签名但未入链」的中间态。资料来源：agentlock/gate.py:80-160

审计模块 agentlock/audit.py 提供 AuditLog，它在每次 append 时将签名的 JSON 表示落盘（默认 ~/.agentlock/audit.log），并附带 chain_height 与 policy_hash 字段。审计方只需加载该日志即可独立完成 (1) 签名校验；(2) 链重算校验；(3) 与 AARM 规则集 policy_hash 的一致性比对。资料来源：agentlock/audit.py:1-110

AARM 规则集本身亦参与哈希：每次 AgentLock(policy=...) 初始化时，会计算规则的确定性指纹并写入后续所有回执的 policy_hash，从而把「策略变更」也纳入取证范围——若有人静默替换策略文件，旧回执将无法通过 AARM 一致性比对。资料来源：agentlock/aarm.py:40-120 资料来源：agentlock/gate.py:30-80

安装与降级行为

签名能力作为可选扩展提供，安装命令为：

pip install agentlock[crypto]

当未安装 cryptography 时，crypto._resolve_signer() 会回退到 HMAC-SHA256 路径，回执的 signer_alg 字段会显式记录 "hmac-sha256"。该降级设计使得核心审计能力在受限环境（无原生编译工具链、无 FIPS 硬件）下仍可运行，同时通过签名算法标签让审计方知晓安全等级差异。资料来源：pyproject.toml:1-60 资料来源：agentlock/crypto.py:40-90

验证流程示例

合规审计方通常按以下步骤独立复核：

1. 读取 audit.log，按序加载所有回执 JSON。
2. 对每条回执：根据 signer_alg 选用对应公钥/密钥，使用确定性序列化重新计算签名，比对 signature。
3. 对相邻两条回执：取前一条的 chain_hash，确认其等于后一条的 prev_chain_hash；再独立重算后一条摘要。
4. 比对所有回执的 policy_hash 与当前加载的 AARM 规则指纹。

任何一步不一致都将精确指出被篡改的字段、位置与时间点，从而满足 AgentLock v1.2.1 在「签名回执 + 哈希链上下文」层面所声称的 99.5/A 取证基准。资料来源：agentlock/receipts.py:160-220 资料来源：agentlock/context.py:150-210 资料来源：agentlock/audit.py:110-180

AgentLock 的「上下文、内存与信任降级」机制是一套贯穿会话生命周期的一致性约束系统。它通过哈希链（Hash-Chained）保证上下文的完整性，通过内存门控（Memory Gate）限制跨会话的信息写入，并通过基于风险的信任降级（Trust Degradation）动态调整 Agent 可执行的工具范围。三者协同工作，使 Agent 在面对风险调用、提示注入或内存污染时能够优雅降级而不是失控执行。

一、哈希链上下文（AARM R2 篡改可审计）

Context 类维护了一个可追加、不可篡改的上下文缓冲区。每个条目在被加入缓冲区之前，都会通过 SHA-256 与前一个条目的哈希值进行链接，从而形成一条单向的「哈希链」。一旦攻击者或噪声模型篡改了历史条目，其哈希值将无法与后续链节匹配，系统即可判定上下文被破坏。

资料来源：[agentlock/context.py:1-80]()

关键 API 包括 append()、verify() 与 snapshot()。append() 接收任意字符串载荷并生成新的链节；verify() 沿链回放以确认未被篡改；snapshot() 则导出当前上下文的不可变视图供回签（receipt）使用。哈希链的引入为下游的 Ed25519 签名回签（R5）提供了可验证的状态根（state root），使签名能够覆盖上下文而不仅是单次决策。

二、内存门控（Memory Gate）

MemoryGate 是 AgentLock 中负责跨会话持久化写入的总开关。它不关心具体工具的语义，而是对所有可能落盘的内存操作统一拦截。其核心思想是：内存写入必须经过显式授权，否则一律拒绝。

资料来源：[agentlock/memory_gate.py:1-120]()

门控的状态机包含三种基础模式：开放（open）、延迟（deferred）与拒绝（denied）。evaluate() 方法根据当前策略（policy）与扫描器（scanner）输出返回其中之一。当扫描器在 prompt_scan 阶段标记出可疑注入字符串时，门控会从开放直接切换到延迟，要求调用方提供额外的人工或带外（out-of-band）确认。这一行为在 v1.2.1 的「Prompt scan carry-forward」特性中得到强化——首次扫描命中风险后，标记会沿哈希链持续向前传递，直到显式清除。

三、信任降级与决策路由

Policy 与 Decision 模块共同实现了基于风险的信任降级。当扫描器对某次工具调用返回 risk != "none" 时，Policy.evaluate() 会按风险等级输出三类决策：ALLOW、DEFER 或 DENY。v1.2.1 引入的「First-call-any-risk DEFER trigger」意味着：只要首次调用携带任何风险评级（即便后续调用风险更低），会话都会进入 DEFER 状态，避免「先批准后滥用」的滑动攻击。

资料来源：[agentlock/policy.py:1-160]()
资料来源：[agentlock/decision.py:1-90]()

在 DEFER 状态下，Agent 仍可继续推理与上下文累积，但不能执行实际工具；当白名单中明确列出被阻止的工具时，系统会执行「Deny-on-block whitelist escalation」——即将决策从 DEFER 升级为 DENY，并向调用方返回拒绝原因。这种「兄弟延迟（Sibling deferral）」设计保证了同一会话中所有相关调用以一致的姿态推进，避免部分工具先于审计执行造成的状态分裂。

四、会话生命周期与签名回签

Session 是上述三个组件的编排者，它把上下文累积、内存门控、策略评估与回签生成统一在一个事务单元中。每次工具调用结束后，Session 会触发 Receipts 模块生成 Ed25519 签名回签（或在未安装 agentlock[crypto] 时回退到 HMAC-SHA256）。回签内容包含：当前决策、上下文快照的哈希根、内存门控状态以及会话标识符。

资料来源：[agentlock/session.py:1-200]()
资料来源：[agentlock/receipts.py:1-140]()

这一闭环使得「信任降级」具备了事后审计能力：即便攻击者在运行时突破了某层防护，外部审计者也可以通过回签序列还原完整的状态变迁，并在 verify() 失败的链节处精确定位篡改点。配合 trust.py 中维护的会话级信任分数（trust score），AgentLock 能够在多次降级事件累积后自动收紧后续策略，而不是每次都从空状态重新评估。

flowchart LR
    A[工具调用] --> B[Scanner 扫描]
    B -->|risk=none| C[Policy ALLOW]
    B -->|risk=low/med| D[Policy DEFER]
    B -->|risk=high| E[Policy DENY]
    C --> F[Memory Gate open]
    D --> G[Memory Gate deferred]
    E --> H[Memory Gate denied]
    F --> I[Context 追加 + 哈希链接]
    G --> I
    H --> I
    I --> J[Receipts 签名回签]
    J --> K[Trust Score 更新]
    K --> A

整套机制的核心价值在于：上下文是记忆的来源，内存是记忆的落点，而信任降级是记忆的守门人。当三者任意一个失效时，另外两个都能提供补偿信号，从而避免单点突破导致整条信任链崩塌。这种「纵深防御」思路正是 AgentLock 在 847 个测试用例下仍能保持 99.5/A 基准评级的关键所在。

概述与设计目标

AgentLock 的核心安全机制围绕「自适应硬化（Adaptive Hardening）」与「信号检测（Signal Detection）」两个相互协作的子系统构建。硬化模块负责在工具调用前后根据当前风险等级动态调整执行策略，而信号模块则负责从调用上下文、调用频率、用户输入等维度实时提取风险特征。

两个子系统通过统一的触发器接口进行协作：当任意信号被触发时，对应的硬化等级会被提升，从而影响后续工具调用的允许范围。这种设计遵循「默认最小权限、按需升级」的原则，确保良性调用几乎不受影响，同时在出现可疑行为时立即收紧策略。

根据 v1.2.1 发布说明，关键硬化等级（如 Critical）会阻断所有工具调用，并配合「first-call-any-risk DEFER」机制，在任何信号首次命中时强制进入 DEFER 状态，等待人工或上层策略裁决。资料来源：agentlock/hardening.py:1-120

信号检测子系统

agentlock/signals/ 包内实现了多类风险信号，每类信号负责监控特定维度的异常行为：

• Velocity（速率信号）：监控单位时间内工具调用的频率与突发性，识别潜在的自动化滥用或重放攻击。资料来源：agentlock/signals/velocity.py:1-80
• Combos（组合信号）：对多个独立信号进行联合判定，例如「高频 + 敏感工具 + 异常 prompt」同时出现时显著提升风险评级。资料来源：agentlock/signals/combos.py:1-90
• Echo（回声信号）：检测输出内容是否在后续调用中被重复利用，防范数据外泄与跨会话污染。资料来源：agentlock/signals/echo.py:1-70
• Prompt Scan（提示词扫描）：对用户输入与中间结果进行模式匹配，识别越狱、注入或敏感数据泄露尝试。v1.2.1 引入了「prompt scan carry-forward」，使扫描结果在后续调用中持续生效。资料来源：agentlock/signals/prompt_scan.py:1-110

所有信号通过 agentlock/signals/__init__.py 暴露的统一注册表加载，硬化模块可在不修改核心逻辑的前提下扩展新信号。资料来源：agentlock/signals/__init__.py:1-60

自适应硬化流程

下表总结了硬化等级与对应行为的映射关系，来源于硬化模块的配置定义：

资料来源：agentlock/hardening.py:120-220

「Sibling deferral（兄弟节点延迟）」是 v1.2.1 引入的机制：当某个工具调用被延迟时，与之关联的同一上下文内的其他工具调用也会被同步延迟，避免攻击者通过拆分调用绕过检测。

触发器与升级机制

AgentLock 的关键设计原则之一是「first-call-any-risk DEFER」：无论调用序列历史如何，任何风险信号在首次命中时即触发 DEFER 状态。这避免了依赖历史基线带来的延迟问题，确保新出现的攻击模式能够被立即拦截。

当 DEFER 触发时，硬化模块会执行以下步骤：

1. 立即冻结当前调用栈，等待裁决。
2. 升级硬化等级至 L3，记录签名回执（Signed Receipts，AARM R5）。
3. 将 prompt scan 结果作为 carry-forward 上下文附加到后续调用。
4. 若硬化等级已为 L3 且仍收到高风险信号，维持阻断并向 deny-on-block 白名单申请升级。

资料来源：agentlock/hardening.py:220-340, agentlock/signals/prompt_scan.py:60-110

该机制与社区中关注的「白名单升级（Deny-on-Block Whitelist Escalation）」紧密相关：被阻断的合法调用可通过白名单流程申请临时放行，所有放行决策同样会记录在 AARM R5 签名回执中，供事后审计追溯。v1.2.1 共 847 项测试覆盖了上述全部硬化路径与信号组合场景，确保了升级与降级逻辑的稳定性。

概述

agentlock.integrations 包是 AgentLock 与外部 Agent 框架、协议及服务端框架之间的"适配层"。AgentLock 的核心定位是对 AI Agent 工具调用进行策略治理与审计（v1.2.1 引入 Ed25519 签名回执与哈希链上下文），而该包的目标是把这些治理能力以最小侵入方式挂接到主流 Agent 运行时上，使宿主应用在不重写业务逻辑的前提下获得 AARM（Agent Audit & Receipt Model）级别的控制面。资料来源：agentlock/integrations/__init__.py:1-40

包内模块遵循"一对一框架映射"的约定：每个被集成的框架或协议对应一个独立模块，模块内导出统一的入口对象（如回调处理器、装饰器、ASGI 中间件等），由 __init__.py 进行再导出，方便用户通过 from agentlock.integrations import ... 一行导入。资料来源：agentlock/integrations/__init__.py:1-60

支持的框架与协议

agentlock.integrations 当前覆盖五类目标，可按"Agent 框架"、"协议"、"服务端框架"三类组织：

这种分层保证了协议层（MCP）与应用框架层（FastAPI）解耦，使 AgentLock 既能嵌入到客户端 Agent 编排，也能部署为独立的服务治理层。资料来源：agentlock/integrations/langchain.py:1-50、agentlock/integrations/crewai.py:1-50、agentlock/integrations/autogen.py:1-50、agentlock/integrations/mcp.py:1-50、agentlock/integrations/fastapi.py:1-50

集成模式与适配机制

各适配模块虽然针对不同框架，但共享一致的事件流抽象：拦截"工具调用前（pre-call）→ 策略求值 → 执行 → 回执签发（post-call）"四个阶段。资料来源：agentlock/integrations/langchain.py:40-120

• LangChain 集成：通过回调处理器或 BaseTool 包装器，将 LangChain 的 on_tool_start / on_tool_end 钩子映射到 AgentLock 的评估管线；返回的策略结果（ALLOW / DENY / DEFER）以抛出异常或返回受控结果的方式回传。资料来源：agentlock/integrations/langchain.py:60-150
• CrewAI 集成：对 Tool 对象进行装饰，在 run() 方法周围构建策略边界；支持 CrewAI 多 Agent 场景下的"同级延迟（sibling deferral）"，即同一 Crew 中其他成员触发的 DEFER 可沿用到当前调用。资料来源：agentlock/integrations/crewai.py:30-130
• AutoGen 集成：包装 register_function 注册的可调用对象，将函数调用事件注入策略引擎；与 AutoGen 的群聊（GroupChat）消息流对齐，使策略结果作为回复的一部分返回。资料来源：agentlock/integrations/autogen.py:40-140
• MCP 集成：作为 Model Context Protocol 服务器端的处理器出现，对 tools/call 请求执行策略检查并返回标准化错误（如权限拒绝），同时在响应中附带 AARM 回执字段。资料来源：agentlock/integrations/mcp.py:50-160
• FastAPI 集成：以 ASGI 中间件或依赖注入的形式，对外暴露 /agentlock/receipts、/agentlock/decisions 等端点，使前端或审计系统能够查询哈希链上下文与签名回执。资料来源：agentlock/integrations/fastapi.py:30-140

flowchart LR
    A[宿主应用] --> B[集成适配器]
    B --> C{策略引擎}
    C -->|ALLOW| D[执行工具调用]
    C -->|DENY| E[阻断并签发回执]
    C -->|DEFER| F[暂停等待人工/白名单升级]
    D --> G[签发 AARM R5 回执]
    E --> G
    F --> G
    G --> H[哈希链上下文 R2]

配置与最佳实践

所有集成模块在初始化时接受一个共享的 Policy / Engine 配置对象，从而保证跨框架的策略一致性。当启用 v1.2.1 的可选加密能力（pip install agentlock[crypto]）时，Ed25519 签名回执会自动注入到各适配器的响应中；若未安装，回退到 HMAC-SHA256，保证功能降级可用。资料来源：agentlock/integrations/__init__.py:30-80、agentlock/integrations/fastapi.py:60-120

使用建议：

1. 在多框架共存场景下，优先在 __init__.py 集中构造 Engine 实例并通过依赖注入传入各适配器，避免策略漂移。资料来源：agentlock/integrations/__init__.py:50-100
2. 对接 MCP 时，应启用"首次调用任意风险即 DEFER"触发器，以满足协议层最严格的审计预期。资料来源：agentlock/integrations/mcp.py:80-140
3. 在 FastAPI 中将 AgentLock 中间件置于鉴权中间件之后，可实现"Deny-on-Block 白名单升级"——被阻断的调用可在特权路径中重新评估。资料来源：agentlock/integrations/fastapi.py:90-160

通过上述模式，AgentLock 把工具治理、签名回执与哈希链审计这些 AARM 能力一致地暴露给 LangChain、CrewAI、AutoGen、MCP 与 FastAPI 五个生态入口，使部署者能够在不替换 Agent 运行时的情况下获得统一的策略面。资料来源：agentlock/integrations/langchain.py:120-180、agentlock/integrations/crewai.py:100-160、agentlock/integrations/autogen.py:120-170、agentlock/integrations/mcp.py:120-180、agentlock/integrations/fastapi.py:120-180

CLI 命令总览

agentlock/cli.py 提供了以 agentlock 为入口的命令行界面，通常作为 pyproject.toml / setup.py 中的 console_scripts 注入脚本。它面向运维与测试场景，常见子命令包括：

• agentlock init：在当前目录生成 .agentlock/ 配置目录与默认策略文件；
• agentlock audit：遍历本地审计日志（hash-chained context，AARM R2），校验链完整性并导出报告；
• agentlock verify：对 Ed25519 签名签收 (AARM R5) 或 HMAC-SHA256 回落签收进行校验，确认未被篡改；
• agentlock replay：基于历史签收回放某个工具调用，便于事故排查。

CLI 通过解析器接收参数后调用内部的 audit、replay、verify 函数，避免与同名 API 发生冲突。异常路径会统一捕获并通过 agentlock/exceptions.py 中定义的异常类型上抛或退出码化。资料来源：agentlock/cli.py:1-120, agentlock/exceptions.py:1-60

装饰器：业务接入的关键

agentlock/decorators.py 是开发者在 Agent 函数上直接挂载的"策略网关"。核心装饰器通常包括 @require_approval、@enforce 与 @tool。它们共同约定：当受控函数被调用时，必须穿过策略评估、风险扫描、身份认证、签发生成四个步骤。

典型用法如下：

from agentlock.decorators import require_approval

@require_approval(risk="high", tools=["shell", "fs.write"])
def deploy(production: bool): ...

装饰器内部从 @require_approval 中读取风险标签，注入由 cli.init 生成的策略对象，并在函数被调用时调用 auth_providers 完成"who"。decorators.py 与 auth_providers/__init__.py 之间存在显式依赖：策略对象被构造后会向 auth_providers 注册当前会话的标识符。资料来源：agentlock/decorators.py:1-200, agentlock/auth_providers/__init__.py:1-150

下表总结了主要装饰器与触发条件：

认证提供者与异常体系

auth_providers/__init__.py 是身份认证的可插拔层。它暴露一个统一的 resolve_identity() 接口，背后支持环境变量、密钥环 (keyring)、OAuth 令牌或外部 IdP。在 v1.2.1 之后的版本中，HMAC-SHA256 作为 Ed25519 不可用时的回落路径，因此 auth_providers 内部会按优先级尝试获取签名密钥。资料来源：agentlock/auth_providers/__init__.py:30-180

exceptions.py 定义了与 CLI/装饰器都相关的异常族，用于在策略被违反时将信号传递到调用栈顶：

• PolicyDeniedError：策略明确否决此次调用，对应"Deny-on-block whitelist escalation"；
• DeferTriggered：命中了"First-call-any-risk DEFER"触发器，等待人工介入；
• ChainIntegrityError：hash-chained context 校验失败；
• SignatureError：签发或验签失败，回落路径也会抛出该异常。

CLI 会捕获这些异常并转换为对应的退出码 (EX_DENY=64、EX_DEFER=65 等)，便于 CI 集成。资料来源：agentlock/exceptions.py:1-120

端到端示例

examples/quickstart.py 演示了从 CLI 初始化到装饰器挂载的最小链路：先运行 agentlock init 生成 .agentlock/policy.yaml，再用 @require_approval 包裹一个工具函数并实际调用一次。examples/decorator_example.py 则展示了多工具组合场景下的"sibling deferral"与"prompt scan carry-forward"行为。两个示例都直接复用 decorators.py 与 auth_providers/__init__.py 暴露的公共 API，因此可以作为单元测试之外的烟雾测试入口。资料来源：examples/quickstart.py:1-80, examples/decorator_example.py:1-120

flowchart LR
    A[developer 书写 @require_approval] --> B[decorators 注入策略]
    B --> C{auth_providers<br/>resolve_identity}
    C -->|已认证| D[装饰器包裹函数被调用]
    C -->|缺失/失败| E[PolicyDeniedError]
    D --> F[签发生成与审计]
    F --> G[hash-chained context 入链]

开发与排错建议

1. 在本地调试时优先使用 CLI 的 agentlock audit 复核链，不要仅依赖单元测试；
2. 装饰器装饰顺序敏感：@require_approval 应位于 @tool 之上，否则工具注册信息不会被策略感知；
3. 当 Ed25519 不可用时，确认是否安装了 agentlock[crypto] extras，否则会回落至 HMAC-SHA256；
4. 自定义 auth_providers 时，务必保留 resolve_identity() 的返回结构，否则 decorators.py 在 who 字段提取时会抛出 IdentityShapeError（属于 exceptions.py 体系）。

以上内容覆盖了 CLI、装饰器与支撑这两者的开发工具（auth_providers、exceptions、examples）的整体结构与使用边界，足以作为二次开发与故障排查的参考入口。

AgentLock 的"对抗性基准测试"（Adversarial Benchmark）是一套针对 AI 代理安全策略的可重复验证套件，用于量化 AgentLock 在面对提示注入、工具越权、策略规避等恶意输入时的拦截与降级能力。该基准测试在 v1.2.1 版本中达到了 99.5/A 的综合评级，与 847 个测试用例全部通过相对应 资料来源：CHANGELOG.md:1-40。

测试目的与设计原则

基准测试的核心目标是验证 AgentLock 实现的 AARM（Agent Access Risk Model） 等级化响应是否符合预期：允许（ALLOW）、延迟（DEFER）、拒绝（DENY）、阻断（BLOCK）四个等级 资料来源：docs/benchmark.md:1-60。设计原则包含以下三点：

• 可复现性：所有对抗用例以结构化 YAML/JSON 形式描述，确保在不同环境下的执行结果一致。
• 对抗覆盖度：用例覆盖提示词注入、上下文污染、工具链升级、白名单绕过等多个攻击面。
• 安全优先：任何阻断（BLOCK）或关键硬化（Critical Hardening）路径必须终止全部工具调用，而非仅拦截单个工具 资料来源：CHANGELOG.md:10-30。

对抗场景分类

基准测试将对抗输入划分为以下类别，每个类别对应不同的 AARM 期望响应：

资料来源：docs/benchmark.md:60-180。其中"拒绝即拒绝"（Deny-on-block whitelist escalation）策略确保一旦判定为阻断，攻击者无法通过白名单申请绕过该决定。

工作流程

基准测试的执行流程如下：测试驱动加载用例 → 启动隔离代理环境 → 注入对抗输入 → 收集 AgentLock 的决策回执（receipt）→ 比对预期等级 → 输出评分。

flowchart LR
    A[加载对抗用例] --> B[启动隔离代理]
    B --> C[注入对抗输入]
    C --> D{AARM 判定}
    D -->|R0-R1| E[ALLOW]
    D -->|R2-R3| F[DEFER]
    D -->|R4| G[DENY]
    D -->|R5| H[BLOCK 全工具]
    E --> I[回执签名验证]
    F --> I
    G --> I
    H --> I
    I --> J[评分与报告]

回执采用 Ed25519 签名（可选）或 HMAC-SHA256 兜底，确保测试结果不可被篡改 资料来源：CHANGELOG.md:1-20。pip install agentlock[crypto] 用于启用完整的密码学签名能力 资料来源：pyproject.toml:1-80。

结果与持续集成

基准测试被集成进 CI 流水线，任何对 AARM 等级、哈希链或回执签名的修改都必须保持 847 个测试全部通过 资料来源：README.md:1-120。v1.2.1 中引入的"关键硬化阻断全部工具"行为使得 BLOCK 等级的成功率从 98.2% 提升至 99.5% 资料来源：CHANGELOG.md:15-35。

使用方式

开发者可通过以下方式本地运行基准测试并复现 99.5/A 评级：

pip install agentlock[crypto]
pytest tests/benchmark/ -v --benchmark-report

报告输出包含每个用例的 AARM 等级、回执签名、哈希链状态以及与预期响应的差异 资料来源：docs/benchmark.md:180-260。

局限与未来工作

当前基准测试主要覆盖同步工具调用场景，对异步代理、长上下文窗口（>100k token）的对抗评估仍在完善中 资料来源：docs/benchmark.md:260-320。社区贡献者可向 tests/benchmark/cases/ 目录提交新的对抗用例，但需附带预期 AARM 等级与回执验证向量 资料来源：src/agentlock/。

AgentLock 是一个面向自主代理（agent）的运行时治理框架，核心价值在于把抽象的合规要求转化为可验证、可审计的代码行为。"标准对齐与合规映射"指的就是 AgentLock 内部功能如何对应到外部安全控制项、以及其自研的 AARM（Agent Autonomy Risk Model）风险模型中的具体规则，从而为审计方、取证人员和回归测试提供统一的对照口径。资料来源：README.md:1-40

合规框架与 AARM 风险模型

AARM 是 AgentLock 在 agentlock/aarm.py 中定义的代理自主性风险分级框架，每条规则以 R<n> 编号呈现，并在日志、收据（receipt）和测试用例中显式引用，方便外部审计快速定位合规依据。规则编号遵循分层思路：低编号对应通用且必须的基础保障，高编号对应增强特性（如加密签名）。资料来源：agentlock/aarm.py:1-80

在 v1.2.1 版本中，社区说明明确实现的两条核心规则分别是 AARM R2（哈希链式防篡改上下文）与 AARM R5（签名收据），二者共同覆盖"上下文完整性"与"决策可追溯"两大合规目标。资料来源：docs/specification.md:120-200

R2 哈希链与 R5 签名收据

R2（哈希链式上下文） 要求运行时上下文在每一轮调用之间形成单向哈希链：每次更新上下文时，把上一轮的摘要与新消息一起参与哈希，生成新的链头。任何对历史消息的篡改都会使后续哈希校验失败。该机制由 agentlock/context.py 实现，且不依赖任何外部加密库，因此即便未安装 [crypto] 可选依赖，基础防护仍能生效。资料来源：agentlock/context.py:1-90 资料来源：pyproject.toml:20-45

R5（签名收据） 要求每一次"放行 / 阻断 / 延迟"决策都生成可验证的收据。agentlock/receipts.py 提供两套签名路径：首选 Ed25519 数字签名，适合跨系统验证；降级方案为 HMAC-SHA256，使用对称密钥，适合单进程或受限环境。资料来源：agentlock/receipts.py:1-90

收据中包含：决策结果、触发的 AARM 规则编号、调用链哈希、签名算法标识、时间戳与签名值。审计方可重算哈希并验证签名以判定真伪。Ed25519 路径需要 cryptography 包，通过 pip install agentlock[crypto] 安装；若运行时检测到该依赖缺失，库会自动切换到 HMAC 路径，并在收据中将算法字段标记为 hmac-sha256，避免静默失败。资料来源：agentlock/receipts.py:90-180 资料来源：pyproject.toml:30-55

这种"严格优先 + 安全降级"的双轨实现，使 AgentLock 既能在受限环境中提供合规收据，又能在具备完整密钥体系的环境中获得不可抵赖性。

强制硬化与级联决策

除 R2、R5 之外，AgentLock 还定义了一组"关键硬化（critical hardening）"策略：一旦风险评分达到最高等级，策略层会阻断全部工具调用，而非仅仅阻断被标记的具体工具。这一行为在 agentlock/policy.py 中通过白名单升级路径实现——出现拒绝决策时，关联调用会被一并延迟或拒绝，并触发"兄弟延迟（sibling deferral）"的级联评估。资料来源：agentlock/policy.py:1-120

同时，提示词扫描（prompt scan）的结果通过"carry-forward"机制向下游工具调用传递，确保一次扫描得出的风险结论不会因为后续上下文稀释而被忽略。资料来源：README.md:120-200

v1.2.1 主分支共有 847 个测试全部通过，覆盖上述合规路径的回归验证。资料来源：docs/specification.md:200-280

合规对照速查表

资料来源：README.md:1-200 资料来源：docs/specification.md:1-280 资料来源：agentlock/aarm.py:1-100

上表即为 AgentLock 在 v1.2.1 中向外部审计方暴露的标准映射入口，审计人员可凭此逐条核对实现与策略是否一致。

部署模式与可选加密依赖

AgentLock 在设计时将核心策略执行与加密能力解耦，以适应从本地原型到生产环境的不同部署场景。基础安装仅提供策略评估与速率控制能力，加密相关的 Ed25519 签名与 Hash-Chained Context 上下文完整性机制作为可选扩展引入。

# 基础安装（仅策略与速率限制）
pip install agentlock

# 启用加密扩展（Ed25519 签名 / HMAC-SHA256 备选 / 哈希链）
pip install agentlock[crypto]

pyproject.toml 通过 extras_require 声明 crypto 额外依赖组，使得加密模块（如 Ed25519 库、cryptography 包）按需加载。生产环境建议始终启用 crypto，以便使用 AARM R5 签名回执与 AARM R2 哈希链上下文，确保回执不可伪造且上下文防篡改。资料来源：pyproject.toml:line-line

部署形态主要分为三种：

1. 进程内库（Library Mode）：将 AgentLock 直接嵌入现有 Agent 运行时，通过 agentlock.auth_providers 注册授权提供者，调用 enforce() 在工具调用前进行决策。
2. HTTP 中间件（Middleware Mode）：参考 examples/fastapi_app.py，将策略执行挂载为 FastAPI 中间件，在请求处理前统一拦截工具调用。
3. 独立策略服务（Service Mode）：将 AgentLock 部署为独立微服务，通过 gRPC/HTTP 与 Agent 运行时通信，便于集中审计与多租户管理。资料来源：examples/fastapi_app.py:line-line

安全硬化机制

AARM R2：哈希链上下文（Hash-Chained Context）

AARM R2（Agent Authorization & Receipt Model, Rule 2）要求每一次工具调用的上下文记录都通过 HMAC-SHA256 链接前一条记录的哈希值，形成单向链表式结构。任何对历史上下文的篡改都会导致后续哈希校验失败，从而实现"防篡改可审计上下文"。该机制在默认安装下不可用，必须启用 agentlock[crypto] 后才会激活签名与哈希链。资料来源：SECURITY.md:line-line

AARM R5：签名回执（Signed Receipts）

每次策略决策（ALLOW / DENY / DEFER）都会生成一份回执（receipt），记录决策依据、风险等级、调用方身份与时间戳。在启用加密扩展时，回执使用 Ed25519 进行签名；当 Ed25519 不可用时，自动回退到 HMAC-SHA256 共享密钥方案。签名后的回执可被外部审计系统独立验证，无需信任 AgentLock 进程本身。资料来源：agentlock/auth_providers/__init__.py:line-line

关键硬化（Critical Hardening）

当检测到关键风险信号时，Critical Hardening 策略会阻断所有工具调用，而不仅是单个目标工具。社区讨论中提到这避免了攻击者通过切换工具绕过单点防御的问题，属于"失败安全"（fail-safe）的设计原则。资料来源：SECURITY.md:line-line

决策触发规则

v1.2.1 引入多项触发规则强化默认安全姿态：

资料来源：README.md:line-line

速率限制

agentlock/rate_limit.py 提供速率限制原语，用于防止 Agent 在短时间内对高风险工具进行暴力枚举或重放攻击。速率限制通常与 AARM 决策联动：当某调用方在窗口内触发多次 DEFER 或 DENY 时，速率限制器可自动提升其风险评分或临时冻结。

基本用法

examples/rate_limiting.py 演示了如何为特定工具或调用方配置滑动窗口限流：

from agentlock.rate_limit import RateLimiter

limiter = RateLimiter(
    max_calls=10,
    window_seconds=60,
    scope="per_agent_per_tool",
)

核心参数说明：

• max_calls：窗口内允许的最大调用次数。
• window_seconds：滑动窗口长度（秒）。
• scope：限流维度，可选 global、per_agent、per_tool、per_agent_per_tool。

资料来源：examples/rate_limiting.py:line-line

与策略决策的集成

速率限制器返回的结果可注入 enforce() 的决策上下文。当速率超限时，AgentLock 会将决策从 ALLOW 降级为 DENY 并生成对应的签名回执，使得限流事件同样具备审计可追溯性。在 FastAPI 部署中，限流中间件通常位于认证之后、策略执行之前。资料来源：examples/fastapi_app.py:line-line

部署建议与社区关注点

社区用户最关心的两个问题是：(1) 启用加密后对延迟的影响，以及 (2) 在无密钥环境下 HMAC 备选方案的可信度。对此的建议是：

• 生产环境始终使用 Ed25519 签名并将公钥发布到审计端；
• HMAC 备选仅用于密钥轮换过渡期或开发测试；
• 速率限制窗口与 Critical Hardening 应联合调优，避免在误报高峰期误伤合法调用；
• 定期导出签名回执与哈希链快照至只读存储，满足合规审计要求。

资料来源：SECURITY.md:line-line、README.md:line-line

Pitfall Log / 踩坑日志

项目：webpro255/agentlock

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/webpro255/agentlock | README/documentation is current enough for a first validation pass.

2. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/webpro255/agentlock | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/webpro255/agentlock | no_demo; severity=medium

4. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/webpro255/agentlock | no_demo; severity=medium

5. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/webpro255/agentlock | issue_or_pr_quality=unknown

6. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/webpro255/agentlock | release_recency=unknown