Deedglass

Agent 说它更新了 1 行，Postgres 却改动了 301 行。

Deedglass 位于 AI Agent 与它们会更改的系统之间。规则决定每次工具调用；检查会将系统实际更改的内容与 Agent 报告的内容进行比较（声称、已检查或已证明；匹配、不匹配或无法检查）；每项结果都会封存为签名记录，任何人都可以离线核验。它可以撤销某项操作更改的行。

在浏览器中试用 · 快速入门 · 文档 · 安全 · deedglass.com

有人要求 Agent 将订单 42 标记为已发货。它运行了一条 UPDATE，工具报告影响了 1 行。一个旧版触发器却在同一事务中发货了另外 300 个订单。这是 2026-10-14 执行快速入门最后一步时的实际输出（看到 … 的地方为缩略内容）：

$ npx -y deedglass init --trigger
…
✕ UPDATE order 42         Proven · Doesn't match · Postgres changed 301 rows in public.orders. The agent reported 1.
  expected   UPDATE 1 row in public.orders where id = 42 · sets status
  observed   UPDATE 301 rows in public.orders · 300 outside id = 42
…
✓ Trigger off             orders_ship_open_batch dropped
✓ Undo preview            Undo available · 301 rows in public.orders · 301 updates
    policy   undo-needs-approval · a person countersigns first

Agent 的日志显示 1 行。Deedglass 读取了 Postgres 自己记录的该事务变更日志，发现实际变更了 301 行，将差异封存为记录，并根据这些行规划了撤销操作，该操作只有在某人会签后才会执行。

_{运行 make demo-hero 的真实记录（提交 97a524c，2026-10-14），逐行展示内容打印时的状态。 来源：docs/assets/demo-hero.cast.json，由 scripts/demo/cast2svg.mjs 绘制。}

## 四种使用方式

	命令	所需条件	离开你设备的数据
在浏览器中	deedglass.com/play	一个浏览器标签页。Postgres 在页面中运行；打开后会显示「said 1, changed 301」场景。	无
在终端中	npx deedglass play	Node，以及从 npm 获取的 deedglass 0.1.1 或更高版本。无需 Docker。规则会实时决定每次调用，记录会在你的设备上封存并检查；Postgres 的操作记录则从一次录制的真实运行中重放，并明确标注为此类记录。	无
扫描你的配置	npx deedglass scan	Node。以只读方式读取你的 MCP 配置；如果你指定了数据库，也会读取其目录。评估你的 Agent 能进行哪些更改，等级从 A 到 F。	无，指定数据库的只读目录查询除外
观察模式	deedglass observe run --connector pg-demo -- ./agent.sh	启用了 observe 的 Postgres 连接器。无需改动现有配置：它会读取 Postgres 的更改日志，同时配合你已在使用的任何防护机制运行。	无

如果扫描发现 Agent 可以写入的表上有触发器或级联操作，就会提示你，并指向 301 场景。观察模式见下文。

快速入门

运行中的 Docker（约有 2 GiB 可用磁盘空间）、Node 18 或更高版本，以及 macOS 或 Linux（Windows 上使用 WSL 2），然后（参见已测试的快速入门指南）：

mkdir acme-agents && cd acme-agents
npx -y deedglass init --yes
npx -y deedglass doctor
npx -y deedglass init --trigger

deedglass init 会在 Docker 中启动两个 Postgres 18.6 容器（Deedglass 自有数据库和演示数据库），在 127.0.0.1:8080 上运行 deedglass serve，创建一个组织、一个 Agent 和 postgres-safe 策略，最后拦截 DROP TABLE，并在 Proven 级别检查一条 UPDATE。deedglass doctor 会运行 16 项只读检查，并为每项检查提供修复方法。deedglass init --trigger 会启用演示数据库的旧式触发器，发送同一条单行 UPDATE，最后展示上文所示的 301 行不匹配和撤销预览。

观察模式：无需改动现有配置

deedglass observe run --connector pg-demo -- ./agent.sh   # open a watched session, run the agent, close it
deedglass observe show obs_01k… --undo-sql                # the undo as SQL you review and run (free)
deedglass observe run --connector dev --undo-sql ~/deedglass-undo -- claude   # watch a Claude Code session, shell included

在连接器配置中设置 witness.observe.enabled: true 即可启用。观察模式只通过 deedglass connector postgres init 创建的角色和复制槽读取 Postgres 的更改日志，因此无论你是否已在使用防护机制，都可以配合运行。 它会显示会话打开期间在受监视表上提交的每一行，并将会话封存为记录。它无法判断是哪一个程序写入了某一行，因此会话不会获得「匹配」或「不匹配」判定；行映像会保留 30 天；无法通过记录撤销 TRUNCATE。撤销 SQL 可免费使用；通过 Deedglass 执行单步撤销则需 Pro。详情见：docs/OBSERVE.md。

工作原理

flowchart LR
  A["AI agents<br/>Claude · OpenAI · Cursor · any MCP client"] -->|tool call + agent key| G
  subgraph D["Deedglass · one binary + Postgres"]
    I[Identity] --> P[Policies] --> G[Rules]
    G --> W[Check] --> S[Records] --> L[Ledger] --> N[Insights]
  end
  G -->|credentials from the vault| T["Tools<br/>Postgres · GitHub · Slack · Stripe · MCP servers"]
  T -->|what actually happened| W
  H[People] -->|approve · stop| G

每次工具调用都会携带 Agent 的密钥经过 Deedglass。你的规则（策略）会决定是 allow、deny 还是 require_approval；Deedglass 会使用 Agent 从未持有的凭据执行调用；检查会将实际发生的情况与请求进行比较；结果会作为记录封存在组织的链中。

各级检查的可信度

级别	检查内容	无法观察的内容
Claimed	根据架构和你的后置条件检查工具自身的回答	回答是否属实
Checked	从目标读取回执（GitHub、Slack、Stripe、Notion、REST、Postgres 行）	读取回执未涵盖的副作用
Proven	Postgres 的更改日志（逻辑解码）：事务提交的每一行	DDL、序列、未记录表，以及该数据库 WAL 之外的任何内容

每条记录都会标注一个级别和一个结果：「匹配」、「不匹配」或「无法检查」。如果 Deedglass 无法确定工具是否运行，结果就是「无法检查」，绝不会是「匹配」。API 保留简短名称（L0/L1/L2、VERIFIED/MISMATCH/UNVERIFIABLE）；术语表中列出了对应关系。

它不做什么

• 已验证的检查仅覆盖 Postgres，并且需要在受监控的表上设置 wal_level=logical 和 REPLICA IDENTITY FULL。
• 如果 Agent 被劫持，但持有有效密钥且执行的操作符合策略，该操作就会被允许。策略、预算和审批可以缩小风险范围，但无法彻底消除风险。
• Deedglass 信任 Postgres 服务、其超级用户、运行 Deedglass 的主机以及其密封密钥。它无法保护你免受受感染主机的影响。
• 记录只保存摘要，不保存负载。一个实例中的所有组织共用一组密封密钥。
• 它不能替代最小权限数据库角色。两者应同时使用：角色限制 Agent 能做什么；Deedglass 检查它做了什么。

完整列表及应对方法：docs/LIMITATIONS.md 和 KNOWN_ISSUES.md。

替代方案

你可能不需要 Deedglass，也可能想将它与以下某个方案搭配使用。每个方案都有更详细的介绍，包括来源和核查日期，见 deedglass.com/compare。

如果你需要	使用此方案	Deedglass 的作用
只能读取数据的 Agent	仅包含 SELECT 权限的 Postgres 角色。无论 Agent 发送什么，它都无法更改数据，而且无需安装任何东西。	你不需要它。它适用于必须写入数据的 Agent。(比较)
供 Agent 尝试更改的环境	数据库分支：Neon 分支是数据的写时复制克隆；Supabase 分支默认不包含生产数据。	对于必须写入生产环境的操作：先应用规则，再进行检查和记录。(比较)
管理多个 MCP 服务的路由、隔离和凭据	MCP 网关，例如 Docker 的网关，它会在隔离的容器中运行每个服务并注入凭据。	部署在网关之后，用于处理写入 Postgres 的服务。(比较)
每一步的追踪记录和评估	Langfuse 或 LangSmith。	与它们搭配使用：追踪记录反映 Agent 一方的情况；检查则读取 Postgres 实际提交的内容。(比较)
在网络层为 Postgres、Kubernetes 和 HTTP 应用规则	Claw Patrol，它会根据解析后的流量，按规则控制每项操作。	它同样会先做出决定；此外，还会检查 Postgres 实际提交的内容、生成任何人都能离线核查的记录，并支持撤销。(比较)
扫描 Agent 发出的内容和工具返回的内容	Pipelock，一款双向扫描 MCP 流量的 Agent 防火墙。	它会在每次调用后检查 Postgres 实际提交的内容，并支持撤销对行的更改。(比较)

安装

方式	命令
npx（无需安装）	npx -y deedglass help
安装脚本（macOS、Linux）	curl -fsSL https://raw.githubusercontent.com/deedglass/deedglass/main/scripts/install.sh | sh
二进制文件	在最新版本中获取 macOS、Linux 和 Windows 的压缩包，附带 checksums.txt
Go	go install github.com/deedglass/deedglass/cmd/deedglass@latest（仅 CLI，不含 Console）
Docker	从检出目录构建镜像：make web-build docker（标签为 deedglass:dev；Console 由 Node 24 构建）

安装脚本会下载适用于你平台的发行版压缩包，将其 sha256 与发行版的 checksums.txt 进行核对，然后把 deedglass 复制到 ~/.local/bin；请先阅读脚本：scripts/install.sh。公开容器镜像即将推出；发布之前，请按上述方法在本地构建镜像。校验和、签名和 SBOM：docs/INSTALL.md。

添加到你的 Agent 客户端

在 VS Code 中安装 · LM Studio · Goose · Claude Desktop · 所有客户端

claude mcp add deedglass -- npx -y deedglass mcp serve

没有链接会携带密钥。先运行 npx deedglass init；每个客户端都会向 Deedglass 请求它写入的密钥。

Claude Code 插件（MCP 服务、/deedglass:scan、/deedglass:wrap 和 /deedglass:watch 命令，以及用于读取扫描结果和安全地为 Agent 提供 Postgres 访问权限的技能），来自此仓库自己的市场：

/plugin marketplace add deedglass/deedglass
/plugin install deedglass@deedglass

所有格式及其来源：docs/INSTALL_CLIENTS.md。

SDK 和客户端

• TypeScript： @deedglass/sdk，提供适用于 AI SDK、OpenAI Agents SDK、LangChain 和 Claude Agent SDK 的适配器。
• Python： pip install deedglass，提供 LangChain 和 Claude Agent SDK 适配器。
• Go： github.com/deedglass/deedglass/pkg/deedglass。
• MCP： deedglass mcp wrap 可管理任意 stdio MCP 服务；deedglass mcp serve 可为 Claude Desktop、Claude Code、Cursor、VS Code 和 Windsurf 管理远程服务。

连接器

Postgres（Proven）、REST、GitHub、Slack、Stripe（仅测试模式）、Gmail 草稿、Notion 和远程 MCP 服务。凭据存储在加密保管库中；所有出站调用都通过一个出口。参见 docs/CONNECTORS.md。

数据

项目	测量值	目标
Gate · 允许，无 witness	p50 5.81 ms · p99 19.4 ms	p50 < 5 ms · p99 < 25 ms（未达到 p50 目标）
Policy · 50 条规则	p99 148 µs	p99 < 1 ms
Witness · L2，100 次写入/秒	p50 118 ms · p99 317 ms	p50 < 1 s
Verify · 100,000 条 deed	1.53 s · 80.9 MiB	< 5 s · < 256 MiB
Stop · 跨 2 个实例	20 次测试中最大值为 23.5 ms	< 2 s

测量方法及未达标项：docs/BENCHMARKS.md。

安全

每个候选版本都会使用真实服务和真实 Postgres 运行包含 82 个用例的攻击套件： 82 项匹配，0 项不同（attack/results/latest.json，docs/ATTACK_SUITE.md）。 私下报告漏洞：SECURITY.md。

免费功能不会向 deedglass.com 发送任何内容：免费扫描会读取你机器上的文件；使用 --postgres-dsn-env 时，只会连接你指定的数据库。Pro 许可证会通过 Dodo Payments 和 deedglass.com 验证：deedglass serve 会在启动时验证一次，之后每天验证；Pro 命令会在运行时验证；距上次成功验证已满一天时会发送请求；如果时钟比上次验证时间或最近一次记录的时间慢超过 5 分钟，或 licence.clock 缺失、无法读取或已被修改，也会立即发送请求。deedglass licence activate、refresh 和 deactivate 始终会向外部发送请求。DEEDGLASS_NO_NETWORK=1 会阻止所有许可证验证请求，仅此而已： 使用 deedglass version --check，以及 deedglass policy install 和 policy packs 的 --latest 选项时，会联系 GitHub。 默认情况下不会记录头部时间戳；如果 deedglass.yaml 中列出了 TSAs 或透明度服务， deedglass deeds timestamp 和每次导出只会联系这些服务。 关闭网络后，Pro 最多可在上次成功验证后的 14 天内使用缓存令牌运行。每个请求携带的内容： docs/LICENSING.md。

贡献

请阅读 CONTRIBUTING.md：make dev、make ci、更改所需的测试，以及 DCO 签署（git commit -s）。如有疑问，请前往 Discussions（[SUPPORT.md](SUPPORT.md）；决策方式见 GOVERNANCE.md。

如果 Deedglass 发现了日志未能呈现的信息，给项目点个 GitHub 星标，有助于其他人找到它。

许可证

核心、SDK 和 CLI 使用 Apache-2.0 许可证。ee/ 中的 Pro 功能使用 FSL-1.1-ALv2 许可证，并会在发布两年后转为 Apache-2.0 许可证。发布二进制文件、@deedglass/cli-* npm 包和容器映像都包含 ee/，因此其许可证为 Apache-2.0 AND FSL-1.1-ALv2。

FSL-1.1-ALv2 允许你出于任何目的阅读、运行和修改 ee/，但不得提供竞争产品（ee/LICENSE）；Deedglass 为安全所做的一切都是免费的，且不在 ee/ 中（docs/LICENSING.md）。其余部分使用 LICENSE 中的许可证；第三方声明见 NOTICE。

记录规范（spec/：deed 格式和导出包）以及意图与效果语料库（corpus/）采用 CC-BY-4.0 许可证发布，任何人都可以在注明出处的前提下实现、复制或改编。