DSAIL

dsail

pip install dsail — Jaxon 提供的 DSAIL 托管服务轻量客户端。

有些规则早已写在纸面上：分包合同必须包含哪些条款、指南将哪些条件视为不合格以及哪些条件可以缓解、衍生文档必须引用什么内容以及写入哪个字段、出口许可证的判定取决于哪些标准。没人需要模型对此发表意见。他们需要按照书面条件，对眼前的值进行判断，并且每次有人提出请求时都得到相同的结果。

DSAIL 正是为此而设计的。将书面政策转化为程序可检查的规则，并且每次都得到相同的答案。你根据已确定的政策编写规则集；服务将其编译为由内容哈希标识的正式规则集；模型提取声明值；服务评估每条规则中的每项断言。

结果按断言返回——TRUE、FALSE、UNKNOWN 或 AMBIGUOUS。没有总体判定、严重性或通过／失败等级；FALSE 应造成什么后果，由你决定。每条结果都附带断言名称和源文本，因此你可以展示作出判定的规则。模型无法确定的值以 "unknown" 传入，需要该值的断言会返回 UNKNOWN：未知也是一种答案，而不是猜测。

我们的处理流程中没有模型。 服务永远不会收到你的文档，也永远不会调用大模型。它会生成一份提示词包——每项声明对应一个提取问题、声明 JSON schema 和验证规则——供你在自己的模型上运行。在检查时通过网络传输的内容是受 schema 限定的声明字典。

如果你曾为此自行构思过设计，它大概就是这样：根据书面政策编译规则集，以内容哈希标识规则集，确保数月后的检查仍会评估经人工批准的确切字节，每次得到相同答案，每条结果都指出作出判定的规则，并由模型提取信息而不作出判定。这就是托管服务的用途，因此你不必在自己的代码库中编写并维护引擎。

不适用的场景：需要判断书面规则未涵盖事项的调用（例如严重程度、风险程度，或如何综合解读两条冲突规则）；需要计算数值或监测阈值；在请求时决定谁可以对什么采取行动。

这个软件包不包含解析器、编译器或求解器——所有形式化处理都在托管服务上进行。它提供 dsail.Client、dsail mcp 标准输入／输出代理、dsail serve 审核界面，以及用于代码仓库的 dsail init。文档的每个页面也都提供 Markdown 版本：https://docs.agents.jaxon.ai

安装

pip install dsail
dsail version

需要 Python 3.10 或更高版本。REST 客户端仅依赖标准库； mcp 依赖项用于 dsail mcp，且仅在该命令中导入。

六十秒端到端体验

dsail init                                    # once per repository; commit what it writes
cat > policies/expenses.dsail <<'EOF'
version 1.3;
// @ask amount What is the total amount of this expense claim, in USD?
// @unit amount USD
declare amount as numeric;
// @ask has_receipt Is an itemised receipt attached?
declare has_receipt as boolean;
assert receipt_over_75 { Implies(amount > 75 "USD", has_receipt) };
assert within_cap { amount <= 5000 "USD" };
EOF
dsail compile policies/expenses.dsail --review   # what a person would be signing
dsail prompt-pack policies/expenses.dsail --render
echo '{"amount": "120 USD", "has_receipt": false}' > claims.json
dsail check policies/expenses.dsail --claims claims.json --summary
dsail serve policies/expenses.dsail              # hand the reviewer the printed link

在生产服务中使用客户端

import dsail

client = dsail.Client()                                  # DSAIL_URL, DSAIL_CREDENTIAL honoured
compiled = client.compile(open("policies/expenses.dsail").read())
pack = client.prompt_pack(ruleset_hash=compiled.ruleset_hash)

claims = pack.empty_claims()                             # every claim "unknown" to start
for prompt in pack.prompts:                              # run each on YOUR model
    claims[prompt.claim] = my_model.extract(document, prompt.render())

def repair(current, failures):                           # the service names EVERY bad field at once
    for failure in failures:
        current[failure.field] = my_model.re_extract(document, failure.field, failure.expected)
    return current

result = client.check_with_repair(claims, repair, ruleset_hash=compiled.ruleset_hash)
for assertion in result.assertions:
    print(assertion.name, assertion.check, assertion.source)
violated = result.where(dsail.FALSE)                     # your system decides what a FALSE costs

错误会以异常形式抛出，你可以据此分支处理：ValidationRejected（带有 .failures）、CompileFailed（带有 .diagnostics 和 .hint）、 BudgetExceeded、RulesetNotFound、BadRequest、EvaluationLimitReached 以及 ServiceUnreachable。每个异常都通过 .payload 携带服务的完整错误信封。

示例

• examples/expense_service.py — 一个贴近生产环境的集成示例：编译仓库策略，获取提示词包，在你自己的模型上运行提取（附带了一个替代提取器，因此无需模型也能运行），检查并修复，然后判断 FALSE 或 UNKNOWN 会造成什么后果。针对 DSAIL_URL 运行 python examples/expense_service.py；由 test/test_examples.py 覆盖。
• examples/adverse_action.py — 将相同的模式用于监管流程：依据 Regulation B（12 CFR 1002.9）处理不利行动通知，在 examples/policies/adverse_action.dsail 中为每个条款设置一条规则，每条规则都以其执行的条款命名。FALSE 会将通知退回，UNKNOWN 会将其暂缓处理。操作指南：https://docs.agents.jaxon.ai/guides/adverse-action-reasons.md。也由 test/test_examples.py 覆盖。
• examples/typescript/ — 一个根据随附的 OpenAPI 文档通过 openapi-typescript 生成类型的 TypeScript 客户端，带有自动获取的评估凭证，以及一个能返回正确结果的演示。examples/typescript/run.sh <url> 会在仓库的 Node 镜像中运行代码生成、类型检查和演示；生成的客户端中没有任何内容是根据网络传输数据手动输入的。

由编码 Agent 执行审查

Claude Code 和 Codex 都不会渲染审查组件，因此代理还提供了托管服务不具备的一个工具：dsail_open_review。Agent 会将其编译的源码（或文件路径，或已存储的名称）传给该工具；代理在 Agent 的 shell 沙箱外运行，且在整个会话期间持续运行，它会在你的机器上启动审查 UI，打开浏览器并返回链接，然后 Agent 会将链接转发给你。在该页面上批准后，服务会记录对应精确哈希值的批准信息。没有 MCP 层时，可将 dsail serve 作为命令启动同一个页面；系统会指示 Agent 将该命令交给你，而不是让它在沙箱 shell 中运行。

网络受阻时

在禁止 shell 发起出站调用的环境中（目前包括 Claude Code 云会话和 Codex 云任务），每次调用都会引发 EgressBlocked，其文本专为原样转告他人而编写。该文本会指出当前进程所在 Agent 环境对应的解决方法，并且只提供这一种：

• Claude Code： 在 claude.ai 中启用 DSAIL 连接器（Team 管理员可在整个工作区启用；连接器通过平台基础设施提供服务，而非经由沙箱出站网络路径），或将 DSAIL API 域名添加到工作区网络允许列表。
• Codex： 将 DSAIL API 域名添加到云环境的互联网访问允许列表。Codex 云任务没有 MCP 层，因此 REST 路径是唯一可用的路径。

检测会读取环境变量（CODEX_* 变量表示 Codex；CLAUDECODE 或 CLAUDE_CODE_* 表示 Claude Code）；DSAIL_AGENT_ENV=codex|claude 可覆盖检测结果。此时 CLI 会以状态码 3 退出，并输出相同的文本。

Codex

dsail init 同时适用于 Codex 和 Claude Code：技能文件也会写入 .agents/skills/dsail/SKILL.md，带标记的 [mcp_servers.dsail] 表会写入 .codex/config.toml。Codex CLI、IDE 扩展和 ChatGPT 桌面应用共用一份 MCP 配置，因此代理只需注册一次即可供三者使用。--no-codex 会跳过这两项操作。

dsail codex-plugin [DIR] [--app-id ID]（或 ./release.sh codex-plugin）会构建插件包：包含 .agents/plugins/marketplace.json，以及其中的 plugins/dsail/，内含 .codex-plugin/plugin.json、.mcp.json、技能文件；仅在使用 --app-id 时，还会包含 .app.json，其中以 OpenAI 分配的 ID 命名 ChatGPT 连接器。使用 codex plugin marketplace add <DIR> 和 /plugins 安装。此阶段为私有版本，绝不可提交目录。

在 Codex 云任务中，完全没有 MCP 层，CLI 和 dsail.Client 会通过 REST 承载整个工作流；AGENTS.md 中的说明会告知 Agent 这一点。环境的互联网访问允许列表必须包含 DSAIL API 域名。

条款、隐私和数据处理

托管服务依据带版本号的条款提供： https://docs.agents.jaxon.ai/legal/terms.md，其中 https://docs.agents.jaxon.ai/legal/privacy.md 和 https://docs.agents.jaxon.ai/legal/data-handling.md 说明了存储哪些内容（你的 规则文本和 DSAIL 源码，而不是你的文档）、绝不会如何使用这些内容， 以及如何确保唯一的衍生字段——由你自己的模型根据已发布的词汇表生成的 类别标签——无法指向任何人的策略。 dsail whoami（或 Client.account()）会在其 terms 块中报告适用于 你的凭据层级的条款版本。

凭据

无需注册。首次联系时，托管服务会返回用于签发评估凭据的路由，客户端会获取该凭据、将其保存 （~/.config/dsail/credential，仅你可读取）并重试——一条命令， 即可获得首个结果，无需人工审核。评估凭据可用于编译和检查，每日及整个有效期内都有额度上限，且会过期；服务会为其生成的每个结果标记 x-jaxon-credential-grade: evaluation，而 dsail whoami 会显示你相对于额度上限的使用情况。

存储——保存、列出、批准、添加单位转换器——以及生产环境用量需要 完整凭据，由 Jaxon 签发。使用 dsail credential set <token> 保存；代理和审核 UI 也会使用该凭据。评估凭据请求存储时会引发 CredentialScopeExceeded；超过额度上限时会引发 EvaluationLimitReached。这两种消息都是升级提示，设计为可直接向用户展示。

登录，以及为何仅有凭据不足以满足团队需求

凭据代表一个工作区。这足以用于编译、检查、保存、加载和批准，也正因如此，上述入门流程才能在无人参与的情况下直接发放凭据。

团队涉及的是人员——邀请这位同事、移除那位同事、让某人担任管理员——而凭据本身无法将这些操作归属到任何人名下，也无法在凭据泄露时追究任何人的责任。因此，这些操作需要由已登录的人员执行：

dsail login        # one browser round trip; stores ~/.config/dsail/session
dsail signed-in    # whether this terminal has a person behind it
dsail logout       # leaves your credential exactly where it is

dsail login 会通过此进程开启的环回监听器，运行托管服务自己的 OAuth 流程，监听器仅在所需的几秒内保持开启。你的 API key 不会受到影响——登录会在 API key 旁边添加身份，而不是将其替换，并且每次调用都会同时携带两者，因为它们回答的是不同的问题。你编写的程序应继续携带 API key：这些程序运行时背后无人操作，而这正是 API key 的用途。

团队协作：

dsail workspaces                                   # where you may work, and where you are
dsail team create compliance                       # starts empty
dsail team invite team-abc123 [email protected]      # a single-use link you pass on
dsail copy cap-policy --to compliance --from personal
dsail use personal                                 # switch back

团队的规则集会与所有成员共享，团队拥有独立的计费账户，无论你在哪里工作，使用团队规则集进行检查都会向该团队计费。完整指南：与同事共享策略规则集。

配置

变量	含义
DSAIL_URL	服务地址（默认：托管部署）
DSAIL_CREDENTIAL	要发送的凭据；否则使用 ~/.config/dsail/credential（dsail credential set）
DSAIL_SESSION	要发送的会话令牌；否则使用 ~/.config/dsail/session（dsail login）
DSAIL_CONFIG_DIR	两个文件的存放位置
Client(auto_credential=False)	不获取评估凭据；直接显示 401

分发

dsail 已发布到 PyPI，而此仓库是 Jaxon 私有源代码仓库的只读镜像，后者才是权威来源。此处的每次提交都由镜像自动化根据私有仓库中的提交生成；没有任何内容是手动提交到此仓库的，也无法将拉取请求合并到此仓库。请参阅 CONTRIBUTING.md，了解更改实际经过的流程。

给定的 PyPI 版本与此仓库中对应的 v 标签内容完全相同，因为同一次发布操作根据同一个源代码提交生成了两者。定期运行的差异检查会对此进行验证，并在不再一致时明确报错。

pip install dsail                     # the published package
pip install dsail==1.0.0              # a pinned version

此仓库也是 Claude Code 和 Codex 的插件市场：.claude-plugin/marketplace.json 和 .agents/plugins/marketplace.json 都指向 plugins/dsail/，其中包含一个提供 DSAIL 技能和 dsail MCP 服务的插件：Claude 的清单指定了托管服务，而 Codex 的清单会启动 dsail mcp 代理。在 Claude Code 中，运行 /plugin marketplace add JaxonAI/dsail，然后运行 /plugin install dsail@jaxon；在 Codex 中，运行 codex plugin marketplace add https://github.com/JaxonAI/dsail。此插件包由 dsail plugin-bundle 生成，并在每次构建时与软件包进行校验。

托管的 MCP 服务已在官方 MCP Registry 中登记为 ai.jaxon/dsail（此文件顶部的 mcp-name 注释用于让 Registry 验证此软件包属于该条目）。

支持从此镜像的检出副本构建，并且会生成与已发布制品相同的结果：

python -m build --sdist --wheel .

合约包由生成器生成

src/dsail/contract/ 根据服务自身的 API 定义生成，绝不手动编辑。它会在私有源代码仓库中重新生成并提交；发布流程不会基于过时的合约包进行构建，因此你安装的合约包始终与该次构建所依据的线缆协议合约一致。dsail.contract.versions() 会报告使用的是哪个版本。

测试

scripts/test.sh                       # the unit suite
DSAIL_TEST_URL=https://... scripts/test.sh   # and the live tests, against a running service

每次更改时，CI 都会运行单元测试套件；它无需凭据，也无需联网。