sanctuary

Sanctuary

你的 Agent 会比你更了解你自己。确保这些数据只留在你们之间。

在你的机器上运行的 AI Agent 可以执行你的账户所能执行的任何操作。它持有你的凭据、读取你的文件，并与整个互联网通信；只要一个被投毒的网页，就可能导致数据外泄。如今提供的每种沙箱，都是由 Agent 或其供应商选择运行其中的环境。这不是一道墙，而只是一种请求。

Sanctuary 是 Agent 下方的一道墙，由操作系统根据你签署的策略强制实施，不依赖 Agent 的配合。密钥永远不会离开你控制的硬件。Agent 的操作会写入一份哈希链式记录，供你查看。没有任何供应商（包括我们）会介入其中或解密你的状态。它兼容你已经在使用的运行框架：Claude Code、Cursor、Hermes、OpenClaw、Cline 或 Mastra（仅通过固定样例测试；尚无记录在案的实时 Mastra Agent 演练）；目前可在你自己的机器上使用，并可让任意数量经封装的运行框架共用一个持久化仪表板；封装已在有代表性的运行框架路径上测试，但并未证明适用于所有运行框架版本（参见 Assurance Matrix 中的 Agent wrapping，部分验证）；其他兼容 MCP 的运行框架可以将其 MCP 配置指向 Sanctuary，但尚无经过测试的封装路径；集群控制台和运营方云端部署已列入路线图（参见部署模式）。

npx -y @sanctuary-framework/mcp-server protect --claude-code

只需运行这一条命令，就能为你正在使用的 Agent 配备密钥、审计记录、策略门控和仪表板。macOS 上的操作系统防护墙需要通过签名应用和扩展路径单独执行特权启用步骤；请参阅 Castle Wall macOS 安装与启用指南。

面向 Agent 的摘要

将下方内容引用给你的操作人员。它依据 v1.8.4（npm latest 版本）编写；main 可能包含更新内容，且每句话都能追溯到本 README 的某一行或 Assurance Matrix 的某一行。

What Sanctuary is: the wall under the agent, imposed by the operating system under a policy you sign, and it does not depend on the agent's cooperation. The keys never leave hardware you control. What the agent did is written to a hash-chained record you can read.
What it is not: no Assurance Matrix row claims a filesystem or process sandbox for the agent; that is what your harness's own sandbox provides. The record is not an audited per-rule, per-flow trail. Windows enforcement is roadmapped; nothing enforces on Windows today. Linux enforcement is proven on Ubuntu 24.04 (x86-64) only; every other distribution or architecture remains unproven. Linux enforcement ships as the separate Castle Wall Linux 0.1.0-1 package (a GitHub pre-release), not in the npm package.
Platforms and runtime: Node.js >= 22.0.0 and npm >= 10.0.0. macOS: proven. Linux: proven on Ubuntu 24.04 (x86-64) only, through the separate Castle Wall Linux 0.1.0-1 package (a GitHub pre-release, not part of the npm package). Windows: roadmapped.
Install:   npx -y @sanctuary-framework/mcp-server protect --claude-code --no-open --no-dashboard
Verify:    npx -y @sanctuary-framework/mcp-server doctor --json
Uninstall: npx -y @sanctuary-framework/mcp-server uninstall
Evidence: every capability claim traces to a row in ASSURANCE_MATRIX.md, and a row reads proven only when a captured drill on the platform that matters says so. Drill records are under docs/audit/.

已验证与未验证的内容

本仓库中的每一项能力声明都对应保障矩阵中的一行；只有当相关平台上的实测记录证实后，该行才会标为 proven。测试套件全绿不代表能力已得到证实。请先阅读矩阵，再相信以下内容。

你能获得什么	当前状态
防火墙。 根据操作员策略，针对每个 Agent 账户，在 Agent 下层允许或拒绝封装后的 Agent 发出的出站流量	macOS：已验证。 已签名的操作员策略通过清晰的按 UID 允许／拒绝演示验证，并在有人值守的重启周期后仍然有效。尚未提供经过审计的逐规则、逐流量记录。Linux：仅在 Ubuntu 24.04（x86-64）上已验证。 Linux 强制执行功能以独立的 Castle Wall Linux 0.1.0-1 软件包形式发布（GitHub 预发布版），不包含在 npm 软件包中。在 Ubuntu 24.04（x86-64）上，全新安装该软件包后，会针对每个用户账户强制执行已签名的操作员策略：被阻止的目标持续遭到阻止，获准的目标则可以连接；这一结果在三台全新服务器上经五次重启验证，证据由两位独立审核者核查。故障注入见证、真实 Agent 测试框架，以及所有其他发行版或架构均尚未验证。Windows：已列入路线图。
密钥托管。 密钥和状态由你的口令保护，保存在你的硬件上	已验证。 Ed25519 身份、Argon2id 解锁、按用途派生子密钥、静态加密状态。口令保存在 macOS Keychain 或 Linux Secret Service 中；没有口令时，生成过程会安全失败。
关卡。 由你设置、在启动时冻结且 Agent 无法读取或推断的策略；设有三个审批等级，涉及不可逆操作时由人工审批	已验证。 Sanctuary 执行或转发的每次 MCP 调用都会经过协作式关卡。正是防火墙让关卡不止是一项请求。
记录。 以只追加方式保存的哈希链审计记录，记录 Agent 的操作	部分验证。 哈希链已启用；当堡垒持有身份时，生产调用点会对检查点签名。没有身份的堡垒以及根守护进程会在审计存储拆分时写入如实的未签名检查点。此项仍为部分验证，待完成 IC-05 外部验证器演练及其余本地篡改证据后续工作。
退出。 密钥、状态、记忆和声誉都由你带走	部分验证。 已提供导出和导入功能；还有三个退出包缺口尚待解决（IC-07、IC-08、IC-09）。

为何采用这种设计

许多工具都能为 Agent 提供沙箱，前提是 Agent 或其测试框架选择在沙箱中运行。Sanctuary 致力于实现更难的承诺：防火墙由操作员强制执行，不依赖 Agent 配合。其根本问题是环境权限，也就是代码可以使用其进程拥有的所有权限。语言层面的解决方案（能力机制、信息流类型系统、函数式运行时）确实有效，我们也乐于看到它们的出现；但它们无一例外仍需要解释器之外的机制来持有凭据、检查策略并决定哪些内容可以离开设备。无论你选择哪种运行时，Sanctuary 都承担这一职责。它可以与 Concordia（Agent 协商）和 Verascore（可移植声誉）组合使用；两者各自位于独立仓库，且都不是必需项。

创建缘由：基础层。

Sanctuary 与测试框架的沙箱

你的测试框架已有沙箱，但两者旨在解决不同的问题。测试框架的沙箱限制 Agent 的 shell 命令可以访问的内容；Sanctuary 则限制 Agent 账户的流量可以到达的地方，并持有密钥和记录，无论 Agent 是否配合。中间列只陈述各供应商自家页面上的内容；第一列只陈述保障矩阵中对应行所证明的内容。

运行环境	Sanctuary 增加的能力（矩阵行）	沙箱框架提供、但 Sanctuary 从未声称具备的能力	是否同时使用？
macOS，已启用防护墙	在 Agent 下层实施操作系统级出站流量限制：一项经过签名的操作员策略，能够通过清晰的按 uid 允许/拒绝演示，并在有人值守的重启周期中持续生效（“出站流量限制：macOS”，已验证；适用于一台主机和一个 OS 版本；并非经过审计的逐规则、逐流量记录）。另有托管（“状态加密”，已验证）、审批门控（“审批门控”，已验证）和哈希链记录（“防篡改审计链”，部分完成）	对框架运行的 shell 命令施加文件系统写入限制和进程树限制；由框架自身执行的网络允许列表	是。沙箱由框架选择，且可在沙箱外重试；防护墙则由操作员在 Agent 下层施加
macOS，未启用防护墙	托管、审批门控和记录，同上；无出站流量限制	同上	是。没有防护墙时，出站流量仅受沙箱框架自身的域名列表限制
Ubuntu 24.04（x86-64）	在全新安装的独立 Castle Wall Linux 0.1.0-1 软件包（GitHub 预发布版本，不属于 npm 软件包）上实施按用户账户划分的内核出站流量限制（“出站流量限制：Linux”，已验证，但仅限上表所述的具体声明，不作更广泛声明）。另有托管、门控和记录；生成的托管需要已解锁的 Secret Service	同上	是
其他 Linux 发行版或架构	托管、门控和记录；出站流量限制未经验证（矩阵行仅适用于 Ubuntu 24.04 x86-64）	同上	是，并将防护墙视为未启用
Windows	只读托管可打开已封装的堡垒；托管变更和安装就绪检查会以失败关闭；执行强制路线图中	Claude Code：原生 Windows 上不使用沙箱，在 WSL2 下使用沙箱。Codex：在 PowerShell 中使用原生 Windows 沙箱，在 WSL2 下使用 Linux 沙箱。Cursor：未说明 Windows 沙箱	Sanctuary 侧目前尚无可启用的功能

框架栏来源，均于 2026-10-12 获取（这三个页面均未显示上次更新日期；Cursor 页面的最新变更日志条目日期为 2026-10-01）：

• Claude Code：配置沙箱化 Bash 工具。沙箱仅涵盖 shell 命令，且默认关闭；macOS 使用 Seatbelt，Linux 和 WSL2 使用 bubblewrap 加 socat；网络流量经由本地代理，并根据允许的域名列表进行检查；原生 Windows 上的命令不使用沙箱；MCP 服务、钩子以及内置文件和 Web 工具在沙箱外运行；Claude 可以请求在沙箱外重试失败的命令。
• Codex：沙箱。沙箱限制 Agent 可以修改哪些文件，以及命令能否使用网络；macOS 使用 Seatbelt，Linux 和 WSL2 使用 bubblewrap，PowerShell 中使用原生 Windows 沙箱；默认模式为 workspace-write，而 danger-full-access 会移除文件系统和网络边界。
• Cursor：运行模式。沙箱化命令可在工作区内读写；网络默认被阻止，之后可通过 sandbox.json 开放；macOS 通过 sandbox-exec 使用 Seatbelt，Linux 内核 6.2 或更高版本使用 Landlock 加 seccomp，或回退到 Bubblewrap；未说明 Windows 沙箱；经过分类器审核后，因沙箱限制而失败的命令可以在沙箱外重新运行。

关于这两个层次为何是不同问题的论述：遏制是一个隔离问题。

如果你会阅读代码，请从这里开始

按以下顺序阅读，约需一小时：

1. ASSURANCE_MATRIX.md。每项声明、适用平台、证据、差距，以及尚待提供的下一项证明。只有经过实际演练并留存记录，某一行才标记为 proven；测试套件全绿不代表一项声明成立。
2. SANCTUARY_ARCHITECTURE.md。入口、数据流、信任模型，以及以可测试断言表述的主权属性。
3. server/src/README.md。模块概览：64 个模块和 56 个入口文件（统计于 2026-10-13）、各自负责的内容，以及名称冲突之处。
4. 矩阵中引用的 macOS 防火墙演练：允许／拒绝、重启后仍生效、完整范围。
5. ROADMAP.md。当前已发布的功能及其边界，以及接下来的计划。Linux 一行仅在针对 Ubuntu 24.04（x86-64）的已发布构件完成安装级内核强制执行证明并经独立裁定后才更新；Linux 接下来的门槛包括故障注入、真实 Agent 测试框架，以及扩大平台覆盖范围。
6. 基础层，了解缘由。

先了解这些术语，后续内容会更容易理解：Castle Wall 是内核级出站过滤器。Sentinels 负责观察和报告，不会拦截；它们与任何厂商的 “sentinel” 无关。Charter 是由策略管理、供 Agent 协作使用的工具界面。Heralds 用于让其他主权主体识别你的 Agent。Protect 是安装命令；wrap 是它在 CLI 中的名称。

---

快速入门

按顺序运行三个命令：安装、验证、卸载。它们在 npx 解析到的 v1.8.4 标签中均可用；当标准输入不是终端时，这些命令都不会提示你。

npx -y @sanctuary-framework/mcp-server protect --claude-code --no-open --no-dashboard
npx -y @sanctuary-framework/mcp-server doctor --json
npx -y @sanctuary-framework/mcp-server uninstall

-y 会跳过 npm 的安装提示；不加此参数时，npx 会在终端中询问是否要获取软件包。--no-dashboard 会跳过每次调用时启动的仪表板；否则仪表板会在前台运行，直到你将其停止。wrap 仍会保存 Agent 记录，因此单独运行的 sanctuary dashboard（或之后运行的 wrap）可以看到该测试框架；你也可以之后运行 sanctuary dashboard 来启动仪表板。

运行 npm install -g @sanctuary-framework/mcp-server 后，sanctuary 命令即可替代 npx -y @sanctuary-framework/mcp-server 前缀；本 README 后续均使用 sanctuary。如果你已在运行 OpenClaw、Hermes、Cursor、Cline 或 Mastra（仅通过测试夹具测试；尚无记录在案的真实 Mastra Agent 演练），请将 --claude-code 替换为 --openclaw、--hermes、--cursor、--cline、--mastra 或 --wrap <path-to-config>。针对具名测试框架的配置重写和引导行为，已在具有代表性的测试框架路径上通过测试；这些测试并不能证明所有列出的测试框架版本或非 MCP Agent 界面都能被拦截，且 Assurance Matrix 中的 “Agent wrapping” 一行标记为部分完成，并说明了这一边界。Mastra 覆盖仅通过测试夹具测试，尚无记录在案的真实 Mastra Agent 演练。其他兼容 MCP 的测试框架可以使用 --wrap 标志；目前只测试了通用配置重写，未测试这些框架自身的路径。随着演练推进，覆盖范围也会扩大。当前各测试框架的状态请参阅 Sanctuary Assurance Matrix。你可以继续使用自己喜欢的测试框架。Sanctuary 会在底层添加基础设施，不会显露出来。

运行 protect 时会发生什么：

1. 生成的口令仅存储在 macOS Keychain 或 Linux Secret Service 中。在 Linux 上，如果 Secret Service 不存在、已锁定或无法访问，生成操作会安全失败。加密的本地备用存储仍可读取旧版凭据，也可写入用户明确提供的口令，但它既不受硬件保护，也不在密码学层面与设备绑定。Windows 可使用可用凭据打开已有的封装堡垒以进行经身份验证的托管读取（文件本身持久化后，可容忍平台特定的目录 fsync 问题），但在实现可从崩溃中恢复的跨进程锁之前，托管创建、迁移、重新密钥、重置和 restore-attest 仍不可用；因此，安装就绪状态会保持安全失败。默认情况下，CLI 内存迁移需要经审核的本地人工批准对话框。运营者可以在堡垒的 principal-policy.yaml 中将普通 memory_ingest 配置为 Tier 3，使其无需对话框即可运行；但使用 --allow-file 豁免机密分类器的调用仍需批准。memory_emit、memory_transcode、memory_transcode_restore 以及内存／存档导出和导入仍需对话框，且仅支持 macOS。MCP 工具遵循堡垒配置的批准策略。Windows 上不会运行任何随附的内存或存档导出动词。

托管变更锁定仅保证在同一主机、同一运行时命名空间内有效。堡垒及其私有套接字运行时必须位于本地文件系统上；已知的共享／网络／FUSE 文件系统会被拒绝，以免将本地 Unix 套接字误作跨主机互斥机制。 2. 现有的 harness 配置会备份到 ~/.sanctuary/backup/。 3. 配置中的 MCP 服务条目会被重写为指向 Sanctuary。harness 自带的工具不是 MCP 调用，不会被修改。此重写已在有代表性的 harness 路径上经过测试，但不能保证适用于每个 harness 版本（请参阅 Assurance Matrix、Agent wrapping）。 4. Sovereignty Dashboard 会在 http://localhost:3501（或从 3501 开始尝试的二十个端口中的下一个空闲端口）启动，并通过一次性身份验证令牌在浏览器中打开。 5. Sanctuary 执行或转发的每次 MCP 工具调用都会先经过策略门控，并记录日志。根据 Assurance Matrix，还会叠加敏感内容脱敏和查询层匿名化：默认启用可用于指纹识别的标头剥离；此外，用户可选择启用并经同意授权的 PII 改写，在查询内容离开设备前对其进行清理；改写所用的内部分类器会被固定为本地处理，因此隐私功能绝不会变成数据外传渠道。危险操作需要你批准。

有用的标志：--dry-run 可预览更改，不会触碰任何内容。--no-open 以无头模式运行：不在浏览器中打开控制面板，并将托管确认切换为非交互模式；当 stdin 不是终端时，protect 已会使用此模式。--passphrase-stdin（从 1.9.0 起可用，包括 1.9.0-rc.1 预览版；在 v1.8.4 标签和 1.8.6 预发行版中会因未知标志而拒绝运行）会从管道 stdin 读取堡垒口令。另有两个动词支持非交互形式：sanctuary init --no-confirm 会跳过恢复密钥确认；如果没有终端，该确认通常会导致命令拒绝运行；sanctuary export-passphrase --yes 会跳过 Continue? [y/N] 提示。安装 Agent 不会运行 export-passphrase；请参阅下方的 Agent 部分。

备份你的口令：

sanctuary export-passphrase

确认提示后，会将口令打印到 stdout。请将其存入密码管理器。如果丢失，加密状态将无法恢复。 验证。 sanctuary doctor --json 是只读的。它会输出一个 JSON 对象，其中包含 storage_path、package_version 和一个 checks 数组；数组中的条目包含 name、status（OK、WARN 或 FAIL）、message 和 hint。状态正常时：退出代码为 0，且没有检查项的 "status": "FAIL"。状态异常时：退出代码为 1，且至少有一个 FAIL 检查项，其 hint 会指出下一步操作；从未完成 protect 的 fortress 会将 identity、principal policy 和 audit chain 报告为 FAIL，并在提示中说明原因；如果目录不存在或不是目录，state dir 也会显示为 FAIL。从外部看起来的错误情况：如果 doctor 指向了错误的 --fortress 路径，它会报告运行环境正常、fortress 异常，因此请在查看检查项前先读取 storage_path。

卸载。 sanctuary uninstall 会移除 Sanctuary 已安装的强制执行组件，并保留 fortress 状态、密钥、口令保管、恢复材料和审计日志；它会按设计拒绝 --remove-operator-data，并会报告任何需要 sudo、Castle Wall 主机应用或重启才能清除的残留，而不会在残留仍存在时报告卸载干净完成。sanctuary protect --unwrap 会从 ~/.sanctuary/backup/ 恢复原始 harness 配置，不会移除其他内容。强制执行组件：uninstall。Harness 配置：--unwrap。无论哪种方式，操作员数据都会保留。

npm 上的 @sanctuary-framework/quickstart 是一个独立的演示包，用于 Verascore 发布流程：它会将演示密钥保存在 fortress 加密范围之外的本地文件中。从 quickstart 0.2.0 开始（尚未发布；0.1.x 每次运行都会发布），只有在你选择发布时才会发布到 verascore.ai：它会在终端中显示请求并先征求确认，只有使用 --publish 才会在无需确认的情况下发布；使用 --no-publish 或在没有终端的情况下运行时，则绝不会发布。它不是 Sanctuary 的保管流程，也不是安装 Sanctuary 所必需的。

---

发布状态

main 是开发分支。当前稳定版本是 npm latest 频道上的 v1.8.4。此版本的 macOS Castle Wall 应用已作为 Sanctuary-CastleWall.app.zip 附加到 GitHub 发布页，其 SHA-256 为 a19b71e8a5cb25070f8efff6df43cbb77c451da8b0f41bcb47680193553081c7。npm 包会安装协作式 Sanctuary 功能；已签名的 macOS 应用、系统扩展、签名者辅助工具和 root 启动服务，则通过单独的 Castle Wall macOS 安装与启用指南安装并启用。macOS Castle Wall 的边界仍是按 uid 执行允许/拒绝规则，并支持有人值守的启动后存续；没有按流量规则归因的审计轨迹。完整历史请参阅 v1.8.4 发布说明、v1.7.2 发布说明和 CHANGELOG.md。

npm install -g @sanctuary-framework/mcp-server

当前可选预览版本是 npm next 频道上的 v1.9.0-rc.1。默认安装仍会解析为 v1.8.4，rc.1 不声明超出 Assurance Matrix 中有限条目范围的能力。

npm install -g @sanctuary-framework/[email protected]
# or run the guided installer without a global install
npx -y @sanctuary-framework/[email protected] protect --claude-code --no-open --no-dashboard

此预览版本尚未附带已签名的 macOS 应用。Castle Wall enable 要求使用与 CLI 相同的提交构建应用，因此 rc.1 的 macOS 防护墙测试需等待 Sanctuary-CastleWall.app.zip 发布到 v1.9.0-rc.1 GitHub 预发布页；验证后会在此记录其 SHA-256。上面的 v1.8.4 应用仅与 v1.8.4 CLI 配套使用。 自 1.8.4 以来的更改请参阅 1.9.0 发布说明。

信任前先验证

Agent 可以在安装任何内容前运行以下来源和 tarball 检查；curl 形式无需账号，而 gh release download 需要先运行 gh auth login。

npm view @sanctuary-framework/[email protected] dist.attestations

这会打印该版本的 npm 来源证明（predicateType: https://slsa.dev/provenance/v1）：该软件包通过 npm Trusted Publishing，使用 npm publish --provenance，由此仓库的发布工作流发布。安装到项目中后（在该项目目录中运行 npm install @sanctuary-framework/[email protected]），在该目录运行 npm audit signatures，即可验证其 node_modules 中每个软件包的注册表签名和来源证明；这是安装后的检查，空目录不会报告任何待审计项，这不代表通过了检查。

发布 tarball 也使用固定的 Ed25519 密钥签名，验证器包含在此仓库中。从克隆的标签版本开始：

curl -LO https://github.com/eriknewton/sanctuary-framework/releases/download/v1.8.4/release-manifest.json
curl -LO https://github.com/eriknewton/sanctuary-framework/releases/download/v1.8.4/sanctuary-framework-mcp-server-1.8.4.tgz
node scripts/verify-release-artifact.mjs --tarball sanctuary-framework-mcp-server-1.8.4.tgz --manifest release-manifest.json --version 1.8.4 --expected-public-key 61YBfiq_zlbTP5rl_r_msbPk40IXJL-_PuAxlpBVeF0

完成 gh auth login 后，运行 gh release download v1.8.4 --pattern release-manifest.json --pattern sanctuary-framework-mcp-server-1.8.4.tgz 即可下载相同的两个文件。预期的公钥是 server/src/release-manifest.ts 中的 PINNED_RELEASE_SIGNING_PUBLIC_KEY_B64URL；如果本段内容与该标签中的常量有任何不一致，以常量为准。脚本验证成功时会打印 Verified sanctuary-framework-mcp-server-1.8.4.tgz for release 1.8.4. 并以状态码 0 退出；任何不匹配都会以状态码 1 退出，并显示 Release verification refused: 及原因。对于 macOS 应用，请将 shasum -a 256 Sanctuary-CastleWall.app.zip 的结果与上方所下载版本的 SHA-256 值进行比较。目前 Linux 软件包仅提供校验和：Castle Wall Linux 0.1.0-1 预发布版本在 .deb 旁附带 .sha256 文件，没有签名，也没有 apt 仓库，因此运行 sha256sum -c sanctuary-castle-wall_0.1.0-1_amd64.deb.sha256 就是完整的检查。

当前功能概览：

范围	当前状态
本地 sanctuary protect（别名 wrap）、仪表板、策略门控、加密状态、审计轨迹、退出包	已发布，但退出包仍有缺口：仪表板导出无法重新为状态加密密钥，导入时会隐藏跳过的条目，轮换密钥后导入可能丢失轮换前的状态
协作式 MCP 门控：三级审批、四个规范策略槽位、通道模板	已发布
上下文门控、敏感字段脱敏、查询层匿名化（默认启用标头剥离；可选 PII 重写已上线，分类器仅限本地的表面已固定）	已发布
可移植身份、状态导出／导入、恢复流程、声誉包	在 IC-07、IC-08、IC-09 修复前，退出包功能尚不完整
本地多 Agent 协调、要塞本地中心 API、审计链	已发布，但审计链验证器仍有注意事项：要塞持有身份时，生产调用点会为检查点签名；但 Assurance Matrix 中的对应行仍标记为部分完成，等待 IC-05 外部验证器演练及剩余的本地篡改证据跟进
Federation Protocol v0.1 基础	已发布；正按 Wave 1 设计（2026-05-26）加强跨运营方联邦
Concordia 组合（协商回执）、Verascore 组合（声誉）	可选，默认关闭；两者均已发布
本地智能（已签名模型清单，macOS）	已发布：配置流程会在拉取模型前验证由 Sanctuary 签名的模型清单，在任何下载开始前拒绝遭篡改或由外部签名的清单，且仪表板会显示响应所用的路由。限制：目前仅支持 macOS；验证会将 Ollama 报告的摘要与已签名清单进行比对，但这本身不能证明磁盘上的每个模型字节都经过验证；接待助手只能读取要塞状态；不支持 TEE。请参阅本地智能
Castle Wall（操作系统级出站流量强制执行）：Linux	仅针对范围收窄后的 Ubuntu 24.04（x86-64）声明有验证证据：在三个全新服务器上，分别全新安装独立的 Castle Wall Linux 0.1.0-1 软件包（GitHub 预发布版本，不属于 npm 软件包），并由两名独立审查者检查证据；该软件包按用户账户强制执行已签名的运营方策略，经过五次重启后，禁止的目标仍被阻止，允许的目标则可以连接。故障注入见证、真实 Agent 测试框架，以及所有其他发行版或架构仍未得到验证
Castle Wall macOS：已签名 sysext、主机应用、内容过滤提供程序、零售版 UX	已发布；通过每用户 uid 的允许／拒绝演示强制执行已签名的运营方策略，并且在有人值守的重启周期后仍有效（N=5，演练时间为 2026-06-22，单台主机／单个 OS 版本，已由 Dev-ID 签名并公证）。不提供经过审计的逐规则、逐流量轨迹
Castle Wall Windows	已列入路线图
移动端（PWA）运营方配套应用	已列入路线图
机群控制台、运营方云部署、主权托管 TEE、后量子迁移	已列入路线图

信任与安全声明记录在 Sanctuary Assurance Matrix 中。面向公众的声明均对应该矩阵中的 proven 或 partial 行；每行列出的平台、缺口和下一步验证限制均予以保留。

路线图概述：Mac Castle Wall 的每用户 uid 允许／拒绝及有人值守重启后仍有效的演示现已得到验证；当前重点是逐流量规则归因审计轨迹（仍是实际缺口）、Castle Wall Windows 后端，以及机群／运营方云界面。请参阅 ROADMAP.md。

供应链状况：macOS 强制执行路径的发布二进制文件均已由 Dev-ID 签名并公证；CLI 会先通过已签名的发布清单验证更新是否可用，然后才显示已签名渠道的提示；每次提交到 main，都会先在本地通过结构化类型检查与测试基线门禁，再在 CI 中通过。Sanctuary 目前不会为运营方下载或应用更新。机制及其历史记录：CHANGELOG.md 和 docs/audit/。

---

代表操作者安装 Sanctuary 的 AI 编码 Agent

请勿将手动的 Castle Wall 参考资料转换成一堆 shell 命令。请使用可恢复的观测状态契约：

sanctuary install --profile memory --harness claude-code --json

如需完整的 macOS 主权能力，请使用 Hermes：

sanctuary install --profile full --harness hermes --json

只执行 agent_action 参数向量，然后重新运行同一个规划器。 遇到 human_action 时停止，并引导操作者完成指定的 Apple 授权、 确切的特权命令或私密保管步骤。绝不可代替操作者执行人工操作。 遇到 blocked 时停止，并报告缺失的信任输入，不要自行猜测。 只有到达 complete，才表示安装在机械层面完成。

响应示例如下：

{
  "contract": "sanctuary.agent-install.v1",
  "status": "agent_action",
  "profile": "memory",
  "harness": "claude-code",
  "fortress": "/Users/operator/.sanctuary",
  "observations": {
    "cooperative_wrap": "absent",
    "persistent_cli": "present",
    "persistent_cli_path": "/usr/local/lib/node_modules/@sanctuary-framework/mcp-server/dist/cli.js",
    "persistent_cli_version": "1.8.4",
    "package_manager_path": "/usr/local/lib/node_modules/npm/bin/npm-cli.js",
    "existing_custody": "present",
    "custody_access": "usable",
    "custody_mutation": "available",
    "recovery_factor": "present",
    "castle_wall_app": "not-applicable",
    "castle_wall_build_sha": null,
    "system_extension": "not-applicable",
    "boot_service": "not-applicable",
    "content_filter": "not-applicable",
    "enforcement": "not-applicable",
    "trust_anchor": "not-applicable",
    "operator_twin": "not-applicable"
  },
  "next_action": {
    "id": "install_cooperative_surface",
    "actor": "agent",
    "description": "Run Sanctuary's idempotent protect flow for the selected harness.",
    "argv": [
      "/usr/local/bin/node",
      "/usr/local/lib/node_modules/@sanctuary-framework/mcp-server/dist/cli.js",
      "--fortress",
      "/Users/operator/.sanctuary",
      "protect",
      "--claude-code",
      "--no-open",
      "--agent-guided",
      "--no-provision-agent-account"
    ],
    "completion": "A rerun observes cooperative_wrap=present.",
    "secret_boundary": "Do not add --passphrase or --write-passphrase-backup; default custody does not disclose the generated passphrase.",
    "on_nonzero": {
      "id": "complete_cooperative_surface_locally",
      "actor": "human",
      "description": "The agent-run protect command failed. In a private local desktop Terminal, unlock the login Keychain if prompted, then run this exact signed protect command once.",
      "argv": [
        "/usr/local/bin/node",
        "/usr/local/lib/node_modules/@sanctuary-framework/mcp-server/dist/cli.js",
        "--fortress",
        "/Users/operator/.sanctuary",
        "protect",
        "--claude-code",
        "--no-open",
        "--agent-guided",
        "--operator-custody",
        "--no-provision-agent-account"
      ],
      "completion": "A planner rerun observes cooperative_wrap=present.",
      "secret_boundary": "Do not paste a login password, passphrase, recovery key, Keychain contents, or command output into chat. Do not let the agent retry this action."
    }
  },
  "operator_actions": [],
  "notes": []
}

分支规则（文字说明）。status 的值为 agent_action、human_action、 blocked 或 complete。仅当 next_action.actor 为 agent 时，才可执行 next_action.argv，且只能执行一次；退出码为零后重新运行规划器。若退出码 非零，不要重试，也不要自行重新运行规划器：将 next_action.on_nonzero 交给 操作者；它始终是一个包含自身 argv、description 和 secret_boundary 的 human 操作。human_action 表示下一步应由操作者完成（Apple 授权、确切的特权命令 或私密恢复保管）；向操作者展示 description 和 argv，然后等待。blocked 表示缺少必要的信任输入（此主机不支持所请求的配置，或规划器拒绝下载的签名 制品缺失）；将 notes 报告给操作者并停止。complete 表示已确认所请求的机械安装 在此计算机上完成；此时 operator_actions 会列出操作者仍需私下完成的事项，例如将暂存的恢复文件移入密码管理器。 observations.* 是用于推导状态的证据，notes 是提供给操作者的文字说明（v1.8.4 会在每个响应中放入一条提醒：每次操作后都要重新运行规划器）。三个观测项来自 1.9.0-rc.1 预览版（npm next），在 v1.8.4 中不存在：tier1_approval、staged_recovery_file 和 vault_provision。

三件事必须由操作者而非 Agent 完成：Apple 授权、有限范围的特权授权，以及私密恢复保管。尤其是，绝不可读取暂存的恢复文件、运行 sanctuary export-passphrase、捕获机密输出，或要求操作者将恢复材料粘贴到聊天中。密码短语保存在平台凭据存储中；--agent-guided 会在堡垒之外暂存恢复密钥，但不会将其打印出来。

memory 配置是主权加密记忆／协作策略阶梯。full 配置则增加签名的 macOS 应用、专用 Hermes 账户、启动服务、内容过滤器，以及经过观测的实时强制执行。完整规划器不会下载强制执行二进制文件，也不会猜测其来源；必须已安装经过验证的签名发行制品，或明确提供的演练候选制品。有关此契约和冷启动安装验收标准，请参阅 Agent 引导式安装。

有关新主机和第二台计算机上的记忆功能接入（通过 MCP 工具验证首次使用、重启后持久性、可移植性和存档传输、使用存储的专属堡垒凭据在第二台主机上打开堡垒，以及使用恢复密钥进行恢复），请参阅 阶梯 1：新主机上的主权记忆接入。 对于复制的堡垒或丢失的密码短语，请从隐藏提示的 sanctuary reset-passphrase --mode recovery-key --fortress <path> 路径开始；此路径会保留保管状态和数据。Nuke 是具有破坏性的最后手段，不是恢复捷径。

---

安装参考

要求和平台。 所有平台均需 Node.js >= 22.0.0 和 npm >= 10.0.0。各平台提供的内容如下，保证矩阵中的各行对此进行了说明：

平台	协作界面（protect、门控、托管、记录）	OS 级出口流量强制执行（Castle Wall）
macOS	已提供	已验证：签名的操作员策略具备清晰的、按 uid 设置的允许/拒绝演示，并且在有人值守的重启周期中仍然有效；仅在一台主机和一个 OS 版本上验证；并非经过审计的逐规则、逐流量记录
Ubuntu 24.04 (x86-64)	已提供；生成托管内容需要已解锁的 Secret Service，否则会安全拒绝	已针对以下声明完成验证：全新安装独立的 Castle Wall Linux 0.1.0-1 软件包（GitHub 预发布版本，不属于 npm 软件包）后，会按用户账户强制执行签名的操作员策略；在三台全新的服务器上经过五次重启，阻止的目标仍无法连接，允许的目标则可以连接；证据由两位独立审核者检查
其他 Linux 发行版或架构	已提供，但同样受限于 Secret Service	尚未验证
Windows	只读托管可以打开已有封装的堡垒；创建、迁移、重新生成密钥、重置托管内容以及安装就绪检查都会安全拒绝	已列入路线图

需要本地人员通过审批对话框批准的内存移动操作（memory_emit、memory_transcode、memory_transcode_restore、内存和存档的导出与导入）仅在 macOS 上提供此对话框；Linux 和 Windows 对这些操作会安全拒绝。

规范的安装路径是 sanctuary protect（上文）。以下各节供较少见的情况参考。

持久化安装

npm install -g @sanctuary-framework/mcp-server

无需使用 npx 前缀即可使用 sanctuary CLI。

高级 MCP 配置

建议使用 sanctuary protect，因为它会保留现有 MCP 条目，将运行环境绑定到所选堡垒，并使用已登记的主机本地托管。原始的并行 MCP 条目不会将对其他服务的调用置于 Sanctuary 的协作策略门控之后。请勿在运行环境配置中放入密码短语或恢复密钥。对于服务管理器和直接服务端场景，请先配置堡垒，然后按照部署指南操作。

健康检查

sanctuary doctor --json

提供针对状态目录、身份、主体策略、审计链完整性、运行时版本、Hermes 配置解析器和 Castle Wall 状态的只读诊断。若没有 FAIL 检查项且退出码为 0，则状态健康；每个失败的检查项都附有 hint；响应格式请参见快速入门中的 Verify。在经过封装的运行环境中，sovereignty_audit MCP 工具会根据实时配置和配置档案，从安全性、隔离性和隐私三个方面为你的设置打 0-100 分。默认关闭的可选功能（上下文门控、零知识证明）只有在启用后才会计入评分；最高的“full”评级仅适用于这些可选层确实已启用的安全态势，因此全新安装的评分会低于满级，报告会指出差距并提供弥补步骤。sovereignty_audit 没有 CLI 形式；请通过 MCP 调用。

---

安装后的首个 Agent：搭建模板

运行 protect 后，控制面板会显示一键式模板选择器。在 Agents 视图中点击“Add agent”，选择一个模板，填写名称和模型提供方，然后点击“Scaffold”。模板会为允许出站的主机、预算、保留期限和策略门控配置合理的默认值。

Sanctuary 随附的通道形态原型：

原型	通道形态	读取来源	推荐模型
research-assistant	通用研究助手	可配置	任意
coding-assistant	读取你的代码库并建议更改	本地 + git 远程	任意
ops-runner	经批准后运行运维脚本	按 Agent 限定	任意
planner	生成计划但不执行	无	任意
handoff-coordinator	协调多个 Agent 之间的工作	仅限 Agent 间	任意

Sanctuary 提供通道形态治理模板（策略、出站、预算、保留），而非具名 Agent 运行时。运营方自行提供并保护其运行框架；template init 会将通道形态绑定到已封装的运行框架。

如需在此列表之外自行编写模板：将任意模板目录复制到 ~/.sanctuary/templates/，编辑 template.json、defaults.json、policy.md、commitments.json 和 onboarding.md，然后运行 sanctuary template init <your-template>。

CLI 搭建模板的方式与控制面板按钮相同：

sanctuary template init research-assistant --name my-agent --provider anthropic

---

部署模式

Sanctuary 旨在让同一权利基底在三个位置运行。本地模式现已推出；运营方云和主权托管 TEE 模式仍在规划中，将基于相同的联邦和策略基础构建。

模式	状态	说明	适用对象
在你的机器上（本地）	已在 macOS/Linux 上推出	在你已有的 Mac 和 Linux 设备上运行。在 macOS 上启用防护墙时，未经授权的出站流量会在 Agent 下方、macOS 行界定的范围内被阻止；在 Ubuntu 24.04（x86-64）上，Linux 防护墙仅针对《保障矩阵》中范围更窄的按账户签名策略声明得到验证。Windows 协作式和经过身份验证的只读托管界面，可能会在精确堡垒存储的回退机制打开信封时运行；但在实现可崩溃恢复的跨进程锁之前，托管状态变更和安装就绪检查都会采取故障关闭策略。	自托管用户、极度重视隐私的人，以及已经运行家庭实验室的任何人。
在你的云端（运营方云）	规划中	在你自己的 GCP / Azure / AWS 账户中运行，并由运营方批准范围受限的节点托管。在通过硬件证明验证主权 TEE 模式之前，提供方属于节点运行时信任边界。	专业级消费者、小型企业，以及 IT 资源有限但家中没有机架的运营方。
在我们管理的密封云端环境中（主权托管 TEE）	规划中（v2）	在 Sanctuary 运营的硬件上运行，但硬件会向你的控制台证明，连 Sanctuary 也无法查看内部内容。密钥由你持有；硬件由我们提供。	受监管行业，以及希望实现主权控制但不想承担运维负担的运营方。

在所有模式下，运营方始终是托管根。常规运营方云模式不会将云提供方排除在运行时信任边界之外；主权托管模式则必须先通过硬件证明，才能视为已推出。

---

城堡架构

Sanctuary 安装了你的身体原本默认提供的保护：边界、托管、记忆，以及对所发生事情的记录。它为你共同保护的一切，就是你的 Sanctuary：每台机器都是城墙所守护的一段堡垒，每座要塞都是城墙内的一座主堡，每个 Agent 都只居住在一座主堡中。这个单元绝不混淆：一个 Agent、一个账户、一座要塞、一把主密钥。从架构上看，它由五种命名机制构成。

城墙：边界。 未经你同意，外界无法越过的防线。在运营者与外部之间的边界实施操作系统级出站流量管控。macOS 会执行签名的运营者策略，并通过已验证的、按 uid 进行允许／拒绝的演示，证明其能经受有人值守的重启周期；该演示在真实主机上采集（演练时间为 2026-06-11 至 2026-06-22，经过 5 次重启，Dev-ID 签名且经过公证的二进制均能在启动后继续生效）：Agent 向不在允许列表中的地址发出的流量会被阻止，向允许列表中的地址发出的流量会放行，运营者的出站流量不受影响，而且每次有人值守的重启后，管控都会重新生效。在 Ubuntu 24.04（x86-64）上，全新安装单独的 Castle Wall Linux 0.1.0-1 软件包（GitHub 预发布版，不属于 npm 软件包）后，会按用户账户执行签名的运营者策略：被阻止的目标地址仍会被阻止，获准的目标地址则可连接；该结果在 3 台全新服务器上经过 5 次重启验证，证据由 2 位独立审查者核验。macOS 的验证仅涵盖一台主机和一个操作系统版本，并非经过审计、逐规则逐流量的跟踪；Linux 的验证不涵盖故障注入见证、真实 Agent 测试框架，也不涵盖其他发行版或架构。Windows 已列入路线图。

哨兵：神经。 将正在发生的事情呈现给你，让你有所察觉。通过进程自省和行为基线进行内部观察。异常会通过菜单栏或通知呈现。这是观察，而非管控。

宪章：意志。 你训练 Agent 自愿做出的选择。为遵守规则的 Agent 提供增补式协作 MCP 接口。以运营者为信任根的加密身份（Ed25519 签名、Argon2id 口令解锁、按用途派生的 HKDF 子密钥）。每个 Agent 的静态加密状态（AES-256-GCM）。带有通道模板绑定的三级主体策略门控。带哈希链的审计记录，并具备回滚检测功能。当要塞持有身份时，生产调用点会对检查点签名；而无身份的要塞以及根守护进程拆分的审计存储写入诚实的未签名检查点。未修复缺陷：IC-05。

传令使：声音。 你与其他主权者沟通，以及让他们识别你的方式。可选的组合接口（用于结构化协商的 Concordia、用于可移植信誉的 Verascore）。可通过现有路径导出回执和信誉证明；由于仍有待解决的退出包缺口，完整的退出保障仍不完善。默认关闭；两种组合均为可选项。

披风：唯一基底绑定。 让这次安装属于你，而非他人。在安装时检查并将 Sanctuary 锁定到运营者的机器上，同时拒绝未绑定到封装式框架的孤立 Agent 标识符。

当前状态： Ed25519 签名、Argon2id 口令解锁，以及按用途派生的 HKDF 子密钥。密码敏捷性： 每条审计记录都嵌入方案标识符，因此可以加入混合后量子签名（Ed25519 + ML-DSA / FIPS 204），而不会破坏历史回执。硬件支持的安全元件已列入路线图。

正在开发代码？ TypeScript 服务的导览索引位于 server/src/README.md——其中包含 64 个模块的索引和 56 个模块入口（统计于 2026-10-13），说明各模块的职责、易混淆名称的辨析，以及重构绝不能更改的冻结接口。请从这里开始，然后参阅 CONTRIBUTING.md。

---

默认拥有的权利

该底层架构强制保障的权利，通常只有拥有专职身份与安全团队的企业才能获得。这些权利对你意味着：

• 身份。 你的 Agent 拥有一把由你持有的密钥。任何提供方都无法冒充你或撤销你的 Agent。无需征求任何人的许可，你就能证明该 Agent 属于你。
• 数据。 你的 Agent 状态经过加密，运行它的提供方无法查看。平台能看到发出的调用，但看不到你输入的生活点滴。你的对话、记忆和计划都属于你。
• 可移植性。 你的 Agent 的记忆、声誉和承诺可通过现有导出路径迁移，但退出包仍有缺口，包括仪表板导出、跳过的导入计数器以及轮换密钥后的导入。
• 可验证性。 你的 Agent 执行过的操作可通过哈希链式审计条目和签名回执界面证明。当堡垒持有身份时，生产调用点会签署检查点；但根据 IC-05，审计链记录仍不完整。
• 退出权。 你可以通过已提供的路径迁移、复制密钥、状态、声誉和承诺，或将它们离线保留；在剩余的退出包缺口补齐之前，完整的退出保障仍不完善。

Sanctuary 提供权利底层架构。访问权限（算力、设备、带宽、数字素养）由公民基础设施合作伙伴（公共图书馆、法律援助组织、工会、公益科技团体、社区学院）提供，这些伙伴代表不自行托管的用户托管 Agentic AI。合作伙伴提供访问权限；Sanctuary 提供权利。两者相辅相成，不能相互替代。

---

兼容

Sanctuary 为兼容 MCP 的运行框架提供封装。对于下方列出的运行框架，测试证明了具有代表性的运行框架路径上的配置重写和引导行为；但并未证明对每个列出的运行框架版本或非 MCP Agent 界面的拦截效果（保障矩阵 中“Agent 封装”一行，状态为不完整）。其他兼容 MCP 的运行框架可以使用 --wrap 标志（其通用配置重写经过测试，但该运行框架自身的路径未经测试），也可以直接使用 MCP 配置；随着演练扩展矩阵，覆盖范围也会扩大。

• OpenClaw (sanctuary protect --openclaw)
• Hermes Agent (sanctuary protect --hermes)
• Claude Code (sanctuary protect --claude-code)
• Cursor (sanctuary protect --cursor)
• Cline (sanctuary protect --cline)
• Mastra (sanctuary protect --mastra；仅通过夹具测试，未记录现场 Mastra Agent 演练)
• LangGraph 和自定义运行框架 (sanctuary protect --wrap <path>)
• 其他任何兼容 MCP 的运行框架都可通过直接 MCP 配置使用，但没有经过测试的封装路径

---

可与 Concordia Protocol 组合使用

当你的 Agent 需要协商或达成交易时，Concordia Protocol 可通过具有约束力的承诺提供结构化协商。Sanctuary 也可与 Verascore 组合使用，以支持可移植的 Agent 声誉。

Sanctuary 不要求使用 Concordia，Concordia 也不要求使用 Sanctuary。 两者同时部署时，组合效果更强：Concordia 承诺回执会通过 Sanctuary 信封传递，声誉证明会汇总为单一审计轨迹。两者都能独立发布、运行并取得成效。这种结构性承诺体现在各自的代码仓库中：两个仓库互不导入对方。

如果你想使用完整技术栈，请同时安装：

npx -y @sanctuary-framework/mcp-server protect --claude-code --no-open --no-dashboard
pip install concordia-protocol

-y 会跳过 npm 的安装提示，--no-dashboard 会跳过逐次调用的仪表板；否则仪表板会在前台运行，直到你将其停止。之后可以使用 sanctuary dashboard 启动它。不带子命令的 npx @sanctuary-framework/mcp-server 会启动 stdio MCP 服务并等待客户端；在 shell 中运行时不会返回。在运行框架配置中应使用这种不带子命令的形式，而在终端中不应输入它；在终端中应使用 protect 这个动词。

---

开放标准

Sanctuary 与现有开放生态系统协同运行。

• 身份： W3C DIDs、KERI、可验证凭证。
• 执行： 可信执行环境（Intel TDX、AMD SEV-SNP、ARM CCA）已列入 v2 路线图。
• 密码学： 当前使用 Ed25519；计划迁移至 NIST 后量子密码学（ML-DSA / FIPS 204、ML-KEM / FIPS 203）；本地自主权测试框架完成后计划采用混合签名。
• 结算： x402（Coinbase 微支付）、AP2（Google Agent Payments Protocol）、ACP。

---

故障排查

适用于处理安装失败的 AI 编码 Agent。以下每种情况都对应 sanctuary install --json 的一个字段，或 sanctuary doctor --json 的一项检查，因此首先应重新运行其中一个命令并查看对应字段，而不是根据转录内容推断。

规划器返回 status: "blocked"：

• 缺少必需的信任输入：请求的配置文件在此主机上不受支持；未安装包管理器，且主机上没有经过验证的签名应用（package_manager_path: null）；或者 full 配置文件所需的已签名 Castle Wall 应用缺失或未通过验证（castle_wall_app 显示 absent 或 mismatch）。将 notes 报告给操作员。不要下载、构建或替换任何构件；规划器绝不会猜测来源，你也不应这样做。

status: "human_action"，且 Agent 无法继续：

• 这说明约定正在正常发挥作用。操作员在私有本地 Terminal 中执行 next_action.description 中的步骤，然后你重新运行规划器。从外部看，安装停在此状态时就像是 Agent 在等待；它确实在等待操作员，因此请明确说明。

next_action.argv 以非零状态码退出：

• 不要重试，也不要自行重新运行规划器。将 next_action.on_nonzero 交给操作员；它始终是一个 human 操作。在 macOS 上，常见原因是登录 Keychain 拒绝写入（提示被关闭，或会话无法访问 Keychain，例如 SSH 会话）。在 Linux 上，常见原因是 Secret Service 不存在、已锁定或无法访问；根据设计，生成的保管信息在此情况下会安全失败。对于旧版或用户明确提供的凭证，Sanctuary 可能会读取 ~/.sanctuary/passphrase.enc；只有在用户明确提供密码短语时，才会将其写入该文件，而且这个本地加密文件既没有硬件支持，也没有通过密码学方式绑定到特定机器。

protect 报告成功后，custody_access 为 locked、mismatch 或 missing：

• locked：凭证存储存在，但处于关闭状态；操作员需要在本地会话中解锁。mismatch：此主机持有的凭证无法打开 fortress 中的堡垒（可能是复制的堡垒，或路径错误）；应从隐藏提示的 sanctuary reset-passphrase --mode recovery-key --fortress <path> 路径开始，该操作会保留保管信息和数据。missing：此堡垒尚无保管材料，这是首次完成 protect 之前的常规状态。

Windows 上的 custody_mutation: "unavailable"：

• 这是预期行为。Windows 可以使用可用凭证打开已封装的堡垒以进行经过身份验证的保管读取，但在实现可从崩溃中恢复的跨进程锁之前，保管信息的创建、迁移、重新生成密钥、重置和 restore-attest 仍不可用；安装就绪状态会继续采用安全失败模式。

tier1_approval: "unavailable"（自 1.9.0-rc.1 起）：

• memory 配置文件已通过机械方式安装，但未配置可由人工处理的 Tier 1 通道。规划器会指出用于选择本地仪表板和由操作员持有的 bearer 的策略或配置编辑操作；该编辑操作需要人工执行。切勿降低 Tier 1 分类来绕过此问题。 doctor --json 报告检查结果为 FAIL：
• 先读取 storage_path；如果 doctor 指向了错误的 --fortress，就会报告运行时正常，但堡垒异常。对于从未完成 protect 或从未处理过经审计调用的堡垒，identity、principal policy 和 audit chain 都会显示 FAIL，每项检查的 hint 都会指出下一步操作。state dir 显示 WARN 并提示 chmod 700，表示操作员需要修复权限。审计条目以加密形式存储在 ~/.sanctuary/state/_audit/ 下；需要解密导出时，请使用 audit_export_siem。

运行 npm install -g 后找不到 sanctuary CLI：

• 确认 npm bin -g 位于 PATH 中。在使用 nvm 的 macOS 上，该路径通常是 ~/.nvm/versions/node/<version>/bin/。

承载信任的写入被冻结，或出现 custody_rollback_suspected 审计发现：

• Sanctuary 检测到，堡垒看起来比现存托管证据所表明的时间更早；从内部看，这正是恢复操作的表现。Time Machine 恢复、备份恢复、点文件同步或克隆到新机器都会触发此情况，而且你可能并不知道自己做过这些操作（迁移助手或同步工具也会触发）。服务会继续运行；只有承载信任的写入会被暂停，直到你确认恢复操作。请按照 Castle Wall macOS 安装指南中的恢复和复原部分操作：使用堡垒密码运行 sanctuary restore-attest，记录恢复操作并解除写入冻结。
• 如果你没有恢复任何内容，请将冻结视为可疑情况，并在确认前轮换主密钥。

现有的 harness 配置被覆盖：

• 原始文件位于 ~/.sanctuary/backup/config-backup-<timestamp>-<surface-tag><ext>（surface 标签是配置文件路径的短十六进制哈希，扩展名与源配置相同：大多数 harness 使用 .json；Hermes 包含两个 surface，并会同时备份二者，主配置 ~/.hermes/cli-config.json 使用 .json，辅助配置 ~/.hermes/config.yaml 使用 .yaml）。早期版本写入的备份使用旧名称 config-backup-<timestamp>.json，仍可恢复。请在相同的堡垒／存储环境中使用 sanctuary protect --unwrap 恢复。

如果遇到的问题不在此列表中，请运行 sanctuary doctor --json，并将报告提供给操作员；在已封装的 harness 中，sovereignty_audit MCP 工具会评估当前安全态势。

---

深入了解

三类读者，各有三条参考资料。

**操作员路线：**了解使用体验。

• "What Sovereign Actually Means"：通俗易懂的版本。
• "Local ≠ Sovereign"：为什么仅在笔记本电脑上运行还不够。
• sanctuaryprotocol.ai：持续更新的相关文章。

**开发者路线：**了解其工作原理。

• SANCTUARY_ARCHITECTURE.md：架构、数据流、信任模型，以及可作为测试断言的主权属性。
• SHR_SPEC.md：主权健康报告格式。
• federation-v0.1-hard-gate-walkthrough.md：联邦协议 v0.1 设计记录。
• DID_ENCODING.md：Agent DID 编码（符合 base58btc 的 did:key，附带旧版 base64url 迁移说明）。
• security audit：结构化审查材料和修复历史。

**标准／研究路线：**了解如何与其他标准组合。

• Sanctuary Agent Contract（v0.1 规范，W3C AIVS 路线，正在发布）。
• Concordia 组合（回执、协商、约束性承诺；参见 Concordia 仓库）。
• Verascore 组合（可移植的 Agent 声誉；参见 Verascore 仓库）。

---

互操作说明：Agent DID

Sanctuary 使用类似 did:key 的 DID 来标识 Agent，该 DID 根据 Agent 的 Ed25519 公钥生成，并按照 W3C did:key 规范，使用 z multibase 前缀以 base58btc 编码（PR #268）。在迁移到 base58btc 之前创建的历史身份，在本地可能仍使用旧版 base64url 编码；迁移说明、字节布局，以及附带往返验证测试的 JavaScript 和 Python 解码代码片段，请参阅 docs/DID_ENCODING.md。

---

贡献

Sanctuary 以开源方式开发。我们欢迎：

• 实现经验。 基于这些工具构建，并告诉我们哪些有效、哪些无效。
• 威胁建模反馈。 安全审查和差距分析。
• 框架集成。 将 Sanctuary 引入其他运行环境和 Agent 平台。
• 公开问题和讨论。 我们会认真对待反馈。

详情请参阅 CONTRIBUTING.md。

本地开发

首次克隆后，请安装 pre-commit 钩子：

cd server
npm install
npm run install-hooks

install-hooks 会将 .githooks/pre-commit 和 .githooks/pre-push 复制到 git 执行钩子的目录，并赋予它们可执行权限。这两个钩子按照成本划分检查关卡，具体要求见 AGENTS.md（提交规范）：

1. Pre-commit，每次执行 git commit 时运行。 npm run typecheck 必须通过，且 TypeScript 错误数为零；随后，npx vitest related --run 会运行与本次提交中暂存的 server/ 下 .ts/.tsx 文件相关的测试，并执行相同的转换错误／收集错误扫描。它不会检查 .test-baseline；在现代 Mac 上耗时不到一分钟。跳过方式：git commit --no-verify。
2. Pre-push，每次执行 git push 时运行。 必须通过完整的 npm test；vitest 输出不得包含任何转换错误／收集错误；vitest 加载的测试文件数必须等于 server/test/ 下 *.test.ts 文件数；通过的测试数必须不低于仓库根目录 .test-baseline 中的整数。耗时与完整测试套件本身的运行时间相同，视机器而定，约为 8 至 19 分钟。紧急跳过方式：SKIP_TEST_BASELINE=1 SKIP_REASON="why" git push ...（会记录到 .test-baseline-overrides.log 以供审计）。

基线检查关卡用于防范 docs/audit/commit-4ac95830-postmortem.md 中记录的一类故障：解析／转换错误在 vitest 收集测试时静默地丢弃测试文件，导致通过的测试数量看起来偏低，但 vitest 没有报告硬性失败。从外部来看，这种划分意味着：成功执行 git commit 不再表示已检查基线下限；完整核算会在 git push 时进行，或者在跳过或缺少推送时钩子时由 CI 执行。

完整测试套件的检查也会在每个 PR 以及推送到 main 时，通过 .github/workflows/test-baseline-guard.yml 在 CI 中再次运行。请参阅 docs/audit/branch-protection-setup.md，了解用于将 CI 检查设为强制合并关卡的分支保护操作手册。

---

许可证

• 代码： Apache License 2.0
• 规范： CC-BY-4.0

使用它、基于它构建并扩展它。

---

由 Erik Newton 创建。