# @datalayer/agent-shield 中文文档

规范地址：https://npmcn.com/package/%40datalayer/agent-shield/

版本：0\.2\.20
npm 元数据更新时间：2026-11-12T15:24:34.840Z
中文译文更新时间：2026-11-14T09:55:18.162Z
软件包许可：BSD-3-Clause

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40datalayer/agent-shield
原文对照：https://npmcn.com/package/%40datalayer/agent-shield/?lang=original
项目主页：https://github.com/datalayer/agent-shield
源码仓库：https://github.com/datalayer/agent-shield

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：106 kB，32 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-10-15T15:09:41.171Z
- 最新版本发布：2026-11-12T15:24:33.748Z
- 近 30 天下载量：2082（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

Agent Shield: 政策文件的类型和决定的句子,用于网络和电话.

## 安装

```sh
npm install @datalayer/agent-shield
```

也可以使用：`pnpm add @datalayer/agent-shield`、`yarn add @datalayer/agent-shield`、`bun add @datalayer/agent-shield`

## README

[![Datalayer](https://images.datalayer.io/legacy/datalayer-25.svg)](https://datalayer.ai/)

[![Become a Sponsor](https://img.shields.io/static/v1?label=Become%20a%20Sponsor&message=%E2%9D%A4&logo=GitHub&style=flat&color=1ABC9C)](https://github.com/sponsors/datalayer)

# 盾牌探员

[![PyPI - Version](https://img.shields.io/pypi/v/datalayer-agent-shield)](https://pypi.org/project/datalayer-agent-shield) [![npm](https://img.shields.io/npm/v/%40datalayer%2Fagent-shield)](https://www.npmjs.com/package/@datalayer/agent-shield)

**每个代理都有一个运行时间防火墙.** 和每个特工一起部署防护罩 执行 执行、集中管理策略并保留 审计线索.

盾牌站在代理人和世界之间 其第一艘起落架是 **代理服务器**数字 : `agent-shield run -- <an ACP agent's command>` 启动代理为 其子进程并作为一个 [代理客户协议](https://agentclientprotocol.com/) 所以任何非加太公司的客户——Zed, `vscode-acp`玛丽莫, Datalayer的跑步时间——与"盾牌"对话,"盾牌"则与特工对话. 在决定之间:

-   `session/request_permission` 根据政策: _动手_ 答案没有 客户端, _先问我_ 以相同的选项转发,并答复如下: 选择的人, _交给我吧_ (一) 被拒判者所见之刑罚;
-   经纪人的 `tool_call` 通知分类(非加太国家) `kind` → `read`, (中文(简体) ), `write`, (中文(简体) ), `delete`, (中文(简体) ), `execute`· ; `other` 未关闭到 `write`并坚持 (b) 拒绝取消转弯,并说明原因;
-   `fs/*` 财务报告和审定财务报表 `terminal/*` 誓以盾牌 **工作空间** ——其外道被拒绝,命令运行环境被修剪 - 每一个都是客户看到的工具行;
-   `mcpServers` 重新撰写,使代理只得到保险单借出的东西;
-   每一个行动和决定都是 `~/.agent-shield/audit.jsonl`, (中文(简体) ), 证书已编辑, 文件的内容从未在其中 .

## 前五分钟

```bash
pip install "datalayer-agent-shield[claude-code]"   # one extra per harness
agent-shield setup        # finds node, the vendor CLIs and the credentials present; installs the pinned adapter into ~/.agent-shield/harnesses/<id>@<version>; writes agent-shield.yaml beside the project
agent-shield run -- claude-agent-acp               # Claude Code behind the Shield, on this directory, with the default policy
```

2026年10月15日从一个干净的前缀测量: `setup` 带了 **27岁s** (适配器) `@agentclientprotocol/claude-agent-acp@0.91.0`, 325 MB,通过 `npm install --prefix`,从一个全球 `npx`(三); `run` 初始化适配器 并宣布会议开幕 **1.5 s (韩语)**; 第一个决定遵循第一个工具 电话 整个,从 `pip install` 在终端上看到的决定,是 一分钟内,5次 在5分钟的目标下.

`setup` 它不要求它找到任何东西:它说哪些证书由 名称( 绝不是一个值) , 缺少名称和如何导出名称和存储 没有秘密 它在一句话中拒绝登记簿禁止的证书——a Claude Code 或 ChatGPT 订阅登录, 只有 API 密钥服务 第三方,Google登录双子座个人等级.

然后说:

```bash
agent-shield log                 # the audit, one line per action and decision
agent-shield policy show         # every line of the policy in force, and where it came from
agent-shield policy schema       # the document's JSON Schema
agent-shield harnesses           # the register: each harness, its terms, where they were read
agent-shield upgrade --check     # a newer Shield or adapter?
agent-shield upgrade             # move the adapters to the register's pinned versions
agent-shield uninstall           # previews; --yes removes the adapters and the config, keeps the audit and the policy
```

赛德, `settings.json`数字 :

```json
"agent_servers": {
  "Claude Code behind the Shield": { "command": "agent-shield", "args": ["run", "--", "claude-agent-acp"] }
}
```

每个启动命令的ACP客户端都使用同一条线——VS代码的ACP 客户端,代理.nvim,代理-客户端-内核,一个Telegram桥像 acp-连接器 [与](https://agent-shield.datalayer.tech/works-with/) 页面上写着曾经尝试过的,有版本和日期.

## 地址: `serve`

```bash
export SHIELD_TOKEN=$(openssl rand -hex 24)
agent-shield serve --host 0.0.0.0 --port 8788 --token-env SHIELD_TOKEN -- claude-agent-acp   # one harness per connection
agent-shield connect ws://host:8788/acp --token-env SHIELD_TOKEN                               # a served Shield as a local stdio agent
```

`serve` 和服务器是相同的代理服务器, 完毕 **网络安全套** 财务报告和审定财务报表 **ACP 可流性 HTTP 密码** 打开 `/acp` ——生态系统桥梁的运输汇合(非加太) 远程, `acp_rpc_bridge`,非加太项目的RFD)——标注在 `Authorization` 在第一个消息中,从不在 地址; `--harness <id>` 登记在 `/acp/<id>`· ; `--bridge` 实值 同一个服务器,没有盾牌, 一个Datalayer运行时舱的侧车. 非加太技术合作公司 `connect` 反对 `serve`数字 : `VERDICT: CONFORMANT`。 。 。 .

## 已注册到数据层

```bash
export AGENT_SHIELD_SERVICE_KEY=...   # a service agent's key, made by the organization's administrator
agent-shield setup --register --org <organization uid> --agent <service agent uid>
```

密钥在 IAM 交换一个符号(`client_credentials`)并保持原样 进去 `~/.agent-shield/credentials.yaml`,模式0600,从未显示; `serve` 接下来 从IAM中抽取其政策,没有这些政策就无法关闭,并输出其周期 并算上数据显示器的可观察性 多么独立 盾不能有——操作员的网络边界和同伴的 数据显示器运行时间的挂载, 由 `setup` 财务报告和审定财务报表 `policy show`; PAP 被说成无法使用, 而只在当地使用, 并且已经注册过 `agent-shield run --pap <company> -- <agent>` 借出网关的 PAP 工具 在有盾牌的公司, 当保险单的 `mcp.allow` 名称 `pap_<company>`。 。 。 .

## 政策

每个范围一份文件—— `organization`, (中文(简体) ), `team`, (中文(简体) ), `session` 内 `agent-shield.yaml` 在项目旁( `~/.agent-shield/agent-shield.yaml`, (中文(简体) ), 与计划在 [`schema/policy.schema.json`](https://npmcn.com/package/%40datalayer/agent-shield/schema/policy.schema.json)。 。 。 . 最严格的范围首先决定 **第一个决定获胜**; 范围 上面写着任何动作都无法通过 任何规则名称都无法通过 _先问我_从不 _动手_。 。 。 .

默认 `setup` 写道:在工作空间内阅读和搜索——做; 编辑并在其中移动——做,显示为diffs;删除,运行命令,以及 工作空间外的任何路径——先问我;一个命令命名证书, `sudo`,从网络安装软件包,或 `git push` -先问我 命令; 获取-通过 `network.fetch`'允许列表,即 空的,所以拒绝;发送或购买——先问我. 限制:100至200个工具 电话,4个接8个终端,5个接20个米B **软** 阈值询问 一次,a **难** 一个拒绝每个会越过它的电话 并说些什么 让会议继续.

```yaml
scope: session
rules:
  - name: read inside the workspace
    decision: allow
    classes: [read]
    where: inside
  - name: git push
    decision: ask
    classes: [execute]
    commands: ['\bgit\b[^;&|]*\bpush\b']
limits:
  tool_calls: {soft: 100, hard: 200}
network:
  fetch: []
mcp:
  allow: []
```

`agent_shield.policy.decide(action, context, policies)` 纯: 它回答 `allow | ask | deny`,句子, 以及决定的范围和规则.

三个级别维持: **联合国** 文档来自IAM **图像的** 规则是团队的,和 **届会** 上面的默认值加上一个人允许或收紧的内容 当它运行。 下层文件只收紧: `agent_shield.policy.widening` 在句子中,如果允许更多, IAM拒绝团队文件 和他们在一起, 运行时间拒绝 与他们的会话规则。 还有两个限制 按住模型 : `model_tokens` (预算)和 `spend` (信贷,每美元100美元), 柔软而硬; `decide_budget` 确定针对他们的下一个模式请求. A 类 `harnesses` 一节说,谁利用了一个范围承认,谁 证书管理他们.

由数据层管理`agent_shield.saas`),政策从IAM提取 在代理的创作, 保存到它的 `expires`,每30 s或 被推时 **未关闭**:与IAM相通而无穷 复制,吊带被拒绝 在句子命名IAM.

## 何为所建,何为所非

建造(0.1.2, 第0阶段和第二阶段的政策方面):政策 发动机及其图案, 三个级别 `widening`,模型限制和 `decide_budget`,则 `harnesses` saaS客户端从IAM中提取 未关闭 登记簿从 [代理规格](https://github.com/datalayer/agentspecs) (单位:千美元)`claude-code`, (中文(简体) ), `codex`, (中文(简体) ), `gemini-cli`, (中文(简体) ), `goose`, (中文(简体) ), `opencode`, (中文(简体) ), `openhands`, (中文(简体) ), `fast-agent`; 官方上的 stdio 和 WebSocket 客户端频道 `agent-client-protocol` SDK(protocol 第1版); 代理,通过 [ACP 测试兼容性套件](https://github.com/agentclientprotocol/acp-tck) 试验剂(`VERDICT: CONFORMANT`审计 `agent-shield` 命令; `@datalayer/agent-shield`政策类型.

建于0.1.7年 (中文(简体) ). (第3阶段独立部分): `agent-shield serve` 结束 WebSocket 和 ACP 可流回式HTTP,每个连接一个接合器 头或第一个消息(SH-52,SH-56); `agent-shield connect`; 桥 会 议 日 程 和 议 程 `datalayer-harnesses` 侧车(SH-40); `setup --register` 通过a 在注册的IAM交换服务代理密钥 `serve` 拉起来 政策和对OTEL的出口(SH-47,SH-73); 类型脚本 由图、图、图 `diff` 财务报告和审定财务报表 `terminal` 显示,报告 渲染器(SH-53);以CI建成的文件网站,其政策参考文献 和生成的注册,每个页面都保存在所建(SH-22).

未构建: Datalayer 校验标签( SH- 36) 中的盾牌报告; IAM 服务 服务代理的组织文件,登记为独立文件 盾牌等待(它不从任何物入手), Neovim and marimo(每个都需要一个窗口).

Claude Code已经运行在代理机后面(`claude-agent-acp` 0.91.0: (中文(简体) ) 初始化、 会话、 模式 ; 转弯需要获得资助的 Anthropic API 键 .

## 发展

```bash
pip install -e ".[test]"
pytest tests/ -q
npm install && npm test            # the TypeScript types against schema/policy.schema.json
make tck                            # the ACP TCK against the proxy (uv tool install acp-tck first)
```

## 文档

[代理屏蔽器 数据显示器 技术](https://agent-shield.datalayer.tech/)

## 常见问题

### @datalayer/agent-shield 是什么？

Agent Shield: 政策文件的类型和决定的句子,用于网络和电话\.

### 如何安装 @datalayer/agent-shield？

在项目目录运行 npm install @datalayer/agent-shield，或使用 pnpm add / yarn add / bun add。

### @datalayer/agent-shield 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @datalayer/agent-shield 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @datalayer/agent-shield 可以商用吗？

@datalayer/agent-shield 使用 BSD-3-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括，不构成法律意见，请以许可原文为准。

### @datalayer/agent-shield 的下载量有多少？

根据 npm 官方下载统计，@datalayer/agent-shield 在 2026/10/12 – 2026/11/10 这 30 天内被下载 2,082 次，日均约 69 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @datalayer/agent-shield 还在维护吗？

最新版本 0\.2\.20 发布于 2026/11/12（1 天前）；至今共发布 18 个版本，其中过去 12 个月发布了 18 个；首次发布于 2026/10/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。