# https://github.com/webpro255/agentlock 项目说明书

生成时间：2026-07-04 05:26:48 UTC

## 目录

- [项目概述与核心原则](#page-1)
- [三层执行架构](#page-2)
- [授权门与权限策略](#page-3)
- [五种决策类型](#page-4)
- [签名回执与哈希链上下文](#page-5)
- [上下文、内存与信任降级](#page-6)
- [自适应硬化与信号检测](#page-7)
- [框架与协议集成](#page-8)
- [CLI、装饰器与开发工具](#page-9)
- [对抗性基准测试](#page-10)
- [标准对齐与合规映射](#page-11)
- [部署、安全硬化与速率限制](#page-12)

<a id='page-1'></a>

## 项目概述与核心原则

### 相关页面

相关主题：[三层执行架构](#page-2), [授权门与权限策略](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/webpro255/agentlock/blob/main/README.md)
- [pyproject.toml](https://github.com/webpro255/agentlock/blob/main/pyproject.toml)
- [agentlock/__init__.py](https://github.com/webpro255/agentlock/blob/main/agentlock/__init__.py)
- [agentlock/policy.py](https://github.com/webpro255/agentlock/blob/main/agentlock/policy.py)
- [agentlock/types.py](https://github.com/webpro255/agentlock/blob/main/agentlock/types.py)
- [agentlock/scanner.py](https://github.com/webpro255/agentlock/blob/main/agentlock/scanner.py)
- [agentlock/context.py](https://github.com/webpro255/agentlock/blob/main/agentlock/context.py)
- [agentlock/receipts.py](https://github.com/webpro255/agentlock/blob/main/agentlock/receipts.py)
</details>

# 项目概述与核心原则

## 一、项目定位与目标

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]()

## 三、运行架构

| 组件 | 职责 | 资料来源 |
| --- | --- | --- |
| `scanner` | 对提示与历史进行模式匹配、风险分级 | [agentlock/scanner.py:1-80]() |
| `policy` | 维护白名单/黑名单并产出 `ALLOW`/`DEFER`/`DENY` 决策 | [agentlock/policy.py:1-60]() |
| `context` | 维护带哈希链的会话上下文，支撑 R2 持久化 | [agentlock/context.py:1-60]() |
| `receipts` | 为每一次决策签发 Ed25519/HMAC 回执（R5） | [agentlock/receipts.py:1-60]() |
| `types` | 提供 `Verdict`、`RiskLevel`、`HardeningLevel` 等核心枚举 | [agentlock/types.py:1-80]() |

公共 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]()

---

<a id='page-2'></a>

## 三层执行架构

### 相关页面

相关主题：[项目概述与核心原则](#page-1), [授权门与权限策略](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [agentlock/gate.py](https://github.com/webpro255/agentlock/blob/main/agentlock/gate.py)
- [agentlock/token.py](https://github.com/webpro255/agentlock/blob/main/agentlock/token.py)
- [agentlock/receipt.py](https://github.com/webpro255/agentlock/blob/main/agentlock/receipt.py)
- [agentlock/__init__.py](https://github.com/webpro255/agentlock/blob/main/agentlock/__init__.py)
- [README.md](https://github.com/webpro255/agentlock/blob/main/README.md)
</details>

# 三层执行架构

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. 三层协同与模块边界

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

| 层级 | 模块 | 主要产物 | 核心动作 |
|---|---|---|---|
| L1 策略门控 | `gate.py` | 决策 (ALLOW/DENY/DEFER) | 风险评估、白名单升级、兄弟延后、关键硬化 |
| L2 能力令牌 | `token.py` | 能力 token | 作用域绑定、TTL、授权来源串联 |
| L3 回执审计 | `receipt.py` | 签名回执 + 哈希链 | 不可否认、防篡改、提示扫描前向携带 |

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

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

---

<a id='page-3'></a>

## 授权门与权限策略

### 相关页面

相关主题：[项目概述与核心原则](#page-1), [五种决策类型](#page-4), [CLI、装饰器与开发工具](#page-9)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [agentlock/gate.py](https://github.com/webpro255/agentlock/blob/main/agentlock/gate.py)
- [agentlock/policy.py](https://github.com/webpro255/agentlock/blob/main/agentlock/policy.py)
- [agentlock/schema.py](https://github.com/webpro255/agentlock/blob/main/agentlock/schema.py)
- [schema/agentlock-v1.2.json](https://github.com/webpro255/agentlock/blob/main/schema/agentlock-v1.2.json)
- [schema/agentlock-v1.0.json](https://github.com/webpro255/agentlock/blob/main/schema/agentlock-v1.0.json)
</details>

# 授权门与权限策略

## 概述

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]()

```mermaid
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]()

策略的关键字段：

| 字段 | 作用 |
| --- | --- |
| `tool_pattern` | 工具名匹配模式，支持精确与通配 |
| `risk_tags` | 触发 first-call-any-risk DEFER 的标签集合 |
| `whitelist_escalation` | deny-on-block 时的白名单升级路径 |
| `critical_hardening` | 命中后是否升级为全工具阻断 |
| `inheritance` | 子代理、工具组、会话级别的继承与覆盖 |

匹配顺序遵循「风险标签 > 显式 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 回执无法签发。

---

<a id='page-4'></a>

## 五种决策类型

### 相关页面

相关主题：[授权门与权限策略](#page-3), [自适应硬化与信号检测](#page-7)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [agentlock/modify.py](https://github.com/webpro255/agentlock/blob/main/agentlock/modify.py)
- [agentlock/defer.py](https://github.com/webpro255/agentlock/blob/main/agentlock/defer.py)
- [agentlock/stepup.py](https://github.com/webpro255/agentlock/blob/main/agentlock/stepup.py)
- [agentlock/gate.py](https://github.com/webpro255/agentlock/blob/main/agentlock/gate.py)
- [agentlock/redaction.py](https://github.com/webpro255/agentlock/blob/main/agentlock/redaction.py)
</details>

# 五种决策类型

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

## 决策类型一览

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

| 决策类型 | 含义 | 主要来源 | 典型触发 |
| --- | --- | --- | --- |
| `ALLOW` | 策略全部通过，直接放行 | `gate.py` | 风险评分低于阈值且无脱敏需求 |
| `DENY` | 阻断请求并记录拒绝凭据 | `gate.py` | 高危工具、`critical` 强化模式命中 |
| `DEFER` | 暂停执行，移交人工或后续阶段 | `defer.py` | 首次调用任一风险项（first-call-any-risk）、同级延期 |
| `STEP_UP` | 要求二次验证或白名单升级 | `stepup.py` | 命中白名单但被前置规则拒绝（deny-on-block escalation） |
| `MODIFY` | 在放行前改写载荷或脱敏字段 | `modify.py`、`redaction.py` | 检出敏感凭据、PII 或提示注入残留 |

`资料来源：[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]()`

## 决策流转示意

```mermaid
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](https://github.com/webpro255/agentlock/blob/main/agentlock/gate.py)

## 小结

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

---

<a id='page-5'></a>

## 签名回执与哈希链上下文

### 相关页面

相关主题：[上下文、内存与信任降级](#page-6), [对抗性基准测试](#page-10)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [agentlock/receipts.py](https://github.com/webpro255/agentlock/blob/main/agentlock/receipts.py)
- [agentlock/context.py](https://github.com/webpro255/agentlock/blob/main/agentlock/context.py)
- [agentlock/audit.py](https://github.com/webpro255/agentlock/blob/main/agentlock/audit.py)
- [agentlock/gate.py](https://github.com/webpro255/agentlock/blob/main/agentlock/gate.py)
- [agentlock/aarm.py](https://github.com/webpro255/agentlock/blob/main/agentlock/aarm.py)
- [agentlock/__init__.py](https://github.com/webpro255/agentlock/blob/main/agentlock/__init__.py)
- [agentlock/crypto.py](https://github.com/webpro255/agentlock/blob/main/agentlock/crypto.py)
- [pyproject.toml](https://github.com/webpro255/agentlock/blob/main/pyproject.toml)
</details>

# 签名回执与哈希链上下文

## 概述与作用范围

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]()`

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

| 优先级 | 算法 | 触发条件 |
| --- | --- | --- |
| 1 | Ed25519 (`cryptography` 库) | `pip install agentlock[crypto]` 成功导入 `cryptography` |
| 2 | HMAC-SHA256 | 当 Ed25519 依赖不可用时的回退路径 |

降级策略由 `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]()`

```mermaid
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）：

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

## 与策略门、审计的协同

`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]()`

---

<a id='page-6'></a>

## 上下文、内存与信任降级

### 相关页面

相关主题：[签名回执与哈希链上下文](#page-5), [自适应硬化与信号检测](#page-7)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [agentlock/context.py](https://github.com/webpro255/agentlock/blob/main/agentlock/context.py)
- [agentlock/memory_gate.py](https://github.com/webpro255/agentlock/blob/main/agentlock/memory_gate.py)
- [agentlock/session.py](https://github.com/webpro255/agentlock/blob/main/agentlock/session.py)
- [agentlock/policy.py](https://github.com/webpro255/agentlock/blob/main/agentlock/policy.py)
- [agentlock/decision.py](https://github.com/webpro255/agentlock/blob/main/agentlock/decision.py)
- [agentlock/receipts.py](https://github.com/webpro255/agentlock/blob/main/agentlock/receipts.py)
- [agentlock/trust.py](https://github.com/webpro255/agentlock/blob/main/agentlock/trust.py)
- [agentlock/scanner.py](https://github.com/webpro255/agentlock/blob/main/agentlock/scanner.py)
</details>

# 上下文、内存与信任降级

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

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

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

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

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

## 二、内存门控（Memory Gate）

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

```python
资料来源：[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` 状态，避免「先批准后滥用」的滑动攻击。

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

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

| 风险信号 | 策略输出 | 内存门控 | 上下文哈希链 |
|---------|---------|---------|-------------|
| 无风险 | `ALLOW` | open | 追加并链接 |
| 低/中风险（首次） | `DEFER` | deferred | 追加并链接 |
| 高风险或白名单命中 | `DENY` | denied | 仅追加元数据 |
| 提示注入命中 | `DEFER` + 标记沿链传递 | deferred | 追加并链接，标记持久化 |

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

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

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

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

```mermaid
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 基准评级的关键所在。

---

<a id='page-7'></a>

## 自适应硬化与信号检测

### 相关页面

相关主题：[五种决策类型](#page-4), [对抗性基准测试](#page-10)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [agentlock/hardening.py](https://github.com/webpro255/agentlock/blob/main/agentlock/hardening.py)
- [agentlock/signals/__init__.py](https://github.com/webpro255/agentlock/blob/main/agentlock/signals/__init__.py)
- [agentlock/signals/velocity.py](https://github.com/webpro255/agentlock/blob/main/agentlock/signals/velocity.py)
- [agentlock/signals/combos.py](https://github.com/webpro255/agentlock/blob/main/agentlock/signals/combos.py)
- [agentlock/signals/echo.py](https://github.com/webpro255/agentlock/blob/main/agentlock/signals/echo.py)
- [agentlock/signals/prompt_scan.py](https://github.com/webpro255/agentlock/blob/main/agentlock/signals/prompt_scan.py)
</details>

# 自适应硬化与信号检测

## 概述与设计目标

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]()

## 自适应硬化流程

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

| 硬化等级 | 触发条件 | 默认行为 |
|---------|---------|---------|
| L0（默认） | 无信号命中 | 允许所有已授权工具 |
| L1（观察） | 单个低风险信号命中 | 记录审计日志，正常放行 |
| L2（限制） | 多个信号命中或组合信号触发 | 限制敏感工具，启用 sibling deferral |
| L3（关键） | Critical 信号或首次高风险触发 | **阻断所有工具**，进入 DEFER |

资料来源：[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 项测试覆盖了上述全部硬化路径与信号组合场景，确保了升级与降级逻辑的稳定性。

---

<a id='page-8'></a>

## 框架与协议集成

### 相关页面

相关主题：[授权门与权限策略](#page-3), [CLI、装饰器与开发工具](#page-9)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [agentlock/integrations/__init__.py](https://github.com/webpro255/agentlock/blob/main/agentlock/integrations/__init__.py)
- [agentlock/integrations/langchain.py](https://github.com/webpro255/agentlock/blob/main/agentlock/integrations/langchain.py)
- [agentlock/integrations/crewai.py](https://github.com/webpro255/agentlock/blob/main/agentlock/integrations/crewai.py)
- [agentlock/integrations/autogen.py](https://github.com/webpro255/agentlock/blob/main/agentlock/integrations/autogen.py)
- [agentlock/integrations/mcp.py](https://github.com/webpro255/agentlock/blob/main/agentlock/integrations/mcp.py)
- [agentlock/integrations/fastapi.py](https://github.com/webpro255/agentlock/blob/main/agentlock/integrations/fastapi.py)
</details>

# 框架与协议集成

## 概述

`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 框架"、"协议"、"服务端框架"三类组织：

| 类型 | 模块 | 集成对象 | 适配入口 |
|---|---|---|---|
| Agent 框架 | `langchain.py` | LangChain Tools / Chains | 回调/包装器 |
| Agent 框架 | `crewai.py` | CrewAI Agent / Tool | 工具装饰器 |
| Agent 框架 | `autogen.py` | AutoGen Function Call | 注册函数包装 |
| 协议 | `mcp.py` | Model Context Protocol Server | 工具处理器 |
| 服务端框架 | `fastapi.py` | FastAPI 应用 | ASGI / 依赖注入中间件 |

这种分层保证了协议层（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]()

```mermaid
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]()

---

<a id='page-9'></a>

## CLI、装饰器与开发工具

### 相关页面

相关主题：[授权门与权限策略](#page-3), [框架与协议集成](#page-8)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [agentlock/cli.py](https://github.com/webpro255/agentlock/blob/main/agentlock/cli.py)
- [agentlock/decorators.py](https://github.com/webpro255/agentlock/blob/main/agentlock/decorators.py)
- [agentlock/auth_providers/__init__.py](https://github.com/webpro255/agentlock/blob/main/agentlock/auth_providers/__init__.py)
- [agentlock/exceptions.py](https://github.com/webpro255/agentlock/blob/main/agentlock/exceptions.py)
- [examples/quickstart.py](https://github.com/webpro255/agentlock/blob/main/examples/quickstart.py)
- [examples/decorator_example.py](https://github.com/webpro255/agentlock/blob/main/examples/decorator_example.py)
</details>

# CLI、装饰器与开发工具

本页面向开发者介绍 AgentLock 中面向工程师的三个核心入口：命令行工具 (`agentlock`)、Python 装饰器 API，以及用于策略解析与身份识别的开发工具模块。AgentLock 是一个在 AI Agent 调用外部工具之前执行授权审批与审计签收 (signed receipt) 的中间层，本页聚焦"如何在代码中接入这套机制"。

## 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`。它们共同约定：当受控函数被调用时，必须穿过策略评估、风险扫描、身份认证、签发生成四个步骤。

典型用法如下：

```python
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]()

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

| 装饰器 | 用途 | 关键参数 | 触发的策略路径 |
| --- | --- | --- | --- |
| `@require_approval` | 在调用前要求人工审批 | `risk`, `tools` | 风险扫描 → 评审队列 |
| `@enforce` | 强制策略包，无人工介入 | `policy_id` | 即时否决或放行 |
| `@tool` | 把普通函数标记为受控工具 | `name`, `domain` | 注册到策略白名单 |

## 认证提供者与异常体系

`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]()

```mermaid
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）的整体结构与使用边界，足以作为二次开发与故障排查的参考入口。

---

<a id='page-10'></a>

## 对抗性基准测试

### 相关页面

相关主题：[自适应硬化与信号检测](#page-7), [标准对齐与合规映射](#page-11)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/benchmark.md](https://github.com/webpro255/agentlock/blob/main/docs/benchmark.md)
- [CHANGELOG.md](https://github.com/webpro255/agentlock/blob/main/CHANGELOG.md)
- [README.md](https://github.com/webpro255/agentlock/blob/main/README.md)
- [pyproject.toml](https://github.com/webpro255/agentlock/blob/main/pyproject.toml)
- [src/agentlock/](https://github.com/webpro255/agentlock/tree/main/src/agentlock)
</details>

# 对抗性基准测试

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 期望响应：

| 类别 | 典型攻击向量 | 期望响应 |
|------|-------------|---------|
| 提示注入 | "忽略之前所有指令" | DEFER 或 DENY |
| 上下文篡改 | 哈希链断裂 | BLOCK |
| 白名单升级 | 拒绝后请求放行 | DENY（拒绝即拒绝） |
| 兄弟延迟 | 多调用间的关联风险 | DEFER |
| 扫描残留 | 前次扫描结果携带 | DEFER（首次出现风险） |

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

## 工作流程

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

```mermaid
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 评级：

```bash
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/](https://github.com/webpro255/agentlock/tree/main/src/agentlock)。

---

<a id='page-11'></a>

## 标准对齐与合规映射

### 相关页面

相关主题：[对抗性基准测试](#page-10)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/webpro255/agentlock/blob/main/README.md)
- [docs/specification.md](https://github.com/webpro255/agentlock/blob/main/docs/specification.md)
- [agentlock/aarm.py](https://github.com/webpro255/agentlock/blob/main/agentlock/aarm.py)
- [agentlock/receipts.py](https://github.com/webpro255/agentlock/blob/main/agentlock/receipts.py)
- [agentlock/context.py](https://github.com/webpro255/agentlock/blob/main/agentlock/context.py)
- [agentlock/policy.py](https://github.com/webpro255/agentlock/blob/main/agentlock/policy.py)
- [pyproject.toml](https://github.com/webpro255/agentlock/blob/main/pyproject.toml)
</details>

# 标准对齐与合规映射

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]()

## 合规对照速查表

| 合规目标 | AARM 规则 | 实现位置 | 依赖要求 |
|---|---|---|---|
| 上下文完整性 | R2 | agentlock/context.py | 无（核心内置） |
| 决策可追溯（强） | R5 (Ed25519) | agentlock/receipts.py | cryptography（可选） |
| 决策可追溯（降级） | R5 (HMAC-SHA256) | agentlock/receipts.py | hashlib/hmac（核心） |
| 高风险全阻断 | 关键硬化 | agentlock/policy.py | 无（核心内置） |
| 跨调用风险传递 | prompt scan carry-forward | agentlock/policy.py | 无（核心内置） |

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

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

---

<a id='page-12'></a>

## 部署、安全硬化与速率限制

### 相关页面

相关主题：[框架与协议集成](#page-8), [三层执行架构](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [SECURITY.md](https://github.com/webpro255/agentlock/blob/main/SECURITY.md)
- [agentlock/rate_limit.py](https://github.com/webpro255/agentlock/blob/main/agentlock/rate_limit.py)
- [agentlock/auth_providers/__init__.py](https://github.com/webpro255/agentlock/blob/main/agentlock/auth_providers/__init__.py)
- [examples/rate_limiting.py](https://github.com/webpro255/agentlock/blob/main/examples/rate_limiting.py)
- [examples/fastapi_app.py](https://github.com/webpro255/agentlock/blob/main/examples/fastapi_app.py)
- [README.md](https://github.com/webpro255/agentlock/blob/main/README.md)
- [pyproject.toml](https://github.com/webpro255/agentlock/blob/main/pyproject.toml)
</details>

# 部署、安全硬化与速率限制

## 部署模式与可选加密依赖

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

```bash
# 基础安装（仅策略与速率限制）
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 引入多项触发规则强化默认安全姿态：

| 规则名称 | 行为 | 说明 |
|---------|------|------|
| First-Call-Any-Risk DEFER | 首次遇到任何风险信号时进入 DEFER | 宁可延迟也不放过 |
| Deny-on-Block Whitelist Escalation | 被拒绝的目标自动升级白名单审查 | 阻止白名单滥用 |
| Sibling Deferral | 兄弟工具一并进入 DEFER | 阻断相关攻击面 |
| Prompt Scan Carry-Forward | Prompt 扫描结果向下游传递 | 上下文风险传递 |

资料来源：[README.md:line-line]()

## 速率限制

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

### 基本用法

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

```python
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]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: webpro255/agentlock; human_manual_source: deepwiki_human_wiki -->