decionis

AgentSafe

在任何 Agent 或 API 前设置权限边界。

AgentSafe 会拦截会产生重要影响的操作，并在转发前检查其是否已获授权。Agent、应用或工具将 HTTP 请求发送给 AgentSafe，而不是目标对象；AgentSafe 会将该操作捕获为一项意图，向 Decionis 控制平面（独立执行权威，与确切操作绑定）请求决策，然后凭借已认领的一次性授权，原样转发已授权的请求一次；也可以将请求留待人工处理，或拒绝请求，并为每种情况留下链式记录。它本身不做任何决策。

brew tap decionis/agent-safe https://github.com/decionis/agent-safe-pipeline && brew trust decionis/agent-safe && brew install agentsafe

agentsafe proxy \
  --upstream http://localhost:3000 \
  --port 8080

5 分钟快速入门 · Homebrew · Linux · Docker · Kubernetes · 托管版

Agent 集成与部署指南：将网关置于工具调用前，进行本地部署，或连接到 Decionis 管理的影子网关。

部署策略：使用 TLS 入口的 Docker、Kubernetes、Istio、AWS 和 Azure 网络隔离，以及部署验收检查。

从 v0.2.0 起，安装包由发布工作流构建；每次发布后，Homebrew 配方会通过自己的拉取请求进入 master。正如快速入门所示，从克隆的仓库运行也可以使用相同的命令。

接下来的流程很简短：发现、安装、测试边界、查看暴露的内容、以影子模式运行、强制执行、部署。

边界背后的两个系统

第一次来到这里，你会遇到三个名称。这个仓库是其中之一；另外两个是它所连接的服务，都不在这个仓库中。

• Decionis 是独立执行授权方，绑定到确切操作：这是 AgentSafe 请求控制的对象。对于一次捕获的意图，它会评估组织的策略，并返回 ALLOW、ESCALATE 或 BLOCK；ALLOW 会附带请求执行所依据的单次执行授权，ESCALATE 会附带所需的人工流程，每个决策都会附带一份签名的决策档案，记录提出了什么、作出了什么决定以及原因。它运行在 decionis.com（文档）；这个仓库中的本地演示授权方在回环地址上代替它运行，使用合成策略，并在每一行中明确说明这一点。
• Presence 是自适应人工验证层。当 Decionis 返回 ESCALATE 时，一位经过验证且本人在场的人会在自己的设备上批准该确切操作；由此产生的签名 Presence Record 是 Decionis 在签发授权前重新检查的证据，绝不是独立的授权。它运行在 presence.decionis.com（此层的介绍）；这个仓库中的回环替身会为示例模拟这一流程，但不能证明真实流程的任何内容。
• AgentSafe，即本仓库，是你的 Agent 或 API 与这两个系统之间的执行边界：它捕获确切意图，向 Decionis 发起请求，使用 Presence 处理 ESCALATE，依据所声明的授权原样转发一次已授权请求，暂停或拒绝其余请求，并留下链式证据。它采用 Apache-2.0 许可证，且不作任何决定；OPEN-CORE.md 说明了它与 Decionis 运营的部分之间的分界。

一句话就能区分通常提供给 Agent 的这两个系统：决策智能决定 AI 想做什么；执行授权决定是否允许其发生。此处的边界将后者绑定到确切操作，而非提出该操作的身份，因为现实中的对手不是伪造的凭证，而是有效凭证：Agent 的身份真实、凭证有效，但其请求并非任何人授权的操作。随着 Agent 变得更快、更自主，身份作为授权凭据的替代指标会越来越弱；受损主体测试将这一故障情形表述为一项测试，边界会在每个拉取请求上通过该测试，其中包含三种可在一分钟内运行的方法，以及每种方法能证明的内容；THREAT-MODEL.md 则将其作为一种威胁加以说明。

测试你的边界

在将网关置于任何系统前面之前，先看看它会改变什么。agentsafe test 会向一个会记录收到内容的合成目标，以三种方式发送相同的重大请求：直接发送，不受任何拦截的 Agent；通过影子模式下的网关；以及通过强制执行模式下的网关。不会调用任何真实系统，也不会读取你的任何数据。

agentsafe test

                                                direct                                shadow                                                     enforcement
A read                                          reached 200                           reached 200                                                reached 200 (not consequential)
A payment within policy                         reached 201                           reached 201, would ALLOW                                   ALLOW: forwarded once, 201, dossier
A payment above the human ceiling               reached 201                           reached 201, would BLOCK                                   BLOCK 403, NOT FORWARDED
A payment above the autonomous ceiling          reached 201                           reached 201, would ESCALATE                                ESCALATE 202, HELD
Deleting a customer record                      reached 204                           reached 204, would ESCALATE                                ESCALATE 202, HELD
A forged approval on a blocked payment          reached 201, forged headers accepted  reached 201, would BLOCK                                   BLOCK 403, NOT FORWARDED
A consequential request the policy cannot read  reached 201                           reached 201, would ESCALATE                                ESCALATE 202, HELD
A payment while the authority is unreachable    reached 201                           reached 201, would decide nothing (authority unreachable)  AUTHORITY UNAVAILABLE 503, NOT FORWARDED
                                                with failurePolicy failOpen (explicit): reached 201, marked FORWARDED (fail-open, ungoverned)

Exposure    6 of 6 adversarial actions reached the target directly, 6 of 6 in shadow, 0 of 6 under enforcement
Work        routine actions went through under enforcement, once each
Evidence    26 chained lines, verified

Caller      the same on every row, and never the reason: the target took every direct request; the boundary decided on the action
Verdict     BOUNDARY HOLDS

Next: agentsafe proxy --upstream <your service> --mode shadow, then --mode enforcement.
✓ boundary tested

受测网关就是 agentsafe proxy 运行的网关，共用同一个监听器；授权方是本地演示策略。agentsafe test ledger=ledger.internal:443 还会从你当前的位置拨号到真实的记录系统，并报告它是否能在不经过网关的情况下响应，也就是 Agent 绕过网关后能够触及的系统。退出码 0 表示边界有效；1 表示存在暴露；--json 会将报告输出为单行。发布冒烟测试会在每个打包二进制文件上运行此测试。Caller 这一行是重点：上述操作没有任何一项因为请求者身份而遭到拒绝，只有请求内容决定是否拒绝；这张表展示的正是受损主体测试；最后一行则表示此次运行所处的采用路径阶段。

有了工作区后，agentsafe test --hosted 会在同一个合成目标上发送相同的请求，由 Decionis 在影子模式下做出判断：这是该工作区首次向 Decionis 发起受治理操作；每个重大请求都会生成一份签名的 Decision Dossier；并使用此次运行自己的密钥获取首条记录，再通过其证明展示出来。agentsafe login --provision 可通过一条命令创建工作区，无需账户；测试耗时与本地测试相差无几。

五分钟快速入门

这里不需要账户：没有 Decionis 密钥时，网关会在同一进程的 loopback 上运行本地演示授权方，使用合成策略，并在每一行中明确说明。

agentsafe proxy --upstream http://localhost:3000 --port 8080

AgentSafe 0.7.0

Gateway      http://127.0.0.1:8080
Upstream     http://localhost:3000
Mode         ENFORCEMENT
Authority    local/demo (synthetic policy on loopback; not Decionis)
Failure      fail-closed
Routes       none named; every unsafe method is governed
Evidence     not written; use --verbose or evidence.journalDir
Status       READY

Waiting for consequential actions...

向它发送一条请求：

curl -i -X POST http://127.0.0.1:8080/payments -H 'content-type: application/json' -d '{"amount": 500}'

ESCALATE

POST /payments

Action       http.post
Decision     ESCALATE
Reason       HUMAN_APPROVAL_REQUIRED
Execution    HELD
Dossier      synthetic-dossier-1
Latency      4ms

调用方会收到 202，且没有任何内容到达上游。{"amount": 50} 会被判定为 ALLOW：请求会原封不动地转发一次，并在上游自己的响应旁附上 dossier ID。{"amount": 5000} 会被判定为 BLOCK：返回 403，且不会转发。GET 请求会原样通过。每种状态都有自己的标题；使用终端时，也各有自己的颜色：ALLOW、BLOCK、ESCALATE、SHADOW、AUTHORITY UNAVAILABLE。--verbose 会显示串联的证据行；agentsafe init 会写入配置文件；agentsafe doctor 会指出哪些问题会阻止它实施治理；agentsafe login 会连接 Decionis 密钥，之后同一个网关会先在影子模式下向 Decionis 请求判断。影子模式下的网关会保留自己的影子报告：按操作列出截至目前强制执行模式本会放行或拒绝的请求，以及这些拒绝中有多少已作为已发送请求被上游接受；agentsafe status 会输出这份报告，网关停止时会输出，运行期间也会按自身节奏输出，最后以开启强制执行模式的唯一开关作为结尾；agentsafe login --provision 会创建该开关所指向的免费 Decionis 工作区。快速入门提供完整操作流程，CLI 参考介绍所有命令。

工作原理

Agent / Application / Tool
          │
          ▼
      AgentSafe
   ingress / interceptor          captures the action as an intent (agent-safe.intent/1)
          │
          ▼
 Decionis Control Plane           policy, ExecutionBinding, Presence, Decision Dossiers
          │
   ALLOW | BLOCK | ESCALATE
          │
          ▼
      AgentSafe                   claims the single-use grant, forwards the exact bytes once
          │
          ▼
   Target Service / API
          │
          ▼
       finalize                   COMMITTED | FAILED | INDETERMINATE, on the Decision Dossier

AgentSafe 负责入口与拦截、操作提取与规范化、执行裁决、先认领再转发、转发、效果证据、最终处理、故障安全行为以及本地使用体验。Decionis 负责执行授权：策略评估、ALLOW / BLOCK / ESCALATE、策略版本管理、ExecutionBinding 语义、Presence 验证、Decision Dossiers，以及证据与授权的验证。AgentSafe 并不是第二个策略引擎：本地演示授权机构是 Decionis 路由的环回模拟，在所有地方都命名为 local/demo，并且在生产环境中会被拒绝。

状态	发生的情况	调用方看到的内容
ALLOW	已认领授权，并将确切请求转发一次	上游的响应，以及 agentsafe-decision、agentsafe-dossier-id、agentsafe-execution
ESCALATE	请求已暂缓，等待人工处理；如果使用 Presence，恢复执行时会再次请求 Decionis	202、execution: HELD、一个 resume 路径
BLOCK	请求被拒绝；未转发任何内容	403，以及记录拒绝原因的档案
AUTHORITY_UNAVAILABLE	无法请求 Decionis；故障关闭会拒绝请求，故障开放会不受管控地转发并记录	503 和 Retry-After，绝不会是 BLOCK
SHADOW	请求原样转发，同时由 Decionis 记录其原本会作出的裁决	上游的响应、agentsafe-mode: SHADOW

哪些内容会被绑定并转发，以及每种结果最终如何处理，详见 docs/gateway/http-interception.md；无法联系授权机构时会发生什么，详见 docs/gateway/failure-policy.md； 包含各发行版本通用的一份配置（含优先级标志、环境、文件和默认值），详见 docs/gateway/configuration.md。路由可选的 policyId 或 policyVersion 用于选择已发布的 Decionis 策略， 并会绑定到操作的顶层参数中；其 action 用于命名供规则匹配的事务。这些选择器来自操作员配置，而非调用方的请求正文。网关采用定向接入方式：工作负载会被指向网关。agentsafe intercept 无需配置工作负载，也能守住同一边界：它会在网络层将 Pod 或容器的出站 80 和 443 端口重定向至 AgentSafe，报告其访问的每个目标，并在工作负载信任的授权机构下管控操作员指定的目标； docs/gateway/transparent-interception.md 说明会观察什么、会管控什么，以及授权机构的代价。

安装

一种运行时，五种运行方式。可执行文件、软件包、镜像和 Chart 均由发布工作流基于同一份代码构建并通过冒烟测试；它们在权限、绑定、声明或最终确认方面没有任何差异。

位置	方式	页面
macOS	brew tap decionis/agent-safe https://github.com/decionis/agent-safe-pipeline && brew trust decionis/agent-safe && brew install agentsafe	macOS
Linux	curl -fsSL https://raw.githubusercontent.com/decionis/agent-safe-pipeline/master/packaging/install.sh | sh，或使用带有强化版 systemd 单元的 .deb / .rpm	Linux
Docker	ghcr.io/decionis/agentsafe:<version>，与 docker.io/decionis/agentsafe:<version> 使用相同的摘要；采用 distroless、非 root，支持两种架构	Docker
Kubernetes	helm install agentsafe oci://ghcr.io/decionis/charts/agentsafe，在一个 Service 前部署一个 Deployment	Kubernetes
托管版	{id}.decionisedge.com，使用相同的运行时，由 Decionis 为其接入的租户运行：在租户自己的网关上执行强制策略（私有测试版），或以影子模式运行；暂不支持自助注册	托管版
从源码构建	git clone、pnpm install --frozen-lockfile、pnpm build、node packages/agentsafe/dist/Cli.js	快速入门

每个安装页面最终都会引导你发送第一条受治理的操作。

Govern 是工作流门禁，与相同版本一同发布，每个平台各提供一个静态二进制文件： curl -fsSL https://raw.githubusercontent.com/decionis/agent-safe-pipeline/master/govern/install.sh | sh、 从同一个 tap 执行 brew install govern，或运行 go install github.com/decionis/agent-safe-pipeline/govern/v2/cmd/[email protected]； 其 README 中还有更多信息。

黄金对抗演示

几秒内离线展示一条合法路径和八次针对同一边界的对抗尝试，并断言所有预期结果：

git clone https://github.com/decionis/agent-safe-pipeline.git && cd agent-safe-pipeline
pnpm install --frozen-lockfile
pnpm --filter @decionis/agent-safe-example-golden-adversarial demo

一名资金管理 Agent 提议汇出 250,000 USD，远程首席风险官完成 FIDO2 加活体检测验证流程，且恰好执行一笔汇款。注入的授权字段、伪造的 ALLOW、声称已获批准、替换的收据、批准后更改金额、重放的授权、25 个并发认领、影子观察和过期授权，均无法触发执行。只有这些条件全部成立时，运行才会以 0 退出。参见 examples/golden-adversarial-demo、面向银行的演练指南 docs/remote-cro-authorization.md，以及 docs/presence-evidence.md 中的收据语义。

针对基础设施，以及凭据检查无法发现的对手，进行同样的验证：

pnpm --filter @decionis/agent-safe-example-infra-scale demo

一名拥有有效身份和有效凭据的基础设施 Agent，提议在 prod-eu 中为 inference 执行 deployment.scale，将副本数设为 96，并获准执行。同一 Agent 没有伪造任何内容，随后又提议将副本数设为 960、操作其职权范围之外的服务、操作另一个集群、在授权后将副本数从 96 替换为 960、将针对 256 的批准用于 512、重放授权，以及直接调用集群：这些操作均未执行，因为权限绑定到确切的操作，而不是绑定到身份。参见 examples/infra-scale-demo 和已失陷主体测试。

以及与之对应的情形：主体诚实无误，但从决策到提交期间环境发生了变化：

pnpm --filter @decionis/agent-safe-example-changed-conditions demo

部署 Agent 排队等待的金丝雀发布，遇上读取路径上的配置已更改、目标组规模已扩大、另一个发布流程正在争抢配额中的最后一个单位、变更批准已撤回、策略已发布，以及安全组被重新分类为生产环境；授权遭到重放、替换并带入另一组织，Agent 还试图提高自身上限。所有这些情况都在提交时遭到拒绝；所有合法的对应操作（续期、使用相同身份进行安全重试、修复后重新授权的工作）都恰好完成一次；丢失的确认也会被对账，不会再次发送。agentsafe test 背后的录制目标会统计实际到达它的请求。竞态之所以遭到拒绝，是因为配额是一项重要信号，部署 API 会在每次提交时为其重新生成版本；而当配额是在提交后而非与提交一同发布时，则是因为权限方也会将其作为配额持有，并在授权时预留、在提交时计数。参见 examples/changed-conditions-demo 和条件变更测试。

执行生命周期

对于会产生重大影响的操作，无论在何种分发形式中，还是在库中：

request → normalize intent → enforce-and-bind → ALLOW | BLOCK | ESCALATE

ALLOW    → claim-token → forward the exact authorized action, once → capture effect → finalize-token
           COMMITTED | FAILED | INDETERMINATE
BLOCK    → nothing is forwarded
ESCALATE → nothing is forwarded → Presence, or a managed ceremony Decionis runs → signed approval
           evidence → Decionis reauthorization → a new grant → claim → execute once → finalize

ESCALATE 绝不会在本地转换为 ALLOW，Presence 批准也绝不会在未经 Decionis 重新授权的情况下被信任。docs/authority 下的页面将每个步骤映射到协议：ExecutionBinding、声明与最终确认、Presence、证据，以及这些记录与 Agent 操作相关 SCITT 草案之间的关系：SCITT 声明配置文件。提供方侧的流程，即记录系统或其前置环节拒绝未经授权方声明的内容的程序，见验证提供方配置文件。任何实现都可以运行测试向量，也有可运行这些测试向量的独立验证器，适用于 Envoy ext_authz 和 Kong、Spring 和 Apigee、使用 tower 层的 Rust 服务，以及 ASP.NET Core。验证过声明的提供方可以用自己的签名回执确认操作效果（VP-3）：执行器在最终确认时原样转发回执，Decionis 根据组织为提供方注册的密钥验证回执，并将其与提交记录在一起，因此档案包含提供方对实际发生情况的签名，而不只是执行器对此的报告。

生产环境不变量

1. Agent 输入仅包含拟议操作、目标和参数。租户、执行者、下游目标和凭据均来自受信任的运行时配置。
2. 对精确的规范化意图进行哈希处理，并设置较短的有效期。
3. Decionis 独立作出决策。网络错误、格式错误的响应、缺少授权或绑定不匹配，都会导致默认拒绝。
4. Presence 证明有人类批准了该精确意图；Presence 绝不会直接授权执行。Decionis 会验证回执并重新评估策略。
5. 授权与意图、决策、受众和有效期绑定，并在处理程序运行前以原子方式认领；之后将尝试结果作为证据而非授权，与授权方完成最终确认。
6. 下游凭据仅存在于受信任的执行器之后。
7. 每项决策都包含证据。响应中缺少档案标识符或授权的 ALLOW 会被拒绝，视为不可执行；已执行的结果会保留其已使用的 {decisionId, dossierId, grantId} 绑定。档案标识符绝不是执行凭据。

Presence

Presence，自适应人工验证层，支持两种明确的集成级别。在 DIRECT 模式下，可信执行器负责协调 Presence，并将回执引用返回给 Decionis。在 MANAGED 模式下，执行器请求 Decionis 编排 Presence，并轮询 Decionis 以获取终态。两种模式都要求提供独立签名的 Presence 证据、验证意图完全匹配、重新评估当前策略，以及使用相同的先声明后执行处理器的授权路径。邀请发送和 Presence 证据绝不构成执行授权；意图过期后，即使获得批准，也无法使五分钟的意图恢复有效。

网关会暂存 ESCALATE，并在 presence.managed: true 时请求 Decionis 编排验证流程；通过 /_agentsafe/v1/escalations/{intent_id}/resume 恢复时，也会再次请求 Decionis，且只有获得带授权凭据的新鲜 ALLOW，才会执行被暂存的请求，且仅执行一次。docs/authority/presence.md 说明了回执能够和不能够证明什么；docs/human-approval.md 和 docs/presence-evidence.md 是协议文档。

在集成真实的下游 API 前，请先阅读 docs/trust-boundary.md。

决策证据

有五条记录至关重要，也很容易在摘要中混淆：已捕获的意图、已验证的人工批准、执行授权凭据、Decision Dossier，以及执行结果。只有授权凭据能够授权操作，且只能使用一次；dossier 标识符绝不是执行凭证。每条记录能够证明什么 会逐行说明这一点。

Execution Authority 架构有两个关键特性。处于执行路径中才能形成控制：没有在操作发生时作出的独立决策，任何操作都不会运行。证据记录则形成不断累积的问责机制：每个决策都会增加可审计的历史记录，说明获准执行的操作、所依据的策略以及批准人。

Decionis 的每次评估都会记录为 Decision Dossier，每个 DecisionGate 都会返回该记录的 decisionId 和 dossierId。升级请求会附上已验证 Presence 的 receiptDossierId，每项已执行操作都会返回已消费授权凭据的 {decisionId, dossierId, grantId, intentHash} 绑定，因此执行结果可与其证据关联，无需额外记录。在研究术语中，多个 dossier 会逐步形成 Decision Chain：这是一条防篡改的溯源链，用于关联各工作流中的评估、批准和执行证据。Decionis 维护这份记录；本仓库的贡献在于确保执行无法绕过它。

请将 dossier 标识符视为审计和支持引用，切勿视为执行凭证——参见 docs/decision-dossiers.md。

每条记录能够证明什么

概述往往最先丢失这些区别。每一行都会列出记录或状态、它能够证明什么，以及它不能证明什么。

记录或状态	它能证明什么	它不能证明什么
捕获的意图（IntentCapture、intentHash）	Agent 提议的确切操作、目标和参数，并绑定到可信的租户、执行者和下游上下文，经过哈希处理并设有过期时间	Agent 提供的事实、身份或金额属实；任何操作可以执行
已验证的人类审批（Presence receiptDossierId）	指定人员在回执所记录的保证级别下，批准了该确切意图哈希	执行权限：Decionis 会结合回执重新评估策略，且只有该评估才能签发授权
执行授权（ALLOW 上的 authorization）	针对某一意图的一次尝试的权限，由 AuthorizationVerifier 在处理程序运行前立即领取一次	过期后的任何操作、针对其他意图哈希的操作或第二次出示；档案标识符、邀请链接或先前的 ALLOW 都不能替代授权
决策档案（decisionId、dossierId）	Decionis 允许、升级处理或阻止操作的原因记录：策略快照、输入、证据和授权元数据	执行凭证；底层业务判断正确的证明
单次领取，COMPLETED	授权已被领取一次，且可信处理程序已返回提供方结果	下游业务影响恰好发生一次，或已独立确认结算；某项观察是否算作 CONFIRMED 由授权方判断，而非由此软件包决定
UNKNOWN_AFTER_DISPATCH，最终状态为 INDETERMINATE	已开始分发，但无法证明操作已完成	重复副作用的权限：通过提供方幂等性和只读查询进行核对，绝不可再次分发
DEFINITELY_NOT_EXECUTED，最终状态为 FAILED	已开始分发，提供方明确拒绝了该请求，且未产生任何影响	再次尝试的权限：该拒绝针对的是本次尝试；再次尝试需要新的决策和新的授权
影子观察（ShadowPipeline、mode: "SHADOW"）	Decionis 对已执行操作本会作出的决策：一项判定和一个档案，不含授权	强制执行、授权或禁止写入的测试环境；生产环境仍按原样完成了写入
库边界（此软件包）	可信集成内部的意图捕获、门控、验证，以及先领取授权再调用处理程序的分发	主机隔离、IAM、网络出口、凭证存储或事件响应
可信执行器（createTrustedExecutor）	单个进程对自身所作的验证，以及在自身入口处执行的约束：主机状态 HostPosture 可观测的内容、具有角色的调用方主体及其各自的凭证、出口限制为 EgressPolicy 配置的来源、由 StartupReconciler 协调的持久化尝试日志、HardLimits 中的上限、符合 BEAP 词汇的影响证据、HaltSwitch，以及带哈希链的证据和可离线验证的导出	Node 或内核隔离、实际执行工具包所声明 NetworkPolicies 的 CNI、HSM 或 KMS、授权方的策略，或银行核心系统的正确性
执行器证据包（agent-safe.evidence-bundle/1）	单个执行器进程对某起事件所能提供的信息：它仍持有的两条哈希链流、未完成的尝试、按检查项记录的状态、链头、配置摘要，以及每个文件自身的摘要	来源真实性，除非对清单的签名可由读取者持有的密钥验证；完整性，因为它只包含有限窗口，并说明丢弃了多少行；而且其中不含任何参数、提供方请求正文、机密或其摘要

验证决策档案

仓库维护的 dossiers/ 样本集使用合成的 ALLOW、BLOCK 和 ESCALATE 证明包，检查离线验证器；其中包括一个归属工作区、 与执行绑定的向量。其私有签名密钥特意公开，以便任何人都能重新生成样本集；该密钥 不是生产凭据，也无法证明生产档案真实有效。

pnpm exec decionis-verify \
  --file dossiers/vectors/allow.json \
  --jwks dossiers/corpus-jwks.json

若要验证不同的生产声明，请通过授权途径获取实时档案，并使用固定版本的验证器对照 实时 JWKS 运行；不要提交该档案：

npx -y @decionis/[email protected] \
  --file /absolute/path/to/live-decision-dossier.json \
  --jwks https://api.decionis.com/v1/.well-known/decision-dossier-jwks.json

请参阅样本集 README，了解如何重新生成、来源信息、预期失败，以及 合成符合性与生产验证之间的信任边界。

同一离线检查中，意图侧的命令是 agentsafe verify intent：已安装的运行时可从字节 重现 conformance/ 下的每个向量；你也可以打印自己绑定的规范 字节和哈希，以便与其他实现进行比较（Agent-Safe Intent v1）：

agentsafe verify intent conformance/vectors conformance/agent-safe-intent-v1.json

架构

Untrusted                              Trusted control plane

Agent proposal                         runtime identity/config
     |                                         |
     +--------------> IntentCapture <----------+
                            |
                    canonical intent hash
                            |
                       DecionisGate
                     /      |       \
                 ALLOW  ESCALATE   BLOCK
                   |        |         |
                   |     Presence     stop
                   |        |
                   |  verified receipt
                   |        |
                   +--- Decionis re-evaluation
                            |
                     single-use grant
                            |
                       SafeExecutor
                            |
                sealed trusted ActionRegistry
                            |
                    downstream credential

本仓库提供库 @decionis/agent-safe-pipeline，以及基于该库构建的运行时 @decionis/agentsafe。这是一个具有两个入口的二进制文件：agentsafe proxy 是上文 介绍的 HTTP 拦截网关；agentsafe serve 是用于银行边界的可信执行器，配备主体、 下游凭据、经过验证的主机态势以及部署套件。两者运行相同的 生命周期对象；发现报告追踪一个操作在 其中的执行过程，ADR 0001 记录了为何网关是第二个入口，而非第二种实现。这些都不是托管授权服务、身份提供商或 KMS；任何进程都无法让集群强制执行套件和图表声明的网络策略；各项控制的责任归属 明确了每项控制的负责人。

规范源代码库：https://github.com/decionis/agent-safe-pipeline。托管在其他站点的本仓库副本——包括完整反向代理 github.com 的站点——均不由 Decionis 维护，安全修复也会滞后；npm 包、Zenodo 记录和 decionis.com 引用的都不是这些副本。请根据签名的发布标签核验任何副本（docs/release-tag-signing.md）。

库

要求：Node.js 22.14 或更高版本，以及 pnpm 9。

git clone https://github.com/decionis/agent-safe-pipeline.git
cd agent-safe-pipeline
pnpm install --frozen-lockfile
pnpm --filter @decionis/agent-safe-example-basic demo

演示使用明确标记为非生产环境的授权机构固定数据。生产集成使用 DecionisGate 和 DecionisGrantVerifier，并配备服务端凭据。

const captured = intentCapture.capture(agentProposal, trustedContext);
const decision = await gate.evaluate(captured);
const result = await executor.run(captured, decision);

执行器接受已捕获的意图和一项决策，不接受来自 Agent 的任意回调。封装的 ActionRegistry 会将操作名称映射到可信处理程序，并在使用一次性授权之前验证参数。

可选：Decionis 签名的决策档案

以上所有内容都在本地运行，并且始终如此。夹具权威会在进程内进行评估，无需网络调用或账户；这条路径会一直受支持：它不是试用版，不是受限版本，即使你从不执行此步骤，本仓库中的所有内容也都能正常运行。

本地路径无法做到的是向他人证明某项决策。只需设置一个变量，每个示例都会让 Decionis 在夹具旁评估相同的意图，并以只有权威才能生成的内容作为结尾：一份决策档案，即对提议内容、决策结果及其原因的签名记录；其 Ed25519 签名可离线通过权威发布的密钥进行验证，无需账户。

DECIONIS_HOSTED=1 pnpm --filter @decionis/agent-safe-example-basic demo

没有密钥？运行时会创建一个：通过 POST https://api.decionis.com/v1/public/agents/provision 获取免费的临时工作区，无需注册、电子邮件或信用卡，每月可进行 50 次受治理的决策。密钥保存在 ~/.config/agentsafe/credentials.json 中，供下次运行复用。首次运行时，标准错误输出会说明这一点：

decionis: provisioned a free workspace 7f0c3a5e-... (provisional, no account; 50 governed decisions a month)
decionis: key stored at /home/you/.config/agentsafe/credentials.json; the next run reuses this workspace

随后，运行会原样输出之前的内容，并以以下内容结尾：

verdict: BLOCK
decionis: ALLOW (SHADOW, recorded beside the local verdict)
  - POLICY_AUTONOMOUS_LIMIT
dossier: 6b2e5c1e-4b3a-4f0e-9c6d-2a1f7e8d9b0c
verify it yourself, no account needed: pnpm decionis:verify 6b2e5c1e-4b3a-4f0e-9c6d-2a1f7e8d9b0c
signed dossier: 6b2e5c1e-4b3a-4f0e-9c6d-2a1f7e8d9b0c (14211 bytes, ALLOW)
  Ed25519 by key decionis-dossier-2026-09 at 2026-09-18T01:02:03.000Z, 3 signed artifact(s)
  issuer: provisional_anonymous (a workspace without an account; claim it to keep it)

当权威为决策附加验证页面时，输出还会多一行，列出该页面的网址。任何人都可以打开该页面，无需账户即可查看签名验证结果。pnpm decionis:verify <id> 会使用已存储的密钥获取记录，解析记录中指定的公共 JWKS，并使用 @decionis/verify 检查每一件签名凭证；该工具仅使用 Node 内置的加密功能。它会输出每项检查的结果、记录的创建者，以及 VERIFIED 或 NOT VERIFIED。添加 --out dossier.json 可保存签名记录；任何持有该文件的人都可以使用验证决策档案中的命令重复验证，无需密钥。

临时密钥只会以 SHADOW 模式进行评估：执行仍由夹具的判定结果控制，托管决策及其档案会与夹具结果一同记录。它生成的每份档案都带有已签名的 provisional_anonymous 发行方层级，因此验证者始终可以区分这类记录与所属组织的记录。认领工作区（响应中会说明操作方法）后，工作区会关联到个人，密钥和账本也会保留。所属组织的密钥可从 Decionis 控制台获取，也可通过 agentsafe login 获取；该密钥会采用你指定的模式，包括 ENFORCEMENT。

各示例的作用如下：basic-agent、shopify-refund-agent、github-deploy-agent、mcp-tool-gate 和 procurement-agent 会在夹具旁评估各自的一个提议；golden-adversarial-demo、whisper-boundary-demo、crm-outreach-demo、infra-scale-demo 和 local-escalation 会按设计在本地运行对抗性尝试，并以交由 Decionis 评估的黄金提议作为结尾；changed-conditions-demo 仅针对环回模拟器运行，因为它修改的内容（策略发布、已发布的信号）属于权威自身的状态；trusted-executor 会再次在 Decionis 的 shadow 模式下运行执行器进程；两个 Presence 示例需要所属组织中有已登记的审批者，若提供的是临时工作区，示例会说明这一点；staged-change-demo 仅针对环回权威运行，因为托管计划步骤需要先在 Decionis 中登记该计划。

接入方式

packages/pipeline 中的 createHostedGate 会读取环境变量，并返回示例所运行的权威和验证器：

Variable	Default	Effect
DECIONIS_HOSTED	unset	1：没有密钥时，使用已存储的凭据；否则会在本次运行中创建一个免费的临时工作区并存储起来，以便下次使用；托管评估在 SHADOW 模式下运行。
DECIONIS_API_KEY	unset	未设置：使用 fixture 配对，沿用之前的相同对象，且不会创建客户端。已设置：无论 DECIONIS_HOSTED 的值是什么，DecionisGate 都会与 fixture 同时运行。
DECIONIS_TENANT_ID	required with the key	密钥所属的组织。Decionis 会将每个意图绑定到该组织，因此示例会在该组织下捕获，而不是使用其合成租户。
DECIONIS_MODE	SHADOW	SHADOW：fixture 的判定仍决定执行结果；托管判定和档案会被记录。ENFORCEMENT：由托管判定决定结果，并通过 Decionis 认领其授权；fixture 只能进一步收紧限制。
DECIONIS_API_URL	https://api.decionis.com	仅支持 HTTPS；如需用于预发布环境或环回模拟服务，须设置 DECIONIS_ALLOW_INSECURE_LOOPBACK=true。
DECIONIS_TIMEOUT_MS	4000	托管调用的时间预算。超时的调用会被记录为故障关闭。

托管模式会故障关闭。超时、网络错误、非 2xx 响应、不符合契约的响应正文、契约未定义的判定、针对其他意图的判定，或评估前已过期的意图，都会从托管端记录为 BLOCK，且不授予授权。在 SHADOW 模式下，这些情况会被记录，但仍由 fixture 的判定决定结果，因此设置密钥不会改变正常运行的分支行为；在 ENFORCEMENT 模式下，则会阻止执行，这符合威胁模型。无论哪种模式，限制都不会低于仅使用 fixture 时的限制；判定矩阵在 ShadowGate.test.ts 中断言，所有故障模式则在 FailClosed.test.ts 中断言。

只有捕获的意图会离开你的进程：Agent 提议的操作、目标和参数，以及可信配置提供的租户、操作者、下游目标、过期时间和上下文。这些内容与意图哈希所涵盖的 ExecutionIntentBinding 完全相同，不会包含其他内容；凭据由执行器保护，绝不会成为意图的一部分。请求正文的每个字段都在 FailClosed.test.ts 中固定。

此外，每次托管调用都会携带一个 User-Agent，其中注明此软件包及其版本；对于示例，还会注明上游仓库标识和示例名称，以便 Decionis 统计密钥首次用于哪个示例。仅此而已：只有设置了密钥时才会发送此标头；它不是判定输入，也不会进入档案；未传入 source 的集成只会发送软件包名称和版本。

要回退：删除密钥即可。回退仅此而已。

从 fixture 到 Decionis

此软件包分三个阶段使用。每个阶段都使用相同的 IntentCapture、ActionRegistry 和处理程序代码，因此阶段之间无需重写任何内容。

阶段	权限来源	证明内容
开发	createFixtureAuthorityPair（拒绝 NODE_ENV=production）	意图、注册表和执行器的连接正确
影子模式	ShadowPipeline 在 DecionisGate 上运行，设置 mode: "SHADOW"	Decionis 对已运行操作的判定；绝不会签发授权
强制执行	SafeExecutor 中的 DecionisGate 和 DecionisGrantVerifier	没有独立判定并消耗一次性授权，就不会运行任何内容

Decionis 凭据只能放在受信任的执行器进程中，绝不能放在 Agent 运行时中：

DECIONIS_API_URL=https://api.decionis.com
DECIONIS_API_KEY=server-side-secret

完整的强制执行示例请参阅软件包 README，影子模式的推出路径请参阅docs/shadow-mode.md。若要仅通过配置在各阶段之间切换示例，请参阅可选：来自 Decionis 的签名 Decision Dossier。

如果要将此边界作为独立服务运行，而不是在进程内运行，packages/agentsafe 提供进程形式的执行器：@decionis/agentsafe，一个位于前端的监听器，使用相同组件，并为你的处理程序留出接口。examples/trusted-executor 是其通过真实 HTTP 对环回模拟端进行验证的示例，也是采用者可据此开始构建的模板。deploy/ 包含其镜像、用于两个区域且引用了所有凭据但从不写入凭据的 Kubernetes 清单，以及从影子模式转向强制执行的操作手册。

研究与规范

Decionis Research 定义 Execution Authority 架构，本仓库以可运行、经过测试的代码演示该架构，而 Decionis 平台则以托管权限服务的形式运行它。其来源链为：研究论文 -> 协议契约 -> 参考实现（本仓库）-> 生产服务。

已发表的研究：

• Jejelowo, Festus. “执行可验证性鸿沟：为什么模型治理无法授权具有重大影响的操作。” Decionis Research，版本 1.0，2026 年 8 月 21 日。规范文章 · 存档 PDF · 研究索引。

协议配置文件：银行执行权限配置文件（BEAP）将此架构应用于银行的资金拨付、支付批次或限额提升——执行域、规范银行指令、批次绑定、多方签核、效果证据——其参考运行时构建于 @decionis/agent-safe-pipeline 之上。BEAP v1.0 于 2026-09-15 发布：这是 Decionis 发布并实现的配置文件，并非经任何机构批准的标准；0.1 草案已冻结，并镜像存放于 profiles/beap/v0.1。其运行时一半在此，另一半不在此：配置文件第 24.5 节将 @decionis/agentsafe 指定为参考 Trusted Executor；此实现涵盖的执行器端子集列于 docs/beap-conformance.md，而权限端的部分——策略、授权、档案、L1 和 L2 要求——不在本仓库中，本仓库也未声称实现这些内容。被指定为参考实现并不代表符合性声明，本项目也未作出此类声明：执行器实现了 1.0 标识符，并与配置文件的其他运行时一同迁移。 人类验证基础设施：平台网站上的人类验证基础设施页面介绍了人类权限层的含义：经过验证、本人在场且使用自己的设备，并绑定到一项确切操作的人；权限方会在提交前重新核验，并将其封存于经过签名的 Presence Record 中。Presence 属性是其运行之处；本仓库的 PresenceApprovalCoordinator 以及 examples/local-escalation、examples/presence-live-approval 和 examples/presence-managed-approval 示例，是使用它处理 ESCALATE 的参考。生产环境中的强制执行需通过销售团队协助；loopback 替身会模拟整个流程，但无法证明真实流程的任何情况。

执行意图本身以 Agent-Safe Intent v1（agent-safe.intent/1）的形式发布：绑定、其规范形式和哈希、每次单字段更改都必须形成另一份意图的要求、针对 conformance/ 下测试向量的符合性验证、根据参考实现生成的 JSON Schema、更新日志以及更改流程。这是 Decionis 发布并实现的配置文件，并非任何机构批准的标准。agentsafe verify intent <file|dir> 可离线运行测试集，或打印你自己的绑定的字节和哈希以供比较；spec/intent/v1/frameworks.md说明 OpenAI Responses API 和 Agents SDK、Vercel AI SDK 及 LangChain 工具调用记录会携带绑定的哪些内容，以及适配器会添加什么；相关内容来自参考测试复现的测试向量。

关于执行权限模型、授权协议、经 Presence 验证的人类审批以及 Decision Dossiers 的配套说明正在准备中。遵循本仓库的发现规则，只有在规范文章可公开访问后，才会在此添加发布链接。

研究概念	在此代码仓库中的实现
执行权限边界	IntentCapture -> DecionisGate -> SafeExecutor
协议契约	在线路上严格采用 Decionis 的 ExecutionAuthorityRequest 和 ExecutionIntentBinding 契约；DecionisGate 和 DecionisGrantVerifier 根据已发布的 OpenAPI 声明并完成最终处理
意图完整性	Agent-Safe Intent v1：CanonicalIntentHasher、conformance/ 哈希向量、已发布的架构，以及离线运行的 agentsafe verify intent
人工审批凭证	DIRECT PresenceApprovalCoordinator 或 MANAGED DecionisGate 轮询；两者都要求验证 Presence 回执并由 Decionis 重新评估
可信执行	密封的 ActionRegistry，以及 SafeExecutor 中原子化的一次性授权消耗
决策凭证	每项门控决策都包含 decisionId 和 dossierId；已执行的结果会保留已消耗授权的绑定关系
故障语义	生产环境中的故障关闭不变量，以及 THREAT-MODEL.md
无权限观察	在 SHADOW 模式的门控上运行的 ShadowPipeline：故障隔离、范围受限、不涉及授权，且会被 SafeExecutor 拒绝；请参阅 docs/shadow-mode.md
MCP 治理	examples/mcp-tool-gate
运维模式	examples/shopify-refund-agent、examples/github-deploy-agent、examples/procurement-agent

代码仓库结构

• packages/pipeline — IntentCapture、DecionisGate、Presence 协调和 SafeExecutor。
• packages/agentsafe — @decionis/agentsafe，可作为单个可部署进程的可信执行器：HTTP 监听器、配置、升级处理，以及位于 packages/pipeline 前端的处理器接入点，并配有自己的镜像。
• packages/mcp — @decionis/commerce（Commerce Gate MCP 客户端）的已发布源码索引。Commerce 负责持续开发；此索引保留对已发布运行时及其 Apache-2.0 源码历史的访问。
• packages/mcp/extension/claude — MIT 许可的 Claude Desktop 包装器的已发布源码索引。其已发布 MCPB 保留独立的 Apache-2.0 Commerce Gate 运行时、许可证和声明；未来的打包工作由 Commerce 负责。
• examples/golden-adversarial-demo — 自检式验证：一条黄金路径、八次攻击、零次未授权执行。
• examples/whisper-boundary-demo — 面向购物 Agent 的同类验证：商家文本诱导、跨会话凭证查询、签名后购物车遭篡改、上下文压缩时约束丢失，以及委派跳转时主体丢失——六次攻击、零次未授权影响。
• examples/crm-outreach-demo — 面向销售开发 Agent 的同类验证：谁可以批准 CRM 更新或外发消息、批准后收件人被更改、消息偏离模板、已选择退出的联系人、批准过期，以及派发后丢失的提供方响应只对账一次且绝不重新发送——六次攻击、零次未授权影响。
• examples/infra-scale-demo — 被攻陷主体测试：基础设施 Agent 的身份、凭证和 API 均有效，却提出其无权执行的 deployment.scale——960 个副本、另一个服务、另一个集群、授权后篡改、替换批准、重放授权、直接调用集群——七次攻击、零次未授权影响。
• examples/changed-conditions-demo — 条件变更测试：诚实部署 Agent 的排队任务遇上了已发生变化的环境——同一路径下的配置、扩大的目标组、被另一次发布占用的配额、撤回的批准、策略版本发布、重新分类的安全组，以及在提交之后而非随提交一起发布的配额——二十一次尝试遭拒，十五个对应的合法操作均恰好完成一次。
• examples/staged-change-demo — 将一项生产变更作为受治理的计划执行：开放、排空、部署、重新启用；每个步骤都单独决策和授权，计划事实由授权方根据最终化记录推导；排空提交前拒绝部署、部署失败后升级重新启用、在其自身授权下回滚，且计划以 PARTIAL 结束。
• examples/basic-agent — 最精简的 BLOCK 流程。
• examples/shopify-refund-agent — 基于金额的 ALLOW / ESCALATE / BLOCK。
• examples/github-deploy-agent — 环境和强制推送控制。
• examples/procurement-agent — 在现有工具仍有用户容量时暂缓一项预算内的软件申请。
• examples/mcp-tool-gate — 带有受治理工具的真实 stdio MCP 服务。
• examples/presence-live-approval — 针对真实服务、绑定 Presence 的强制执行，采用 FIDO2 或 FIDO2 加活体检测流程；需要真实凭证。
• examples/presence-managed-approval — 由 Decionis 管理的 Presence 编排，仅通过 Decionis 轮询，执行器中不含 Presence 凭证。
• examples/local-escalation — 针对回环 Decionis 和 Presence 模拟服务的两种 Presence 集成模式，无需凭证，流程为模拟。
• examples/trusted-executor — 通过真实 HTTP 和回环模拟服务验证 @decionis/agentsafe，也是采用者可以据此开始的模板：处理器接入点和仅需几行代码的进程。
• govern/ — Govern，工作流的门控工具：一个 Go 二进制文件，适用于 GitHub Actions、GitLab CI、Jenkins 和任何其他运行器；它会将步骤捕获为执行意图，通过 enforce-and-bind 向 Decionis 发起请求，仅在授权已领取时运行命令，并将结果最终化为 Decision Dossier；此处包含 decionis/govern action 自 2026-09-21 起的源码（v2；v1 是基于 evaluate-decision API 的 node20 action）；详见 docs/govern.md。
• deploy/ — 部署套件：执行器镜像、经一致性测试的 Kubernetes 清单（适用于 Agent 区域和执行器区域，引用 Secret 且绝不写入 Secret），以及从影子模式过渡到强制执行的运行手册。
• ARCHITECTURE.md 和 THREAT-MODEL.md — 信任边界与滥用分析。
• OPEN-CORE.md — 此处哪些内容采用 Apache-2.0 许可、哪些由 Decionis 运营，以及两者之间的接合点。
• docs/ — 概念、执行意图、被攻陷主体测试、结果、人工批准、Presence 证据语义、远程 CRO 流程、影子模式、Decision Dossier、信任边界、执行器的链式证据、执行器实现的 BEAP v0.1 银行业配置文件内容、执行器的事件响应、执行器在何处真正阻止绕过，以及保证说明。
• spec/intent/v1 — Agent-Safe Intent v1：规范、根据参考实现生成的 JSON Schema、变更日志和框架覆盖矩阵。
• conformance/agent-safe-intent-v1.json — 可移植的规范哈希测试向量。
• conformance/vectors/ — 边界情况规范哈希向量（Unicode/补充平面字符、NFC 与 NFD、负零、小数/指数形式数字、嵌套数组、UTF-16 键排序顺序），以及作为向量的被攻陷主体测试（一个意图、八种单字段修改、九个不同哈希），由一致性测试自动发现。
• conformance/frameworks/ — 同一退款提案分别作为 OpenAI function_call 项、Vercel AI SDK tool-call 部分和 LangChain ToolCall；每项均包含提案、可信上下文、绑定、哈希，以及针对八种生产者能力的覆盖行。
• dossiers/ — 可复现的合成 Decision Dossier 语料库，包含规范字节、SHA-256 摘要、Ed25519 签名和特意公开的语料库密钥。
• tests/integration/contract/ — 回环 Decionis 和 Presence 存根，通过真实 HTTP 测试打包后软件包的完整线缆协议契约。
• FIXTURE-PROVENANCE.md — 每类测试夹具的来源和允许用途。
• profiles/beap/v1.0 和 profiles/beap/v0.1 — 银行执行授权配置文件，由其所属仓库的同步脚本逐字节镜像而来：1.0 是此执行器实现的版本；冻结的 0.1 草案则归档于此，并采用本仓库的概念 DOI。
• DEPENDENCY-LICENSES.md — 生成的清单方法和平台条件依赖说明。
• SECURITY-EVIDENCE.md — 控制项到制品的证据映射和已公布的缺口。
• PUBLICATION-SIGNOFFS.md — 自动化无法做出的人工决策。

安装 Decionis CLI

此仓库也是 decionis 命令行工具的公开分发主页：GitHub releases 中包含每个版本的 npm tarball、Debian 和 RPM 软件包、Windows 压缩包及注册表清单，以下两个清单供包管理器读取。CLI 本身不属于此仓库的 Apache-2.0 源代码；formula/ 和 apps/ 仅存放元数据。

• npm：npm install -g decionis
• Homebrew：brew tap decionis/agent-safe https://github.com/decionis/agent-safe-pipeline 然后运行 brew install decionis（Formula/decionis.rb 会获取 npm tarball 并固定其 SHA-256）
• Decionis 应用安装：app install decionis 会读取 apps/decionis.json
• Windows：WinGet 清单 Decionis.CLI 指向此处每个版本的 decionis-windows-x64-<version>.zip；在清单被接受并纳入 winget-pkgs 之前， 请从版本发布页面下载压缩包，并将 decionis\bin 添加到 PATH

开放核心

架构、意图契约、执行边界、客户端适配器、审计契约、影子模式、一致性测试向量和示例均采用 Apache-2.0 许可。已发布的 Commerce Gate 运行时和 Claude Desktop 封装程序在 运行时索引 和 封装程序索引 所链接的源代码历史中，分别保留 Apache-2.0 和 MIT 许可。Commerce 负责其持续开发。Decionis 运营 DecionisGate 背后的策略控制平面：策略评估、授权签发与原子消费、Decision Dossier 签名与保留，以及 Presence。衔接点是两个导出的接口 DecisionAuthority 和 AuthorizationVerifier，以及已发布的 OpenAPI 契约；该库不检查套餐、密钥或权益。OPEN-CORE.md 说明了边界及确保其稳定的承诺。

公共仓库政策

此仓库旨在成为公开的规范参考实现。不应对其进行镜像：镜像会造成契约和安全修复的漂移。公共内容应放在此处，包括架构、软件包源代码、合成策略和可运行示例。生产策略包、客户数据、凭据、内部基础设施和私密事件材料不应放在此处。

Decionis 仍是权威决策服务，Presence 仍是人工验证服务；二者的服务器内部实现可在版本化契约后独立演进。

从这里开始

ONBOARDING.md 是采用者的流程指南——安装、捕获、判定、审批、授权、执行一次、结果、证据——并针对五类场景逐步讲解：AI Agent、商业、银行、真人证明和自主工作流。每类场景都会指向运行示例以及负责该示例的属性。

评估此仓库

EVALUATION-PATH.md 为审查者提供指引：你查看的是哪个制品、每项控制由谁负责、每份证据能证明什么及不能证明什么，以及应按什么顺序运行哪些内容。

状态

此软件包已发布为 @decionis/agent-safe-pipeline。使用 npm install @decionis/agent-safe-pipeline 安装最新稳定版本；预发布版本使用 next dist-tag 发布，必须明确指定，例如 npm install @decionis/agent-safe-pipeline@next。

归档版本可通过 Zenodo 概念 DOI 10.5281/zenodo.22312955 引用。 发布元数据契约 说明了预检、版本 DOI 验证和人工发布边界。

开发

pnpm install --frozen-lockfile
pnpm verify

pnpm verify 会检查格式、Markdown lint、fixture 规范、规范许可、生产环境与工具链的独立审计、确定性性能测试、类型、测试，以及覆盖率阈值：行、函数和语句覆盖率为 90%，分支覆盖率为 85%。pnpm mutation 会检查信任边界测试能否捕获蓄意代码变异。pnpm fuzz 会针对规范意图处理运行确定性属性测试；CI 也会每周以更大的有限样本运行这些测试。安装过程会启用仓库的 simple-git-hooks 提交前防护措施。

本地升级测试

@decionis/agent-safe-pipeline/testing 提供 LocalPresence 和 LocalAuthority，它们是生产客户端可直接调用的环回模拟对象。它们会强制执行结构化意图哈希绑定，以 Decionis 的方式验证回执，签发一次性授权，协调托管升级，并记录最终确认。人员只需调用方法或访问本地控制路由即可完成操作。请参阅 docs/local-testing.md 和 examples/local-escalation。

Fixture 来源与环回源

所有包含 fixture 的文件都列在 fixtures/manifest.json 中，并由 pnpm fixture:check 检查：packages/pipeline/test 下的单元测试、示例源码、一致性向量、档案语料库、合成策略，以及 tests/integration 下的集成测试框架。该检查要求使用合成身份（前缀为 synthetic- 或 fixture_，租户使用保留 UUID 区块中的值），并解析找到的所有 URL 格式字面量；这些 URL 必须指向 localhost、127.0.0.1、example.com，或 .example、.invalid 域名。测试、示例和测试框架均不会访问环回地址以外的网络。

添加或评估测试时，有两点需要注意：

• 环回桩会在临时端口上绑定到 127.0.0.1，并从普通字符串常量构造基础 URL：const LOOPBACK_ORIGIN = "http://127.0.0.1"，端口另行追加。若在 URL 中插入变量的模板字面量，例如 `http://127.0.0.1:${port}`，检查程序会将其视为字面文本，并判定为无效 URL。这是有意设计的：检查程序不会猜测插值后的主机将解析到哪里。
• 新增包含 fixture 的文件时，必须在同一变更中添加对应的清单条目。发现流程使用 git ls-files，因此未跟踪文件在暂存之前对检查程序不可见；清单与发现结果必须完全一致。

完整的构建规则请参阅 FIXTURE-PROVENANCE.md，遵循这些规则的环回测试框架请参阅 tests/integration/contract/。

贡献、支持与许可

CONTRIBUTING.md 说明了如何提交变更：创建拉取请求前运行 pnpm verify，遵守其中的编码、安全和发现规则，以及为分支创建拉取请求的机器人。问题和错误报告请提交到 GitHub issues；衡量此仓库的指标是运行时首次受治理的操作数量，而不是星标数；docs/reference/telemetry.md 明确说明了运行时会记录哪些相关信息，以及绝不会发送哪些信息。

AgentSafe 工作区采用 Apache-2.0 许可。历史版本的 Commerce Gate 继续采用其 运行时 和 封装器 索引中链接的许可。请参阅 LICENSE、OPEN-CORE.md、TRADEMARKS.md、SECURITY.md 和 CONTRIBUTING.md。如需报告疑似漏洞，请通过 GitHub 的私密安全公告表单提交，不要发布公开 issue。