Deadlatch

Deadlatch

为你的交易 Agent 提供交易前门闩。 仅提供建议。

在了解其他内容之前，你需要知道三件事：

1. 你需要一个由自己控制、独立于各经纪商的拦截关卡。 如果 Agent 可以在你的账户上提交订单，那么 Agent 与经纪商之间的最后一道检查不应由 Agent 自己执行，也不应受限于某一家经纪商的界面或规则。
2. Deadlatch 不预测、不推荐，也不下单。 它只回答一个问题：这笔订单现在是否允许提交？ 它不是信号生成器，也不是经纪商。
3. 每个答复都附带原因、证据，以及 Linux/macOS 上的本地审计记录。 PASS / WARN / BLOCK 绝不是没有说明的结论——你可以看到触发了哪条规则、原因是什么，以及评估了哪些内容。持久化审计写入（init / append / repair / prune / shadow report）仅支持 Linux 和 macOS。在 Windows 上，软件包仍可导入，规则引擎 / Guard / CLI / MCP 仍可计算决策；但这些写入路径会因 audit_platform_unsupported 而安全失败。对已停止快照进行离线 verify / read 仍然可用。Windows MCP 是受限的集成路径，并非完整可信的审计链。

坦诚说明边界（请阅读）： Deadlatch 仅提供建议。它无法强迫从不调用它的 Agent 去调用它，也无法阻止忽略 BLOCK 的 Agent 在其他地方提交订单。是否调用 Guard 并遵循结果，由集成方决定。请勿将此工具视为防止损失的保障——它是一个拦截关卡，不是保险单。

• 许可证： MIT — 参见 LICENSE。
• 中文文档： README.zh-CN.md
• 安全： SECURITY.md · 贡献： CONTRIBUTING.md · 免责声明： DISCLAIMER.md

从这里开始

当前安装方式是经验证的 PyPI deadlatch==0.1.2， 于 2026-09-22 发布。稳定版 GitHub v0.1.2 Release 对应提交 b072e8a4d4b053e1d5a428dbb9c47e06652fbf4c；其 wheel/sdist 资产与 PyPI 原始文件一致。

pip install deadlatch==0.1.2

已发布的 MCP Registry 名称为 io.github.Diabloluo/deadlatch，版本为 0.1.2， 并于 2026-09-22 确认为已激活且为最新版本。本地 server.json 与该已发布版本一致。 下面的命令会直接启动经验证的 PyPI 软件包。

从 MCP 开始：

uvx --from deadlatch==0.1.2 deadlatch-mcp --policy policy.yaml --portfolio portfolio.json

--policy 和 --portfolio 是必需的本地文件。--audit-path 和 --kill-switch-path 为可选项。请仅使用虚构数据或你自己的模拟输入。Deadlatch 仅提供建议：它从不下单，也无法阻止从不调用它的 Agent。期权订单必须将经纪商提供的唯一完整合约代码用作 symbol。历史 GitHub 预发布版本仍为 v0.1.0.dev1；它不是当前安装方式。

接下来：

1. 在下方使用虚构数据完成快速入门（Python、CLI 或 MCP），并在 Linux 或 macOS 上运行。确认 PASS → BLOCK → 本地审计。Windows 可以导入软件包并运行规则计算，但不能用于审计写入快速入门。
2. 仅当你已有订单意图或模拟执行路径时，申请 20 分钟的集成评估：打开评估表单。

该 GitHub issue 是公开的。请勿粘贴账户、持仓、订单、API 密钥、令牌、客户姓名或私有路径。安全缺陷应通过 GitHub Security Advisories 提交，而非发布在公开 issue 中。

---

快速开始（每项 60 秒）

这三个快速开始示例均使用虚构数据和临时审计路径。测试套件会通过同一组源脚本执行这些示例，因此文档内容不会与实际代码脱节。完整的审计写入 / MCP 快速开始需要 Linux 或 macOS。 Windows 可以导入库并评估规则，但不会初始化或追加持久化审计集合。

1. Python API

pip install dist/deadlatch-*.whl        # or: pip install -e .
python docs/quickstart/python.py

演示 Guard.from_policy(...) → Order / Portfolio → guard.check(...)： 有效订单返回 PASS / 0；超额订单返回 BLOCK / 3，并列出命中的规则； 如果结果为 BLOCK，示例调用方会停止，不会调用经纪商。

2. CLI

bash docs/quickstart/cli.sh                  # requires `deadlatch` on PATH

在临时目录中创建新输入（时间戳动态生成，不会过时），然后运行 deadlatch check，分别检查 PASS（exit 0）、BLOCK（exit 3）、输入错误（exit 4）和 --json 检查，并对审计日志运行 shadow report --json。

3. MCP（stdio）

python docs/quickstart/mcp_client.py         # requires `deadlatch` installed

通过 stdio 将 deadlatch-mcp 作为真实子进程启动，列出五个工具，并分别调用一次 check_order 来检查 PASS 和 BLOCK。policy / portfolio / audit 路径属于服务启动配置，Agent 无法将它们作为工具参数替换。调用方必须遵守 BLOCK 这一约束；从技术上说，守卫无法强制一个完全绕过它的 Agent 调用自己。

---

它是什么 / 不是什么

Deadlatch 是什么	Deadlatch 不是什么
提交前进行评估的本地确定性风险关卡	信号生成器、推荐工具或投资组合优化器
一个库、一个 CLI 和一个 stdio MCP 服务——不连接经纪商，不修改策略	经纪商适配器、执行引擎或市场行情源
可审计的检查：每次评估都会写入本地 JSONL 日志	云服务、数据库或遥测接收端
仅支持 USD、单腿订单，每次检查使用一个快照（v0.1）	多腿、多币种、感知 Greeks/IV（见限制）

适用对象

• 已有订单意图或模拟执行流程，并希望在交易前设置独立、确定性的关卡和本地审计跟踪的团队。
• 希望获得轻量、依赖少、默认拒绝的构建模块，并将其集成到自己的执行流水线中的开发者。
• 希望根据自己控制的策略评估订单，并以纯 YAML 表达策略的任何人。

不适用对象： 任何期待盈利保证、回测引擎、投资组合管理器或可自我执行工具的人。如果 Agent 从未调用守卫，或忽略 BLOCK，本仓库中的任何内容都无法阻止它。

核心安全边界

• **本地：**所有内容都在你的机器上运行；绝不会存储、读取或传输账户凭据。
• **核心路径不联网：**库、CLI 和 MCP 服务绝不会打开套接字、注册 HTTP/SSE 路由，也绝不会调用外部服务获取报价或执行其他操作（MCP SDK 的 HTTP 堆栈是传递依赖，业务代码绝不会导入它）。
• **绝不下单：**核心包（库、CLI、MCP 服务）不连接经纪商，也绝不提交订单。实验性的只读映射示例仅存在于开发工作区；不会包含在公开候选版本或 wheel 中，也不是经过实时验证的集成。
• **失败时默认拒绝：**数据缺失或格式错误 → BLOCK（exit 3）；输入／配置错误 → exit 4；内部错误 → exit 5。绝不会将不确定状态报告为 PASS。
• **方向从快照推导：**绝不接受订单方向文本作为平仓证明。只有当最新的投资组合快照包含数量充足、方向相反的匹配持仓时，才会识别股票和期权的平仓意图。对于期权，symbol 必须是经纪商唯一的完整合约代码；绝不可在不同到期日、行权价或权利类型的合约之间重复使用同一标的代码。
• **仅支持 USD（v0.1）：**任何货币不匹配（订单、投资组合、持仓）都属于输入错误（exit 4）；MCP 账户状态工具遇到不匹配时会默认拒绝。

**写入范围：**该工具绝不修改 policy、portfolio 或 kill-switch 状态，绝不连接经纪商，也绝不下单。有两类有意执行的本地文件写入：

1. 审计子系统：Guard.check() / check_order 会在逻辑审计路径旁边的 UTC 日期分片中追加一条经过清理的 v2 记录（保留 30 天）。追加操作是在共享锁下进行的有界尾部写入，不会重写历史记录。新集合在追加前需要显式执行一次 deadlatch audit init（或 initialize_audit_state）；Guard/MCP 绝不会自动迁移。deadlatch shadow report 和 deadlatch audit prune 会删除超出 30 个日历日范围的整个分片文件。deadlatch audit repair --quarantine 在隔离截断的尾部时，仍会使用锁文件／临时文件和 os.replace。普通追加无法跨文件实现崩溃原子性。POSIX 锁支持跨进程使用。v0.1.2 的持久化审计写入仅支持 Linux/macOS；Windows 写入方会收到 audit_platform_unsupported，不会跳过目录 fsync 并报告成功。
2. **显式迁移输出：**仅当你显式传入 --output 时，deadlatch migrate --output <file> 才会写入迁移后的文档。

这些规则、Decimal 阈值、退出码和期权代码要求的公开规范见 docs/rules-spec.md。

12 条规则（v0.1）

#	规则	防护内容
R1	kill_switch	全局开关：off / full（阻止所有操作）/ reduce_only（仅允许推断出的平仓订单）
R2	input_validity	订单通过架构、版本门槛、货币一致性和金额有限性检查（违规 → exit 4）
R3	max_order_quantity	单笔订单数量上限
R4	max_order_value	单笔订单名义价值上限（期权：价格 × 乘数 × 数量）
R5	max_symbol_exposure	每个标的的敞口（期权按行权价 × 乘数 × 数量计算）
R6	max_total_exposure	投资组合总敞口率
R7	cash_margin_check	交易后的现金底线和卖出期权保证金
R8	max_daily_loss	每日亏损率（损益 / 当日开始时的权益）
R9	max_drawdown	从峰值计算的回撤率
R10	order_time_validity	订单时效 / 未来时间戳（无法解析 → 安全失败并 BLOCK）
R11	data_freshness	投资组合快照时效性（未来快照 → 安全失败）
R12	missing_data_fail_closed	投资组合数据缺失 / 为空 / 格式错误 → exit 3（数据不可用 = 风险）

可选规则（R3–R7）通过 policy.yaml 中对应的配置键启用或禁用；缺失的可选键必须在 acknowledged_disabled 中声明，否则策略将被拒绝 （exit 4）。必需规则（R1、R2、R8–R12）永远不能禁用。

退出代码

代码	含义
0	PASS — 按给定内容允许该订单
2	WARN — 只有执行策略明确允许警告时才继续
3	BLOCK — 不得提交该订单（触发风险规则或安全失败数据检查）
4	输入 / 配置错误 — 调用方误用了 API，不属于风险事件
5	内部 / 规则异常 — 按 BLOCK 处理（安全失败）

在影子模式下，会记录内部判定结果（shadow_verdict），而外部映射结果为 PASS / 0；熔断开关命中以及 exit 4/5 永远不会被隐藏。

数据契约与迁移

架构采用版本化 JSON Schema 2020-12 文件，并随软件包一同发布： order、portfolio、policy、result、audit-record、shadow-report、 audit-maintenance-result、audit-prune-result、audit-write-state、 audit-state-result。 支持对旧版文档进行显式离线迁移：

deadlatch migrate --kind order    --input order_v1.json    [--output out.json]
deadlatch migrate --kind policy   --input policy_v1.json   [--output out.json]
deadlatch migrate --kind portfolio --input portfolio_v1.json [--output out.json]

迁移只转换已裁定的字段（例如，将策略 v1 的布尔型熔断开关转换为 off/full）；绝不会猜测业务字段。常规评估入口会拒绝旧版本（exit 4），而不会静默迁移。

审计日志

每次调用 Guard.check()，都会在逻辑路径旁边的 UTC 日期分片中追加一条 v2 记录（默认路径为 ~/.deadlatch/audit.jsonl，可通过 --audit-path / DEADLATCH_AUDIT_PATH 覆盖）。新集合必须先通过 deadlatch audit init / initialize_audit_state 初始化一次，才能追加；状态缺失时会拒绝写入，且不会扫描目录来重建状态。v0.1.2 之前的单文件仍可作为旧版 v1 读取。记录会经过架构验证和清理（明文中不包含凭据、Cookie 或绝对路径）。保留期限为30 个日历日的分片；追加操作不再重写历史记录。UTC 分片日期在获得集合锁后确定（使用默认时钟或显式指定的 now）。持久化的写入日期水位线（audit.jsonl.state.json）会拒绝任何早于已预留日期的 UTC 日期，即使中间间隔 30 或 365 天；原始日志和状态字节保持不变。水位线用于顺序控制，不是签名。evaluated_at 不会被改写。使用 deadlatch shadow report 或 deadlatch audit prune 删除过期分片。旧版文件不会自动删除。如果审计写入失败，返回结果只会在严重性方面向上降级：PASS/0 → WARN/2；BLOCK/3/4/5 保留原判定，只附加 audit_write_failed 警告——磁盘状态与返回的 Result 永不矛盾。参见 docs/audit-write-state.md。

v0.1.2 记录包含本地 SHA-256 哈希链（prev_hash / record_hash）。该链具有篡改可检测性，但不是数字签名，也不能防止篡改。能够重写整个目录并重新计算哈希的攻击者不在考虑范围内。若没有外部不可变锚点，仅凭哈希链无法可靠检测到当前最后一条记录或整个可见记录集被删除。

deadlatch audit verify 会扫描可见集合（旧版文件，以及 30 个日历日窗口内的 UTC 分片和 prune 保留的任何未来分片），不会更改内容或写入隔离区。过期分片可能仍未清理，因此不属于该链校验范围。对于现有集合，它可能会创建 .lock 旁文件，以便与追加／修复／清理操作共用同一把锁。损坏的旧版 v1行仍可通过 deadlatch audit repair --quarantine 隔离。v2 修复只会隔离最后一个分片中被截断的末行；哈希不匹配、ID 重复、版本降级和链中段损坏都会拒绝自动重新链接（退出码为 3，不写入任何内容）。Shadow report 和 MCP recent_decisions 会在同一把锁下读取相同快照，并在返回记录前验证哈希、链链接、重复 ID 和版本位置；遭篡改或降级的链不会作为可信历史呈现。v1 兼容性仅限旧版基线文件，且只在任何 v2 记录出现之前有效；UTC 日期分片中的 v1 行会被拒绝。有关 G1 选项方向修复的虚构说明，请参见 docs/postmortem-option-direction.md。

MCP 服务

deadlatch-mcp 是一个仅支持 stdio 的 MCP 服务（不监听 TCP，也没有 HTTP/SSE 路由）。这五个工具均为只读：它们都无法修改 policy、portfolio 或 kill-switch 状态（这些路径属于启动 配置，而非工具参数）。策略变更会经过验证，并在下一次工具调用时自动加载。每次调用时都会读取可选的独立 kill-switch 文件，且该文件只能让策略更加严格。请注意，服务仍会将每次 check_order 评估追加到本地审计日志中——这是设计如此，并非 工具功能。五个工具：

工具	用途
check_order	评估单笔订单；返回完整的 result（决策、退出代码、违规项、证据）
get_account_status	快照新鲜度、权益、现金、PnL、回撤、敞口利用率
get_policy	以只读方式展示生效策略
kill_switch_status	当前 kill-switch 模式（只读；没有工具可以更改它）
recent_decisions	最近的审计记录（按时间从早到晚，可选 since/limit）

使用以下命令启动：

deadlatch-mcp --policy policy.yaml --portfolio portfolio.json \
  [--audit-path audit.jsonl] [--kill-switch-path kill-switch]

路径参数仅用于启动配置；其文件内容仍是实时的本地状态。已配置的 kill-switch 文件必须且只能包含 off、reduce_only 或 full。它不能弱化策略中已有的更严格模式。实时策略/开关缺失、格式错误或在并发访问中不稳定时，系统会采取失败关闭策略：工具错误为 isError=true + fail_closed，配置错误则包含 input_error=true + exit_code=4。

演示

Agent 使用超额订单调用 check_order；守卫返回 BLOCK / 3 以及命中的规则；Agent 停止操作，而不是调用任何经纪商 工具。此演示使用虚构数据，生成自真实的本地 MCP stdio 运行 （tools/make_demo_gif.py）：

已知限制（v0.1）

• 裸卖看涨期权的上行风险没有上限。v0.1 使用基于行权价的敞口 近似值，不会对这种无上限尾部风险建模；不要将其视为卖出看涨期权的 保守上界。
• 卖空的现金流出建模为 0（已说明的简化处理）。
• 不支持希腊值、IV、多腿策略或多币种账簿。
• 跨进程审计锁依赖 POSIX fcntl；在非 POSIX 平台上，锁会降级为进程本地锁（不保证跨进程）。
• v0.1.2 的持久化审计写入仅支持 Linux 和 macOS。Windows 和其他平台会在创建锁或写入状态之前，拒绝执行 init / append / repair / prune / shadow report，并返回 audit_platform_unsupported。在受支持的平台上，文件和目录 fsync 失败时仍会采取失败关闭策略；不会将其视为“缺少功能”。仍支持对已停止的快照进行离线验证/读取。并发 Windows 写入不在支持范围内。
• 守卫无法阻止完全绕过：从不调用它的 Agent，或忽略 BLOCK 并直接调用经纪商的 Agent，都无法被此工具阻止。
• 仓库中的示例仅使用虚构的股票代码和数据。

治理

• SECURITY.md — 支持的版本、漏洞范围、报告方式。
• docs/rules-spec.md — 公开的 12 条规则约定。
• CONTRIBUTING.md — 环境、测试/模式/扫描/覆盖率命令、规则规范。
• DISCLAIMER.md — 完整的法律/风险免责声明（摘要见下文）。
• README.zh-CN.md — 中文文档。

**免责声明（摘要）：**不构成投资建议；不保证不会发生亏损； 请自行验证输入和规则；守卫绝不会下单；所有示例均为虚构；使用真实资金交易前请先测试；不提供 SLA。请参阅 DISCLAIMER.md 中的完整免责声明。