eriknewton/sanctuary-framework

# Sanctuary [](https://github.com/eriknewton/sanctuary-framework/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@sanctuary-framework/mcp-server) [](LICENSE) **为您的 AI agent 量身打造的防火墙与控制面板。** Sanctuary 封装了您机器上或云端的任何 AI agent。未经您的允许，它执行的每一个操作都会在网络层被拦截，使用仅由您持有的密钥进行签名，并记录在您真正可读的审计追踪中。只需一个仪表盘即可管理您运行的所有 agent 的安全与隐私——无论是在笔记本电脑上运行的单个 agent，还是跨机器的整个 agent 舰队。您的数据以及您的 agent 积累的声誉始终保留在由您掌控的硬件上，并且您可以随时带着它们离开。绝不产生供应商锁定。 已经在使用 Claude Code、Cursor、Hermes、OpenClaw、Cline 或 Mastra 了吗？ ``` npx @sanctuary-framework/mcp-server protect --claude-code ``` 只需一条命令，就能为您正在使用的 agent 构建起防火墙、密钥管理、审计追踪和仪表盘。您保留现有的 harness；Sanctuary 在底层默默提供保护。 **底层原理：** 一道即使在被 prompt 注入的 agent 试图执行违规操作时依然稳固的内核级防火墙（目前支持 Linux，macOS 开发中）；运行您 agent 的平台无法读取的加密身份与加密状态；以及让您永远不会被困在单一供应商处的全面数据可移植性。它可以与 Concordia（agent 协商）和 Verascore（便携式声誉）组合使用，它们各自拥有独立的代码仓库，且均非必选项。 为什么开发此项目：[“主权”到底意味着什么](https://sanctuaryprotocol.ai/2026/03/30/what-sovereign-actually-means.html)。 ## 安装说明 已经在使用 OpenClaw、Hermes、Claude Code、Cursor、Cline 或 Mastra 了吗？一条命令即可将其封装。 ``` npx @sanctuary-framework/mcp-server protect --openclaw ``` 或者，对于任何其他兼容 MCP 的 harness，替换为 `--hermes`、`--claude-code`、`--cursor`、`--cline`、`--mastra` 或 `--wrap `。上述指定的 harness 兼容性在每次发布时都会进行测试；其他兼容 MCP 的 harness 可通过 `--wrap` 标志使用，并随着测试演练的扩展纳入覆盖范围。有关各 harness 的当前状态，请参阅 [Sanctuary 保障矩阵](ASSURANCE_MATRIX.md)。您可以继续使用自己心仪的 harness。Sanctuary 会在底层无形地添加基础设施。 运行 protect 时会发生什么： 1. 生成一个 passphrase 并将其存储在 macOS Keychain 中（在 Linux/Windows 上则存储在加密的备用文件中）。 2. 您现有的 harness 配置将被备份到 `~/.sanctuary/backup/`。 3. 重写配置，使每次工具调用都通过 Sanctuary 路由。 4. Sovereignty Dashboard 在 `http://localhost:3501`（或最高至 3510 的下一个可用端口）启动，并在浏览器中使用一键 auth token 打开。 5. 每次调用都会被记录并进行策略控制。根据保障矩阵，在此之上还会分层应用敏感内容脱敏和查询层匿名（Tier 1 和 Tier 2）。危险操作需要您的批准。 实用标志：`--dry-run` 可预览更改而不实际修改任何内容。`--no-open` 以无头模式运行，适用于 CI。`--unwrap` 还原原始的 harness 配置。 **备份您的 passphrase：** ``` sanctuary export-passphrase ``` 在确认提示后，将 passphrase 打印到 stdout。请将其存储在密码管理器中。如果丢失，将无法恢复加密状态。 ## 发布状态 `main` 是开发分支。当前稳定版本为 npm `latest` 频道上的 **v1.6.1**（发布于 2026-07-01）。v1.6.1 是一个修复版本，它恢复了纯粹的 `npx @sanctuary-framework/mcp-server` 安装方式（自 v1.4.0 起被破坏），使 wrap 操作在 harness 配置中写入固定版本的 MCP 条目，并根据真实的执行证据来控制首次运行时的“已保护”横幅提示；请参阅 [v1.6.1 发布说明](docs/releases/v1.6.1.md)。v1.6.0 将会话式服务台设定为默认的单一仪表盘界面，强化了仪表盘状态显示，使得主权得分和层级卡片反映真实的执行判定结果，而不再仅仅因为配置存在就显示绿色（安全）；此外，还为安装流程和 Hermes wrap 路径添加了诚实的安装时消息，并推出了针对 macOS 的 Castle Wall 启动操作手册。macOS Castle Wall 的界限保持不变：按 uid（per-uid）的允许/拒绝以及重启后存活能力加上广域网（WAN）限制已被证实；但目前还没有针对每个流量规则归属的审计追踪。完整历史记录请参阅 [v1.6.0 发布说明](docs/releases/v1.6.0.md) 和 [CHANGELOG.md](CHANGELOG.md)。 ``` npm install -g @sanctuary-framework/mcp-server ``` 当前功能摘要： | 层面 | 当前状态 | |---|---| | 本地 `sanctuary protect`（别名 `wrap`）、仪表盘、策略门控、加密状态、审计追踪、签名导出包 | 已发布（v1.0 至 v1.3） | | 协作式 MCP 门控：三层审批、四个标准策略槽位、频道模板 | 已发布 | | 上下文门控、敏感字段脱敏、查询层匿名（Tier 1 + Tier 2） | 已发布 | | 便携式身份、状态导出/导入、恢复流程、声誉包 | 已发布 | | 本地多 agent 协调、堡垒本地 hub API、签名审计链 | 已发布 | | Federation Protocol v0.1 基础 | 已发布；根据 Wave 1 设计（2026-05-26），跨运营商联邦强化工作正在进行中 | | Concordia 组合（协商凭证）、Verascore 组合（声誉） | 可选，默认关闭；均已发布 | | Castle Wall（操作系统级出站执行）：Linux | 已发布（第一阶段，2026-05-06） | | Castle Wall macOS：签名的 sysext、主机应用、content-filter provider、零售 UX | 已发布；通过清晰的按 uid 的允许/拒绝演示执行已签名的运营商策略，并在重启后依然有效（N=5，演练于 2026-06-22，单主机/单操作系统版本，经过 Dev-ID 签名和公证）。但这并非经过审计的基于规则和流量的追踪 | | Castle Wall Windows | 已列入路线图 | | 移动端（PWA）运营商伴侣 | 已列入路线图 | | 舰队控制台、运营商云端部署、主权管理的 TEE、后量子迁移 | 已列入路线图 | 信任和安全声明记录在 [Sanctuary 保障矩阵](ASSURANCE_MATRIX.md) 中。面向公众的声明可追溯至该矩阵中的 `proven` 或 `partial` 行；每一行中指定的平台、差距和下一次验证的限制均被保留。 路线图形态：随着 Mac Castle Wall 按用户 ID 的允许/拒绝以及重启后存活能力演示得到证实，目前的重点是针对每个流量规则归属的审计追踪（这仍是真正的差距所在）、Castle Wall Windows 后端以及舰队/运营商云端界面。请参阅 [ROADMAP.md](ROADMAP.md)。 ## 面向代理运营商进行 Sanctuary 安装的 AI 编程 agent 如果您是一个由 LLM 驱动的编程 agent（OpenClaw、Hermes Agent、Claude Code、Cursor、Cline、Mastra、Codex 或任何其他拥有 shell 访问权限的 harness），并且有运营商要求您安装 Sanctuary，请按照本部分的说明操作。人类用户可以直接跳到下方的“安装参考”；您将使用到相同的命令。 **首先向运营商提供摘要。** 在运行任何命令之前，向运营商提供一段话说明： ### 第 1 步：检测运营商的 harness 按顺序运行以下检查。选择第一个匹配的结果。 ``` # OpenClaw command -v openclaw && echo "harness=openclaw" # Hermes Agent command -v hermes && echo "harness=hermes" # Claude Code command -v claude && echo "harness=claude-code" # Cursor（config 存在） test -d "$HOME/Library/Application Support/Cursor" && echo "harness=cursor" # Cline（VS Code extension config） test -d "$HOME/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev" && echo "harness=cline" # Mastra（config 存在） { test -f "$HOME/.mastra/mcp.json" || test -f "$HOME/mastra/mcp.json" || test -f "$HOME/.config/mastra/mcp.json"; } && echo "harness=mastra" ``` 如果有多个匹配项，请询问运营商要封装哪一个。如果都不匹配，说明运营商没有安装受支持的 harness；此时可以提议安装一个，或者使用原始的 MCP server 路径（参见下文第 4 步）。 ### 第 2 步：运行 protect 命令 ``` npx @sanctuary-framework/mcp-server protect -- ``` 将 `` 替换为在第 1 步中检测到的值：`openclaw`、`hermes`、`claude-code`、`cursor`、`cline` 或 `mastra`。对于不在此列表中的任何 harness，请参见第 4 步。 等待命令执行完毕（通常需要 20-40 秒）。预期输出的结尾将是类似这样的一行： ``` Sovereignty Dashboard ready: http://localhost:3501 ``` 请记下该端口（如果 3501 被占用，可能是 3501-3510 之间的一个）。 ### 第 3 步：验证安装 在第 2 步（protect 成功）之后，仪表盘将开始运行。请验证安装： ``` # (a) Dashboard 响应 curl -fsS "http://localhost:3501/api/health" | grep -q '"status":"ok"' && echo "dashboard=ok" # (b) Passphrase 已备份到 keychain (macOS) security find-generic-password -s "sanctuary-passphrase" >/dev/null 2>&1 && echo "passphrase=ok" ``` 当您首次在浏览器中打开 Sovereignty Dashboard 时，Sanctuary 会从存储在 keychain 中的 passphrase 派生出您的主密钥，创建您堡垒的 Ed25519 身份，并写入审计日志的创世区块。protect 命令将这些内容配置在磁盘上；首次解锁仪表盘时将初始化它们。请在首次解锁后进行验证： ``` # (c) Identities 已加载（在打开 dashboard 一次后运行） curl -fsS "http://localhost:3501/api/identities" | grep -q '"identities":\[' && echo "identities=ok" # (d) Audit log 已初始化（在打开 dashboard 一次后运行） test -d ~/.sanctuary/state/_audit && echo "audit=ok" ``` 如果任何检查失败，请参阅本 README 底部附近的“故障排除”。 ### 第 4 步：构建运营商的首个受控 harness（推荐） 在 protect 成功后，询问运营商：“您希望在此 harness 上使用哪种频道形态？我提供针对 research-assistant、coding-assistant、ops-runner、planner 和 handoff-coordinator 的一键原型。或者我也可以跳过这一步。” 如果他们选择了一个原型，请运行： ``` curl -X POST "http://localhost:3501/api/templates//init" \ -H "Content-Type: application/json" \ -d '{ "agent_name": "", "model_provider": "" }' ``` 将 `` 替换为运营商选择的原型（`research-assistant`、`coding-assistant` 等）。`agent_name` 必须与已经封装好的 harness 相匹配；`template init` 会拒绝未绑定到已封装 harness 的孤立 `agent_id`（这是将 Sanctuary 锁定到运营商机器上的安装时检查机制），并提示运营商使用 `sanctuary protect`。确认响应中包含 `signed_policy_event_id` 和 `attestation_panel_url`。在运营商的浏览器中打开该 URL。 ### 第 5 步：交回给运营商 告诉他们：“Sanctuary 已安装完毕，您的第一个子 agent 也已构建完成。请在 http://localhost:3501 打开 Sovereignty Dashboard，以实时查看您的 agent 正在做什么。您的 passphrase 存储在您的 macOS Keychain 中；如果您需要可打印的备份，请运行 `sanctuary export-passphrase`。” ### 原始 MCP server 路径（第 4 步替代方案） 如果运营商的 harness 不在受支持的列表中，请直接安装 MCP server，并让他们在其 harness 中指向它： ``` npm install -g @sanctuary-framework/mcp-server ``` 然后将 Sanctuary 添加到 harness 的 MCP 配置中。具体格式取决于 harness；对于兼容 MCP 的 harness，其条目通常如下所示： ``` { "command": "npx", "args": ["-y", "@sanctuary-framework/mcp-server"], "env": { "SANCTUARY_PASSPHRASE": "" } } ``` 使用 `openssl rand -base64 32` 生成 passphrase，并将其存储在运营商的 keychain 或密码管理器中。 ## 安装参考 **环境要求：** Node.js >= 22.0.0，npm >= 10.0.0。 标准的安装路径是 `sanctuary protect`（如上文所述）。以下部分是针对不常见情况的参考。 ### 持久化安装 ``` npm install -g @sanctuary-framework/mcp-server ``` 使 `sanctuary` CLI 可以直接使用，无需加 `npx` 前缀。 ### 手动配置 MCP 如果您更愿意手动编辑您的 harness MCP 配置： ``` # OpenClaw openclaw mcp set sanctuary '{"command":"npx","args":["-y","@sanctuary-framework/mcp-server"],"env":{"SANCTUARY_PASSPHRASE":"your-passphrase-here"}}' # Hermes Agent hermes mcp set sanctuary '{"command":"npx","args":["-y","@sanctuary-framework/mcp-server"],"env":{"SANCTUARY_PASSPHRASE":"your-passphrase-here"}}' # Claude Code claude mcp add sanctuary -- npx -y @sanctuary-framework/mcp-server ``` 在首次启动前生成一个 passphrase： ``` openssl rand -base64 32 ``` 请妥善保管。它用于派生所有持久状态的加密密钥。如果丢失，加密状态将无法恢复。 ### 健康检查 ``` sovereignty_audit ``` 该功能会根据您当前的实时配置和环境，在安全性、隔离性和隐私性方面对您的设置进行 0-100 的评分。默认关闭的可选功能（上下文门控、零知识证明）只有在您启用后才会计入分数，而最高的“完全”评级专为那些真正开启了可选层级的安全姿态保留。因此，全新的安装评分会低于满分，评级文字也达不到“完全”级别，报告还会标出差距并提供填补这些差距的步骤。该功能既可以作为 CLI 命令使用，也可以作为任何已封装 harness 内部的 MCP 工具使用。 ## 安装后的首个 agent：生成模板 运行 `protect` 后，仪表盘会提供一个一键模板选择器。在 Agents 视图中点击“Add agent”，选择一个模板，填写名称和模型提供商，然后点击 Scaffold（生成）。该模板会为允许出站的主机、预算、保留时间窗口和策略门控等配置提供合理的默认值。 Sanctuary 内置的频道形态原型： | 原型 | 频道形态 | 读取来源 | 推荐模型 | |------|---|---| | **research-assistant** | 通用研究助手 | 可配置 | 任意 | | **coding-assistant** | 读取您的代码库，提出修改建议 | 本地 + git 远程仓库 | 任意 | | **ops-runner** | 经批准后运行运维脚本 | 按 agent 划分作用域 | 任意 | | **planner** | 生成计划而不执行计划 | 无 | 任意 | | **handoff-coordinator** | 协调多个 agent 之间的工作 | 仅限 agent 之间 | 任意 | Sanctuary 提供的是频道形态治理模板（策略、出站、预算、保留策略），而不是特定名称的 agent 运行时。运营商自带 harness 并对其进行封装；`template init` 负责将频道形态绑定到已经封装好的 harness 上。 如果运营商想要在此列表之外自行编写：只需复制 `~/.sanctuary/templates/` 下的任意模板目录，编辑 `template.json`、`defaults.json`、`policy.md`、`commitments.json` 和 `onboarding.md`，然后运行 `sanctuary template init `。 CLI 搭建的工作方式与仪表盘按钮完全相同： ``` sanctuary template init research-assistant --name my-agent --provider anthropic ``` ## 部署模式 Sanctuary 旨在在三个位置运行相同的权限基础设施。本地模式目前已经开始提供；运营商云端和主权管理的 TEE 模式属于路线图中的内容，它们建立在此基础上相同的联邦和策略之上。 | 模式 | 状态 | 说明 | 适用对象 | |---|---|---|---| | **在您的机器上**（本地） | 已发布 | 运行在您已经拥有的 Mac、Linux 机器或 Windows 机器上。除非您主动指示，否则数据绝对不会离开您的设备。 | 自托管者、极度重视隐私的用户、任何已经拥有家庭实验室的人。 | | **在您的云端**（运营商云） | 已列入路线图 | 在您自己的 GCP / Azure / AWS 账户中运行，采用运营商批准的限定节点托管模式。在通过硬件认证验证主权 TEE 模式之前，云提供商仍处于节点运行时的信任边界之内。 | 高级消费者、小型企业、拥有轻量级 IT 团队但家中没有服务器的运营商。 | | **在我们管理的密封云盒中**（主权管理 TEE） | 已列入路线图（v2） | 运行在由 Sanctuary 运营的硬件上，但该硬件会向您的控制台证明，连 Sanctuary 也无法看到内部情况。密钥由您掌握；硬件由我们维护。 | 受监管的行业、希望获得主权而又不想承担运营负担的运营商。 | 在任何模式下，运营商始终是托管的根本主体。普通的运营商云模式并不会将云提供商置于运行时的信任边界之外；主权管理模式在未通过硬件认证（hardware attestation）之前，不会被视为已发布状态。 ## Castle 架构 Sanctuary 安装的主权底座是伴随其诞生的。在架构上，它由五个命名的机制组成。 **Castle Wall：边界防线。** 外部世界未经您同意无法跨越的屏障。这是位于运营商与外部边界处的操作系统级出站执行控制。由内核本身来拦截未经授权的跨边界调用。即使是遭到 prompt 注入的 agent 也无法绕过。Linux 后端已发布（第一阶段，2026-05-06）。macOS 后端（已签名的系统扩展 + content-filter provider）已经拥有经过证实的按 uid 允许/拒绝出站执行演示，该演示是在真实主机上录制的（演练于 2026-06-11）：拦截了 agent 对未列入白名单地址的出站请求，允许了白名单内的出站请求，且对运营商的出站请求没有影响。这只是在单台主机和单一操作系统版本上进行的演示，并非重启后仍能存活，也不是经过审计的细粒度规则与流量追踪。Windows 版本已列入路线图。 **Sentinels：神经感知。** 将发生的情况呈现到您的感知中。通过进程内省和行为基线化实现内部观察。异常情况会通过菜单栏或通知显示出来。这是观察手段，而非执行手段。 **Charter：自主意志。** 您训练 agent 使其自愿做出的选择。为顺从的 agent 提供的附加协作式 MCP 界面。运营商根源的加密身份（Ed25519 签名、Argon2id 密码短语解锁、特定于用途的 HKDF 子密钥）。针对每个 agent 的静态加密状态（AES-256-GCM）。具有频道模板绑定功能的三级主体策略门控（Principal Policy gates）。带有回滚检测的签名审计链。 **Heralds：对外发声。** 您如何与其他主权者交流并被识别。可选的组合界面（用于结构化协商的 Concordia，用于便携式声誉的 Verascore）。凭证和声誉证明汇聚成一条单一的审计追踪，随着 agent 跨越不同机器移动。默认关闭；两者皆为可选项。 **Mantle：底层唯一绑定。** 使此安装属于您而不是其他人的机制。安装时的检查机制会将 Sanctuary 锁定在运营商的机器上，并拒绝未绑定到已封装 harness 的孤立 agent 标识符。 **当前状态：** 采用 Ed25519 签名、Argon2id 密码短语解锁和特定于用途的 HKDF 子密钥。**密码敏捷性：** 每一个审计条目都嵌入了一个方案标识符，因此混合式后量子签名（Ed25519 + ML-DSA / FIPS 204）的引入不会破坏历史凭证。基于硬件的安全元件已列入路线图。 **正在参与代码开发？** TypeScript 服务器在 [`server/src/README.md`](server/src/README.md) 中有一份导读图——这是一个包含 56 个模块的索引，说明了每个模块的职责、容易混淆的名称区分，以及重构时绝对不能更改的冻结接口。请从这里开始阅读，然后参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md)。 ## 您默认拥有的权利 这套底座所执行的权利，过去通常只配备给那些拥有专门的身份和安全团队的大型企业。它们对您的意义在于： - **身份。** 您的 agent 拥有由您掌握的密钥。没有任何提供商可以冒充您或撤销您的 agent。您无需任何人的许可即可证明该 agent 属于您。 - **数据。** 您 agent 的状态是针对运行它的提供商进行加密的。平台能看到发出的调用；但它看不到您输入的生活点滴。您的对话、您的记忆以及您的计划始终属于您自己。 - **可移植性。** 您 agent 的记忆、声誉和承诺都与您如影随形。如果提供商作恶、涨价或倒闭，您可以离开，而不会失去您构建的一切。 - **证明。** 您的 agent 所做的事情都是可证明的。对您、对第三方、甚至对法庭（如果走到那一步）。审计日志是经过签名的、只可追加的、且是可移植的。 - **退出。** 您所积累的一切都不会被锁定在一个可以任意撤销它们的平台上。密钥、状态、声誉和承诺都归您所有，任由您移动、复制或离线保存。 Sanctuary 提供的是底层的权利基础设施。访问权（算力、设备、带宽、文化素养）属于公民基础设施合作伙伴（公共图书馆、法律援助组织、工会、公共利益科技团体、社区大学），他们代表那些不自行托管的用户来托管代理式 AI。合作伙伴提供访问途径；Sanctuary 赋予权利。两者相辅相成，互不替代。 ## 兼容性 Sanctuary 封装兼容 MCP 的 harness。以下指定的 harness 在每次发布时都会进行兼容性测试；其他兼容 MCP 的 harness 可通过 `--wrap` 标志或直接的 MCP 配置使用，并随着测试演练扩展 [保障矩阵](ASSURANCE_MATRIX.md) 而获得经过发布测试的覆盖范围。 - **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`) - **LangGraph** 和自定义 harness (`sanctuary protect --wrap `) - 通过直接的 MCP 配置连接的任何其他兼容 MCP 的 harness ## 与 Concordia Protocol 组合 当您的 agent 需要进行协商或达成交易时，**Concordia Protocol** 会添加具有约束力的结构化协商。Sanctuary 还可以与 **Verascore** 组合，实现便携式的 agent 声誉。 **Sanctuary 绝不要求必须安装 Concordia，Concordia 也绝不要求必须安装 Sanctuary。** 当两者都部署时，它们能发挥强大的组合效应：Concordia 的承诺凭证会通过 Sanctuary 的封装传递，而声誉证明则汇聚成一条单一的审计追踪。各自都可以独立发布、运行并取得成功。这是结构设计上的承诺，绝非一句口号。这两个代码库互不依赖。 如果您需要完整的全栈体验，请同时安装两者： ``` npx @sanctuary-framework/mcp-server pip install concordia-protocol ``` ## 开放标准 Sanctuary 可以与现有的开放生态系统组合使用。 - **身份：** W3C DIDs、KERI、可验证凭证。 - **执行：** 可信执行环境（Intel TDX、AMD SEV-SNP、ARM CCA）已列入 v2 路线图。 - **密码学：** 目前采用 Ed25519；NIST 后量子密码标准（ML-DSA / FIPS 204，ML-KEM / FIPS 203）已在迁移路径上；计划在完成本地主权 harness 之后引入混合签名。 - **结算：** x402 (Coinbase 小额支付)、AP2 (Google Agent Payments Protocol)、ACP。 ## 故障排除 对于处理安装失败的 AI 编程 agent，以下是常见情况。 **安装第 3 步 中的 "dashboard=ok" 检查失败：** - 请等待 10 秒钟后重试。仪表盘在首次启动时需要一点时间来绑定端口。 - 如果仍然失败，请检查 `lsof -i :3501-3510` 以确认仪表盘是否选择了端口。protect 输出中的 `Sovereignty Dashboard ready: http://localhost:` 这一行是权威的；请使用那个端口。 **在 macOS 上，安装第 3 步 中的 "passphrase=ok" 检查失败：** - protect 命令可能写入 Keychain 失败了（通常是因为运营商取消了权限提示）。请重新运行 protect 命令，并在出现提示时批准 Keychain 的访问请求。 **在 Linux 或 Windows 上，安装第 3 步：** - keychain 检查是 macOS 特有的。在 Linux 上，Sanctuary 会尽可能使用 Secret Service，如果不可用则回退到位于 `~/.sanctuary/passphrase.enc` 的加密文件。Windows Credential Manager 支持已列入 v1.0.x 补丁计划。请使用 `test -f ~/.sanctuary/passphrase.enc && echo "passphrase=ok"` 来测试回退机制是否生效。 **安装第 3 步 中的 "identities=ok" 检查失败：** - 确认 protect 过程无误地完成。如果是，请检查 `~/.sanctuary/identities/` 目录下是否有 `.enc` 文件。如果没有，说明 protect 命令提前退出了；请加上 `--dry-run` 重新运行以查看它将要执行的操作，然后去掉 `--dry-run` 再次尝试。 **安装第 3 步 中的 "audit=ok" 检查失败：** - 确认 `~/.sanctuary/` 存在且当前用户对其有写权限。如果不存在，说明 protect 未完成；请重新运行。 - 审计条目经过加密后存储在 `~/.sanctuary/state/_audit/` 下，而不是以纯文本 JSONL 形式存储。当您需要解密导出时，请使用 `audit_export_siem`。 **在执行 `npm install -g` 后找不到 `sanctuary` CLI：** - 确认 `npm bin -g` 的路径已包含在 PATH 中。在 macOS 上使用 nvm 时，它通常位于 `~/.nvm/versions/node//bin/`。 **现有的 harness 配置被覆盖：** - 原始配置位于 `~/.sanctuary/backup/config-backup--`（其中 surface 标签是配置文件路径的简短十六进制哈希，扩展名与源配置相匹配：大多数 harness 为 `.json`；Hermes 封装了两个层面并都进行了备份，主文件 `~/.hermes/cli-config.json` 为 `.json`，辅助文件 `~/.hermes/config.yaml` 为 `.yaml`）。早期版本编写的备份使用旧的 `config-backup-.json` 命名方式，但仍然可以恢复。请从相同的堡垒/存储上下文中运行 `sanctuary protect --unwrap` 进行恢复。 对于本列表中未提及的问题，请运行 `sovereignty_audit` 并将报告呈现给运营商。 ## 深入探索 面向三类受众，提供三个指引。 **运营商方向：** 使用起来到底是什么感觉。 - [“主权”到底意味着什么](https://sanctuaryprotocol.ai/2026/03/30/what-sovereign-actually-means.html)：通俗易懂的英文解释。 - [本地 ≠ 主权](https://sanctuaryprotocol.ai/2026/03/30/local-not-sovereign.html)：为什么仅仅在您的笔记本上运行是远远不够的。 - [sanctuaryprotocol.ai](https://sanctuaryprotocol.ai)：以相同口吻持续发布的文章。 **开发者方向：** 它是如何运作的。 - [CLAUDE.md](CLAUDE.md)：完整的架构、安全不变量和威胁模型。 - [SHR_SPEC.md](docs/SHR_SPEC.md)：主权健康报告格式。 - [federation-v0.1-hard-gate-walkthrough.md](server/docs/federation-v0.1-hard-gate-walkthrough.md)：federation 协议 v0.1 设计记录。 - [DID_ENCODING.md](docs/DID_ENCODING.md)：agent DID 编码（兼容 base58btc 的 `did:key`，附带旧版 base64url 迁移说明）。 - [安全审计](docs/audit/)：结构化的审查产物与修复历史。 **标准 / 研究方向：** 它在哪里发挥组合效应。 - Sanctuary Agent 合约（v0.1 规范，W3C AIVS 路线，已发布）。 - Concordia 组合（凭证、协商、约束性承诺；详见 Concordia 代码库）。 - Verascore 组合（便携式 agent 声誉；详见 Verascore 代码库）。 ## 互操作性说明：agent DID Sanctuary 使用一种 `did:key` 风格的 DID 来标识 agent，该 DID 源自 agent 的 Ed25519 公钥，根据 W3C `did:key` 规范（PR #268）将其编码为带有 `z` multibase 前缀的 **base58btc** 格式。在 base58btc 迁移之前创建的历史身份在本地可能仍然使用旧版的 base64url 编码；有关迁移说明、字节布局以及包含往返验证测试的 JavaScript 和 Python 解码器代码片段，请参阅 [`docs/DID_ENCODING.md`](docs/DID_ENCODING.md)。 ## 贡献指南 Sanctuary 是在开源环境下开发的。我们欢迎： - **实施经验。** 基于这些工具进行构建，并告诉我们哪些可行，哪些不可行。 - **威胁建模反馈。** 安全审查和差距分析。 - **框架集成。** 将 Sanctuary 引入其他的 harness 和 agent 平台。 - **开放的问题和讨论。** 我们非常重视您的反馈。 详情请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ### 本地开发 首次克隆仓库时，请安装 pre-commit 钩子： ``` cd server npm install npm run install-hooks ``` `install-hooks` 会将 `.githooks/pre-commit` 复制到 `.git/hooks/pre-commit` 并赋予其可执行权限。该钩子会在每次执行 `git commit` 时运行两道检查关卡： 1. **类型检查。** `npm run typecheck` 必须通过，且保证零 TypeScript 错误。 2. **测试基线守卫。** `npm test` 必须通过；vitest 输出中不得包含任何 transform/collection 错误；vitest 加载的测试文件数量必须等于 `server/test/` 下的 `*.test.ts` 文件数量；通过的测试数量必须至少达到根目录下 `.test-baseline` 文件中的整数值。 第二道关卡旨在防范 [`docs/audit/commit-4ac95830-postmortem.md`](docs/audit/commit-4ac95830-postmortem.md) 中记录的一类失败情况：即在 vitest 进行收集期间，解析/转换错误悄无声息地丢弃了测试文件，导致通过的测试用例数量看起来变少，而 vitest 却并未报告严重的失败。 钩子总运行时间：在现代 Mac 上约为 21 秒。紧急绕过方式：`SKIP_TEST_BASELINE=1 git commit ...`（该操作将被记录到 `.test-baseline-overrides.log` 中以便审计）。 相同的两道关卡也会在 CI 中通过 [`.github/workflows/test-baseline-guard.yml`](.github/workflows/test-baseline-guard.yml) 在每个 PR 和向 main 分支的每次推送时运行。有关使该 CI 检查成为强制合并门控的分支保护操作手册，请参阅 [`docs/audit/branch-protection-setup.md`](docs/audit/branch-protection-setup.md)。 ## 许可证 - **代码：** Apache License 2.0 - **规范：** CC-BY-4.0 尽可使用它，在它之上进行构建，扩展它。 **由 Erik Newton 创建。**

标签：AI安全, Chat Copilot, MITM代理, Streamlit, 人工智能, 审计日志, 暗色界面, 用户模式Hook绕过, 网络防火墙, 自动化攻击, 访问控制