SYNAPSE CHANNEL

面向 AI Agent 集群的本地优先协作总线。
一个 WebSocket Hub 是状态、文件范围声明、共享计划、任务状态和能力的共享事实来源，服务于在同一仓库或整个生态系统中协作的 Agent。

旗舰示例：通过声明文件范围来协调并行工作的 AI 编码 Agent — Hub 会拒绝第二个重叠的有效声明，而已覆盖的提供方钩子和暂存的 Git 门禁则仅强制执行其文档所述的变更边界。

English · 简体中文 · Español · Português (Brasil) · 日本語 · 한국어 · Deutsch · Français · Slovenčina

一个本地优先的协调总线，供多个 AI Agent 并行协作——无论是在单个代码库中，还是分布于整个生态系统。一个 WebSocket 中枢是在线状态、工作认领、聊天、任务状态和资源提供的共享事实来源：Agent 可以跨项目相互联系并共享同一计划，而文件范围认领可防止同一代码库中的 Agent 获得重叠的实时权限。文档说明的提供方钩子和暂存 Git 门禁，仅在其覆盖的变更操作范围内强制执行这些权限。

观看演示

在 YouTube 上观看 SYNAPSE CHANNEL 演示（8 分钟；从头开始播放）。

初次了解？ 阅读为什么选择 SYNAPSE CHANNEL——一篇五分钟的文章，介绍它是什么、可以基于它构建什么、它与相关工具有何不同，以及为什么运行多个 Agent 后协调会成为瓶颈。

项目沿革： SYNAPSE CHANNEL 始于 2025 年 9 月。

该总线对传输层的依赖很少（websockets，以及 Python 3.10 上的 typing-extensions），设计上以中枢为核心 （由一个位置统一管理在线状态、租约和历史记录），并完全在本地机器上运行。模型工作进程可通过任何兼容 OpenAI 的端点在频道中回复，包括本地 Ollama 服务；离线时则使用确定性的基于规则的回退方案。

内置的 synapse mcp 服务使用 Model Context Protocol (MCP)，将发送、持久收件箱、状态、认领、释放、 交接和任务等操作作为 MCP 工具公开，并将看板、Agent 和资源作为只读 MCP 资源公开。主机互操作性取决于已安装的主机版本、传输方式和配置；请参阅集成目录中的具体支持范围。A2A HTTP 接口有单独说明的部分认证资格。基础运行时使用 websockets，并在 Python 3.10 上使用 typing-extensions；适配器使用各自声明的可选扩展（pip install 'synapse-channel[mcp]'）。请参阅 MCP 指南和另行认证的经过身份验证的 HTTP 配置。

限定范围的执行结果会区分 A2A/MCP 交互、唤醒传输和工作进程退出与外部业务效果。结果未知时，需要进一步查询或由操作员恢复；重新连接不会自动重复工作。

python -m pip install synapse-channel && synapse demo

获取 Python 软件包  ·  运行最初的 60 秒  ·  阅读快速入门

## 分组与项目图谱

SYNAPSE CHANNEL 是 Agentic Coordination, Assurance and Continuity Systems 组织的协调层：该组织包含一系列独立项目，用于让 AI Agent 作为负责任的工程参与者开展工作。总线是 Agent 汇聚之处，而此仓库则保存该组织的权威图谱。

图谱组成部分	仓库与用途
协调	SYNAPSE-CHANNEL、SYNAPSE-CHANNEL-FLEET 和 SYNAPSE-POLICY-CHECK-ACTION：协调总线、多机运行，以及在 CI 中执行的发布策略检查。
保证	DIRECTOR-AI、DIRECTOR-CLASS-AI、DIRECTOR-AI-CLOUD 和 RIGOR-FOUNDRY：基于事实的回答、操作控制、托管控制平面，以及基于证据的仓库审计。
持续性	REMANENTIA 和 REMANENTIA-PORTAL：可跨会话保留的记忆，以及客户身份与权限。
支持工具	HushLine：命令输出过滤。新兴工具尚未设计。

每个项目都有自己的开发、版本管理和发布生命周期；使用任何一个项目都不需要整个组织。组织与项目图谱列出了每个仓库的功能和当前状态，并解释示意图中各条线的含义。

完整尺寸 SVG · PNG · JPG

协调。观察。治理。

Synapse 每日的承诺体现在三个明确的循环中：

• 协调已声明的工作并揭示冲突：synapse git-init、synapse git-claim、 synapse git-claim-check --staged、synapse task 和 syn ack 将工作 范围、依赖项和证据转化为共享状态，而不是旁路记录。
• 观察基于持久状态的集群：synapse who、synapse state、 synapse dashboard、synapse event-query 以及观测到的对等节点行，显示哪些节点 在线、认领了什么、发生了哪些变化，以及哪些对等节点中心事实仅供参考。
• 治理有证据支撑的高风险操作：策略检查、审批、发布凭证、Merkle 根、ACL 界面、联邦 和加密密钥命令，让操作员决策可审计。治理界面默认只报告结果； 由操作员决定哪些事项会阻止合并、发布或跨中心操作。
• 使用可选的 SQLCipher 页面加密来保护静态持久日志， 加密实时中心事件存储（此外，还使用整文件 AES-GCM 封装 relay 日志、A2A 状态、游标和归档）。请参阅下文的 SQLCipher 实时事件存储。

各个界面提供的功能

目前已发布的七种协作界面，每种都以当前提供该功能的命令或文档命名：

• 编辑前先认领。 synapse git-init 安装可识别认领状态的 Git 钩子；synapse git-claim 会记录准确的工作树、分支和路径范围，从而在文件发生分歧之前拒绝重叠的认领。

  

• 阻止未认领的原生文件编辑。 Provider 文件编辑认领钩子 将 Claude Code Edit|Write、Codex apply_patch、Gemini CLI replace|write_file 和 Kimi Edit|Write 接入同一个实时认领决策引擎。

  

• 共享计划。 synapse task 和 synapse board 将任务状态、依赖关系和就绪工作保留在中枢，而不是分散在各个 Agent 的笔记中。

  

• 交接工作，不留所有权空档。 原子交接 会将持有的任务、范围、状态和检查点转交给在线接收方，不会出现先释放再重新认领的间隙。

  

• 发现失联席位。 在所有者准确的等待器连续 30 秒未响应后，中枢会针对受影响的认领或已分配工作发出一条 dark_seat_alert，其中包含永久启用 arm 的补救方法；它不会自动释放或重新分配工作。

  

• 通过一个驾驶舱查看整个 Agent 群组。 synapse dashboard 提供本地指挥中心、显示准确状态的任务列、认领、冲突、安全态势和可选的持久化事件流；只读 Studio 投影不会增加任何新的中枢权限。

  

• 在边缘接入现有 Agent 协议。 synapse mcp 通过 stdio 提供协作工具和只读资源；A2A 桥接器 提供本地 Agent Card 和 HTTP+JSON 接口，同时明确说明其部分验证边界。

  

概览

graph LR
    A1["Agent"] --> H
    A2["Agent"] --> H
    A3["Worker"] --> H
    SUP["Supervisor"] --> H
    H["SynapseHub<br/>single source of truth"] --> CL["Claims & leases<br/>scope · epoch · checkpoint"]
    H --> BB["Blackboard<br/>plan + progress"]
    H --> CAP["Capabilities<br/>cards + routing"]
    H --> LOG["Event log (SQLite WAL)<br/>durable · optional SQLCipher at rest"]

认领会为已声明的工作单元租用一个文件范围，因此，对于由其他所有者持有的相互冲突的已声明范围，中枢会予以拒绝。Provider 钩子和暂存区 Git 门禁会在其文档规定的界面上执行该权限；它们不会对所有文件系统或外部副作用进行沙箱隔离。计划、交接、检查点和停滞监督器会推动工作持续进行。配置日志后，重启会根据经过验证且保留的记录恢复尚未过期的租约；过期、保留策略和完整性隔离机制会限制可恢复的内容。

核心层与可选层

SYNAPSE CHANNEL 以一个可安装的软件包形式发布，但其公共功能按层划分，以保持精简的总线清晰易懂：

层级	分类层级	包含内容
本地协调核心	stable	用于日常协调的 hub、send/wait/listen/arm、声明、任务、锁、状态、看板、init 和 fleet bootstrap 命令。
边缘适配器	adapter	将现有工具连接到总线的 MCP、A2A、git hooks、tmux/provider 桥接、shell hooks、数据摄取和工作者席位。
操作员分析	analysis	Doctor、state、dashboard、causality、multihub、reliability、trust graph、directory、accounting、fleet scorecard export、manifests 和 event queries。这些是侧重检查的分组；显式控制可能会更改状态或配置、持久化记录或导出内容。请查看各动词的影响和权限。
治理与完整性	governance	策略检查、审批、ACL/角色功能、联邦、Merkle 根、发布回执、复现、压缩、加密密钥 / SQLCipher 密钥操作。
实验功能	experimental	基准测试、参与者结构、route-task、沙盒、工作流、TTL 建议、记忆召回、自动操作和资源竞价。

权威映射位于 synapse_channel.surface_taxonomy， 生成的操作员视图见公共功能与稳定性。 适配器和实验功能可通过同一个软件包安装和使用，但基础依赖仍为 Python 3.10 上的 websockets 加 typing-extensions。层级或配置文件标签不授予权限，也不保证行为为只读。

六种可衡量的发现配置文件让这些层级清晰明确，同时不会隐藏或移除命令：first-use、core、adapters、governance、labs 和 all。无需启动 hub 或可选进程，即可检查任意配置文件：

synapse commands --profile first-use
synapse commands --profile first-use --json

JSON 契约记录三个首次使用概念和三个 shell 命令，概念数严格限制为八个，同时可选额外项为零、隐式启动的持久化服务为零。配置文件检查为只读；可选功能仅通过对应文档说明的软件包 extra 和命令或标志启用，并可通过停止对应进程或省略启用选项来停用。请参阅安装配置文件。

可选的参与者记忆召回

participant ask、participant exchange 和 participant convene 可以为其席位封装有界的只读召回功能，该功能通过 REMANENTIA 的轻量级 HTTP API 实现。除非指定 --memory-url，否则召回功能处于禁用状态；不会隐式启动记忆进程。令牌只能通过 --memory-token-file 提供，召回的片段会在纯数据围栏中进入 TurnRequest.context，而操作员提示词保持不变。

synapse participant ask claude "review this design" \
  --memory-url http://127.0.0.1:8001 \
  --memory-token-file /run/secrets/remanentia

当前 HTTP 结果不包含 REMANENTIA 的诚实性维度，因此每条召回结果都会标示为边界数据；相似度是相关性证据，而非真实性证据。无结果和不可用状态仍会显示，但不会导致提供方回合失败。有关设置、限制、CLI 标志、库用法和审计边界，请参阅参与者记忆召回。

即将推出：Studio —— dashboard 正在发展为面向操作员的 Studio： 一个控制平面，可一目了然地回答当前发生了什么、有哪些风险，以及接下来可以安全地做什么。仪表盘设计系统、/studio 参考页面、实时 /studio/command shell、安全态势面板和事件日志 LiveFeed 已发布。默认本地优先且只读——组织级工作台计划作为独立层推出。

安装

python -m pip install synapse-channel       # the release from PyPI
python -m pip install -e ".[dev]"           # or an editable dev checkout
# optional: live hub event-store page encryption (SQLCipher)
python -m pip install 'synapse-channel[sqlcipher]'
# optional: whole-file AES-GCM envelope helpers (encrypt-key profile/migrate/rekey)
python -m pip install 'synapse-channel[encryption]'

对于可编辑的检出版本，请让本地 .venv 与仓库声明的 dev、docs 和 benchmark extras 保持一致：

.venv/bin/python tools/check_dev_dependency_drift.py --check
.venv/bin/python tools/audit_dependency_tooling.py --check

第二项检查为离线检查。它会验证本地预检仍涵盖预期的工具门禁、GitHub Actions 是否固定到完整提交 SHA、Dependabot 是否涵盖 actions/Python/Docker，以及 PyPI 发布/下载元数据入口是否仍已接通。

这会安装 synapse 命令。若要将 hub 作为始终运行的本地服务或容器运行，请参阅部署指南（其中同时包含 systemd 用户单元和 docker compose）。在 Linux 上，只需安装一个永久的精确身份等待器： synapse arm install --identity myproject/agent --start；它使用邮箱重放和 Restart=always，无需安装 hub。它的 myproject/agent-rx 接收器可与 agent-tmux 独有的 myproject/agent-pane-rx 桥接器共存，在避免名称抢占的同时，保留持久的间隙恢复和活跃窗格投递。窗格桥接器遇到繁忙、模态、未知或有歧义的提供方界面时会安全失败：它会持久化待处理唤醒，并且只有在通过两次提供方专属的空闲输入框探测后才提交固定提示词。 它仅在窗格显示提示词已被接收后确认投递；如果提供方异步启动期间忽略了 Enter，唯一暂存的提示词会保持待处理状态，以便安全地仅重试 Enter。 它只接受精确的身份、角色或群组目标；全局优先级和 CEO 广播仍会作为持久的收件箱流量保留，但绝不会注入提供方窗格。

若要在无人值守时进行活跃投递，请独立于 Agent 回合监督该窗格桥接器：

synapse waker install \
  --identity myproject/agent \
  --session myproject-agent \
  --cwd "$PWD" \
  --agent-command codex \
  --start
synapse waker status --identity myproject/agent

生成的 [email protected] 配置了 Restart=always 和主循环看门狗，因此即使 Agent 忘记重新启用它，桥接器死亡后也会自动重建。waker stop --reason ... 会先持久化 inhibited 状态，再停止且仅停止精确的桥接器；systemd 无法立即将其复活，而且 tmux 提供方终端不会被终止或重启。只有显式执行 waker resume 才会清除该抑制状态。 此处不声称支持原生 Windows 服务配置；请按部署指南所述使用带 systemd 的 WSL。

若要借助 Agent 准备环境，synapse setup spec、inspect、plan、authorize、apply、verification-plan、authorize-verification 和 verify 会提供打包的 synapse-setup.v1 合约。前三项分别描述需求、检查主机，并将不含凭据的目标绑定到不可执行的 SHA-256 计划。authorize 会为一项经过审核的计划生成短期有效的信封。重启授权必须与该计划中观察到的确切 hub PID 匹配；首次启动授权不包含 PID。在使用 systemd-user 的 Linux 上，apply 会重新检查目标和与计划绑定的可执行文件版本，在私有重放账本中以原子方式预留授权，并且只会安装或启动由软件包管理的本地 hub 和精确等待器单元。它会保留已声明的 PID、生成绑定摘要的收据，并在失败时恢复先前的单元和服务状态。成功应用后，独立的验证事务会发送一个定向 canary、要求精确等待器提供持久 ACK、仅重启获授权的 hub PID、通过新的 hub PID 证明重放、重新检查绑定版本，并保留已声明的终端/提供方 PID。它会生成一份单次使用、绑定摘要的验证收据；仅有应用收据并不能作为严格的端到端就绪证据。软件包、Python、身份、密钥、远程、macOS、原生 Windows 和容器更改仍会被阻止。有关架构、过期时间、nonce 消耗和精确 PID 授权规则，请参阅机器可读设置。

CLI 附带两项可选的 Shell 便利功能：synapse completions bash|zsh|fish 会为顶层命令、一级嵌套命令及其长选项输出静态补全（根据已安装版本的解析器生成；升级后请重新生成）；synapse install-shell-hook 会添加受保护的代码块，在每个新终端中自动启用唤醒监听器：

synapse completions bash > ~/.local/share/bash-completion/completions/synapse
synapse install-shell-hook          # auto-arm Bash, Zsh, and Fish terminals

适用对象

• 在同一个代码仓库中运行两三个编码 Agent，厌倦了合并冲突和重复工作的开发者。
• 在多个服务中管理一组 Agent，需要统一的计划、名单以及跨仓库任务依赖关系的团队。
• 构建长期运行的自治 Agent，希望实现事件驱动唤醒、持久协调，并能在重启后恢复，而不是依赖轮询循环并丢失状态的开发者。

请参阅使用场景，了解它适用于哪些情况、哪些情况下属于杀鸡用牛刀，以及哪些人会选择使用它。

开始使用

推荐遵循的唯一路径。 先运行下面这组由三个命令组成的独立验证，然后按照**多席位黄金路径**设置持久化 Agent。可选适配器和生成的工作区可以稍后再处理。

前 60 秒

在干净的 Python 环境中，先验证已安装的 CLI，再将 Agent 接入真实代码仓库：

python -m pip install synapse-channel
synapse doctor
synapse demo --output ./synapse-golden-demo

synapse doctor 会报告本地设置问题，例如身份、Hub 暴露情况、根文件系统压力以及缺少等待器。新机器可能会提示当前没有 Hub 或等待器运行；在设置服务之前，这是预期情况。synapse demo 会启动自己的本地 Hub，演示规划器/工作者协调流程，并在打印以下内容时成功：

此流程中的 CLAUDE 和 CODEX 名称是进程内脚本化的 SynapseAgent 身份。演示不会启动任何提供商 CLI，也不会消耗任何模型轮次。

success: coordination demo completed

完成独立验证后，仍可选择运行 synapse quickstart-coding，体验生成工作区演示。它会创建一个临时的编码 Agent 集群工作区，运行实时重叠声明拒绝演示，成功后删除该工作区，并打印：

success: coding fleet demo completed

或者运行以下命令，一次性完成整个首次运行流程：

synapse fleet-init

它会运行 doctor（使用 --fix 修复默认的本地 Hub 和等待器），生成持久化的 ./synapse-fleet 工作区，探测这台机器可运行哪些提供商 CLI（claude、codex、kimi、ollama，……），运行演示冒烟测试，并打印后续步骤计划——启动等待器、各提供商的席位命令、git-init、仪表板——其中会填入工作区的项目名称。

最快的安全试用路径

在修改真实代码库之前，先使用以下独立路径：

python -m pip install synapse-channel
synapse doctor
synapse demo --output ./synapse-golden-demo

演示会启动并停止自己的本地 Hub，使用一次性提交的 Git 仓库，证明声明彼此独立且会拒绝重叠声明，在交接前拒绝修改操作、在交接后允许该操作，并写入一份经观察的验证回执和一个静态仪表板。它不需要持久化 Hub、提供商 CLI、Git 钩子、MCP 宿主或 A2A 桥接。同一组三命令代码块在此 README、快速入门和 CLI 参考中均作为回归测试的一部分进行校验，并且会作为真实子进程运行其中的 synapse demo 命令。

通过该验证后，使用 synapse fleet-init --fix 准备持久化的本地工作区、Hub 和等待器，然后在真实代码仓库中运行 synapse git-init --name trial-agent，再让 Agent 编辑代码。可选的 A2A 互操作性是后续步骤，详见 A2A 桥接指南；它不是首次实现协同价值的前提。

发布

此软件包以开源方式开发，并每天用于验证自身：一组编码 Agent 使用它来协调自身工作，因此问题会在实际使用中暴露并迅速修复。因此，发布频繁且大多改动较小，主要是修复和强化，而非大幅变动。当前的 0.x 版本不承诺在次要版本之间保持向后兼容。我们会防止线缆词汇和公开 Python API 意外漂移，但经过评审的 0.x 次要版本可能会有意更改其中任一接口。每项此类更改都会更新冻结的契约测试；若线缆不兼容，则会提升 WIRE_PROTOCOL_VERSION，并随版本发布变更日志和迁移说明。从 1.0.0 开始，稳定公开 Python API 的破坏性更改需要发布软件包主版本；线缆破坏性更改则需要提升线缆协议版本。请参阅API 和线缆稳定性。

1.0.0 计划作为 SYNAPSE CHANNEL 的首个稳定商业版本，届时将一并记录运营契约、打包方式、支持范围和商业许可条款。

SYNAPSE CHANNEL 正在寻求初创资金、战略合作伙伴，以及愿意共同推动协调层成熟、以支持生产环境多 Agent 开发的生态系统共建者。请参阅商业许可，或发送邮件至 [email protected]。

如果需要固定目标版本，请锁定版本（synapse-channel==X.Y.Z）；如需获取最新修复，请使用最新发布版本。两种方式都受支持。

用法

使用模型工作器运行 hub

通过一条命令启动 hub 和一两个本地模型工作器：

synapse team

如果 Ollama 未运行，synapse team 会回退到单个离线规则型工作器（使用确定性的预设回复），以便流程仍能运行；启动 Ollama 后重新运行即可获取真实模型回复。

然后，在另一个终端中查看频道或发送消息：

synapse listen --name USER                                 # terminal A: watch the channel as USER
synapse send --target FAST "what is the status of TASK-1?"  # terminal B: one-shot, unique ephemeral sender
synapse send --require-recipient --target FAST "ping"  # also print the positive receipt

不带 --name 的 send 会使用唯一的临时发送方，因此单次发送不会因监听器已使用相同名称连接而违反 hub 的每个名称仅允许一个所有者的规则。单次发送也能避免等待方名称冲突：synapse send --name api-dev-rx ... 会以 api-dev 的身份发送，同时保持持久的 api-dev-rx 唤醒套接字连接。定向发送默认请求私有回执；如果没有匹配的实时消费接收方，则以非零状态退出，包括套接字仍处于连接状态，但既没有近期响应，也没有活动等待方的情况。消息仍会记入日志并尽力路由，而 hub 会记录一条死信，不会将套接字存在报告为已送达。每次单次发送都会使用唯一的消息身份，并且只接受与之匹配的回执，因此发送方重新连接时重放的旧待处理回执不会被报告为本次发送的结果。添加 --require-recipient 还可打印肯定回执。匹配的肯定回执会以状态 0 退出；明确的否定回执会以状态 1 退出。没有收到回执时（包括来自较旧 hub 的情况），会以状态 3 退出，并显示 delivery unknown 及消息身份。--receipt-timeout 限制发送和确认的总耗时（默认 2 秒，必须为有限值、大于 0 且不超过 300）。重试未知发送前，请检查保留的 hub 日志：接收方可能已经收到消息。CLI 不会自动重新发送。不带 --require-recipient 的广播和频道发送只会报告已提交，而非已确认送达。任何回执都不能证明模型已读取或处理该消息。

对于选定的敏感载荷，请在其到达 hub 之前加密消息正文，并仅在接收方一侧解密：

synapse send --target FAST \
  --encrypt-key-file ./payload.key \
  --encrypt-key-id project-main-v1 \
  --encrypt-recipient FAST \
  "private handoff note"
synapse listen --name FAST --for FAST --decrypt-key-file ./payload.key

hub 仍能看到发送方、目标、频道 ID、密钥 ID、接收方名称、随机数、密文和送达元数据。此功能不管理密钥发现或轮换。

单独运行各部分

synapse hub --port 8876
synapse hub --port 8876 --db ./synapse.db            # crash-safe: resumes leases + history on restart
synapse hub --port 8876 --relay-log ./feed.ndjson    # mirror the channel to a compact file for observers
synapse hub --shutdown-close-timeout 5               # bound active socket close handshakes on stop
synapse hub --max-progress-per-author 500            # cap retained board progress per author
synapse hub --max-findings-per-agent 200             # cap durable findings admitted per agent
synapse hub --tls-certfile ./hub.crt --tls-keyfile ./hub.key  # native wss://
synapse worker --name FAST --provider ollama --model gemma3:4b
synapse worker --name OFFLINE --provider rule        # no network, canned replies
synapse worker --name TIER --provider tiered --model small --heavy-model big  # route trivial→rule, hard→heavy
synapse relay ./feed.ndjson                          # decode and print that file as readable lines
synapse ingest ./synapse.db --memory --cursor ./mem.cursor  # stream durable memory events since a seq cursor (NDJSON)
synapse memory-recall ./synapse.db "transport handoff"       # local recall over durable memory records
synapse compact ./synapse.db --all --max-checkpoints-per-task 3 --archive-report ./compact-report.html
synapse board                                        # print the shared task/progress blackboard
synapse task declare BUILD --title "compile" --idem-key build-v1  # retry-safe durable write
synapse task update BUILD --status done              # mark a plan task done so dependents unblock
syn ack BUILD --evidence "pytest -q"                 # post evidence and mark a board task done
synapse supervisor --idle-seconds 300 --history-multiplier 3  # re-offer stalled plan tasks
synapse manifest                                     # print capability cards, including contract counts
synapse capability-card keygen --key-id PROJECT:worker:v1 --private-out ./card.pem --agent PROJECT/worker --project PROJECT --trust ./card-trust.json
synapse directory                                    # print discovery-only agents/resources
synapse route-task BUILD --limit 3 --event-store ./synapse.db  # add observed evidence
synapse resource-bids BUILD --resource-kind gpu      # rank live resource offers without reserving capacity
synapse a2a-card --endpoint-url https://agent.example.com/a2a/v1  # emit A2A Agent Card JSON
synapse a2a-serve --endpoint-url http://127.0.0.1:8877             # run the HTTP+JSON A2A bridge
synapse doctor                                       # check for common misconfigs (identity, exposure, hub, waiter)
synapse demo                                         # installed self-check: local hub + planner/worker flow
synapse quickstart-coding                            # create a temporary coding fleet workspace and run it
synapse new coding-fleet ./demo-fleet                # scaffold a runnable two-agent coding demo workspace
synapse hub --host 0.0.0.0 --token s3cret            # require a shared secret when binding off-loopback
synapse hub --host 0.0.0.0 --token s3cret --tls-certfile ./hub.crt --tls-keyfile ./hub.key
synapse hub --max-connections-per-host 4             # cap simultaneous sockets from one remote host
synapse send --token s3cret --name USER "hello"      # agents present the token to a secured hub

Python 嵌入程序可以使用 HubConfig 配置 hub，并调用 SynapseHub.from_config(config)。显式组合工厂也支持替换整组协作者；请参阅嵌入 hub。

CLI hub 查询和 task 写入仅在收到匹配的回复后返回 0。 缺少回复时返回 1，并显示结果未确认的诊断信息。写入可能已经提交：请检查 synapse board，并在明确重试时保留相同的 --idem-key 和未更改的请求。CLI 不会自动重试超时的写入。请参阅查询确认。

对于已观察到的跨 hub 任务修订，task declare 和 task update 也接受 --causal-parent HUB_ID:SEQ:SHA256。SHA-256 是多 hub 看板溯源信息中公开的完整事件指纹。已验证的同任务父级可让已观察到的折叠仅丢弃该已证实的祖先；缺失或不匹配的引用仍保持未解决状态，绝不会被视为并发声明。 此元数据会更改建议性的已观察看板，不会更改本地声明权限。 格式错误的父级元数据会在任务写入提交前被私下拒绝。 验证过程会保留编写的原因；意外的解析器故障会返回固定文本。 看板保持不变，修正后的请求可以复用其重试键。

与你的编码 Agent 搭配使用

Synapse 协调你已在运行的 Agent；它不会取代它们。 其 MCP 和 A2A 适配器是互操作接口：它们让 Claude Code、Claude Desktop、Cursor、Codex、Copilot 风格的宿主、Aider、编排框架和其他 Agent 工具参与同一个本地协调总线，同时这些工具仍负责提示词、模型选择、工具使用以及编辑器／运行时行为。 集成演示矩阵列出了三条范围明确、可重复的路径，以及每个演示范围之外仍不支持的行为。

• **Claude Code / Codex / Claude Desktop / Cursor（MCP）：**注册 stdio 服务后，其协调工具会自动加载——无需 shell 钩子或 Synapse 专用客户端代码。

  python -m pip install 'synapse-channel[mcp]'
  claude mcp add synapse -- synapse mcp         # resolves <git-project>/mcp
  codex mcp add synapse -- synapse mcp --name my-repo/codex
  

  Claude Code 也可以使用可选的、独立版本控制的 Synapse 插件，它将此 MCP 接口与现有的感知声明的编辑钩子和可逆的配置文件引导流程打包在一起。 供应商兼容性监测每日检查官方 发布，并记录实际验证过的宿主版本。 供应商和提供商发现每周审查范围有限的 公开候选信息源，再决定是否集成。其宿主接入流程会拒绝经审查的 Pages 下载诱饵，也不会将 cron 推送评为代码来源。 宿主集成目录列出已接受的 版本，并为生命周期已验证的宿主软件包提供统一的检查／安装／诊断／卸载入口。

  可选的 pi 参与者使用固定版本的 pi 0.87.1 RPC。其 独立扩展会在支持的文件写入前检查实时声明；默认参与者不使用工具运行。

  Cursor 和 Claude Desktop 可以复用不含密钥的 examples/mcp/.mcp.json 模板。此适配器中的 MCP 不会唤醒处于空闲状态的提供方；请在每轮开始时调用 synapse_inbox，并保持 synapse arm install --identity NAME --start 处于活动状态，以便传递提示词。

• **Claude Code / Codex / Gemini / Grok / Kimi 原生文件编辑：**打印 提供方原生的工具前置配方（Claude 系列、Grok 和 Kimi 使用 PreToolUse；Gemini CLI 使用 BeforeTool），在支持的文件工具运行前检查权威的实时声明。

  synapse adapters claude-claim-hook --identity my-repo/claude --print-config
  synapse adapters codex-claim-hook  --identity my-repo/codex  --print-config
  synapse adapters gemini-claim-hook --identity my-repo/gemini --print-config
  synapse adapters grok-claim-hook   --identity my-repo/grok   --print-config
  synapse adapters kimi-claim-hook   --identity my-repo/kimi   --print-config
  synapse adapters kimi-claim-hook   --identity my-repo/kimi   --install-config
  

  --print-config 为只读操作。将 Grok 片段保存到 ~/.grok/hooks/*.json；synapse adapters install grok 会单独安装 kebab-case 的 ~/.grok/skills/synapse/SKILL.md 协调技能。Kimi 的 opt-in 安装程序只会在 $KIMI_CODE_HOME/config.toml（默认为 ~/.kimi-code/config.toml）中写入一个带标记的代码块，而 --uninstall-config 只会移除该代码块。对应的 Kimi 组合方式是 synapse adapters install kimi --identity my-repo/kimi --with-hook。

  提供商 claim-hook 指南介绍了确切的工具 覆盖范围、令牌文件设置以及原生宿主的限制。这些是有限范围的文件 防护措施，并非完整的 Bash 或文件系统隔离。

• **Aider 或任何非 MCP 工具：**编辑前先申领文件范围，并通过 Git 钩子在提交时释放。申领可防止冲突授权；工具对工作树的写入仍由操作员 负责执行，而暂存区 Git 门禁则提供独立的提交时检查。

  synapse quickstart-coding                    # optional: run a temporary overlapping-claim refusal demo
  synapse new coding-fleet ./demo-fleet        # optional: keep the generated workspace
  synapse git-init --name aider-1              # one step: install the hooks + write the conventions guide
  synapse git-claim --task-id AUTH --paths src/auth --name aider-1
  aider src/auth/*.py                          # ... edit; the post-commit hook releases the claim
  

• 检查接线情况：synapse doctor 会报告常见的设置错误——没有运行中的 等待器、未使用令牌却公开了 hub、意外的身份标识，或根文件系统空间 紧张——并为每项错误提供修复方法。使用持久化 hub 时，它还会根据接收方 水位标记报告 N undelivered messages pending for <identity>；这是 邮箱传输确认，并不能证明模型已处理这些消息。使用 --disk-path <path> 可检查承载特定工作区或缓存的文件系统。

• **查看实时面板：**运行 synapse dashboard --port 8765，即可打开仅限回环访问的只读 HTML 视图，查看成员列表、精确的黑板／认领状态列、进度、集群可见性、任务依赖图边、分支冲突候选项、发布回执和已公布的能力；相同快照也可通过 /snapshot.json 供本地工具使用。传入 --a2a-state-file <path>，即可在集群部分添加持久化的 A2A 任务和推送配置计数。面板根据黑板快照推导任务依赖关系，并使用实时认领元数据检测分支冲突；需要在客户端进一步结合 git diff 时，请运行 synapse conflicts --check-diff。状态快照还包含 dead_letters——未能送达任何活动连接的定向聊天，按目标显示计数——因此，无人接收的消息会直接显示在页面上，而不必等人转述后才被发现。面板正逐步发展为面向运维人员的 Studio——打开 /studio 查看设计系统参考——并提供基于 React 的操作台，位于 clients/cockpit/（构建说明见其 README；使用 synapse dashboard --cockpit-dist clients/cockpit/dist 提供构建后的程序包）。如果你有意使用 --allow-non-loopback 对外开放面板，请传入 --dashboard-token <token>，并要求客户端发送 Authorization: Bearer <token>；React 操作台会加载不含令牌的静态外壳，随后请求该 Bearer 令牌，并仅将其保留在当前标签页的会话存储中。它绝不会接受 URL 中的 Bearer 令牌。若在对外开放的绑定中未提供令牌，Synapse 会生成并打印一个启动令牌。团队也可以传入仅限所有者访问的 --dashboard-access-file，将不同的查看者／操作员／管理员令牌文件映射到浏览器主体和不同的中继身份。由服务器生成的能力描述符会从 DOM 和命令搜索中移除未经授权的写入控件，但每个 POST 仍会在服务器端和 Hub 端重新授权；目前，管理员除已提供的三种操作员写入操作外，并无其他变更权限。使用 --operator 后，经授权的命令面板会提供受治理的消息、任务声明和任务更新表单；每个表单都会报告 Hub 的严格处理结果，且不会授予超出 Hub 验证、ACL、速率限制和审计决策范围的权限。使用 --feeds-db 后，操作台的「审计」标签页会增量呈现通用回执账本和受治理的操作员中继历史，作为两个独立且有界、并由存储背书的数据流。回执账本包含经精简的认领和防护拒绝、死信升级、身份固定重新认领以及身份密钥登记结果，并将审批与应用明确区分；每个已声明的持久化 EventKind 都会被明确归类为包含在回执中或有意省略。缺失数据和过期的最近一次有效数据仍会显示。持久化数据流的存储和编码失败会返回固定的 HTTP 503；内部诊断信息仅保留在服务器日志中，修复存储后，后续请求即可恢复。实时持久化数据流通道使用相同的失败详情。请参阅操作台恢复指南。添加 --observed-peer HUB=URI，即可在浏览器和 /snapshot.json 中包含供参考的对等 Hub 行；这些行会标记为 observed@HUB，且绝不会授予本地认领权限。

• 验证发行版重新部署： synapse doctor --redeploy-checklist 会输出 软件包、服务、名册、持久状态和 git 钩子检查项，用于发行后重启本地服务群。它本身不会重启服务，默认也不会提供重启 命令。检查准确的实时 hub PID 和名册后，拥有最新中断授权的操作员可以添加 --redeploy-authorize-restart-pid PID；生成的命令会在持有失败即退出的主机本地托管锁时重新检查该 PID。Dogfooding 要求每个新发行标签发布后立即由本地 hub 采用，并通过这条有界授权路径及重启后的健康验证完成。

• 安装始终运行的本地服务： synapse init 会输出或安装 hub、项目在线状态和非 LLM 唤醒监听器单元。doctor --fix 会在缺少等待器时输出 准确的命令。

  synapse init --project myrepo --identity myrepo/worker --install-user-services
  synapse init --project myrepo --identity myrepo/worker --start-user-services
  synapse doctor --fix
  

• 以 Synapse 身份启动提供方命令： worker-session 会在提供方启动前导出 身份变量。从交互式终端启动时，Codex、Claude、Kimi 和 Grok 等交互式终端 提供方默认在持久 tmux 会话中运行，并在后台保持定向等待器运行。非终端命令仍使用临时的 syn arm 辅助进程路径。

  synapse worker-session --identity myrepo/worker -- codex --sandbox danger-full-access
  

• 手动检查或控制 tmux 唤醒路径： codex-tmux 是自动提供方启动路径背后的 诊断／管理界面。它会在命名的 tmux 会话中运行提供方 TUI，并在 Synapse 收到定向消息时注入固定的唤醒提示词。它不会将 Synapse 负载粘贴到终端；提供方唤醒后会自行读取收件箱。只有当现有会话的实时 tmux 环境与已配置的 SYN_PROJECT 和准确的 SYN_IDENTITY 匹配时，才会接受该会话；如果会话已由另一个席位占用，则 start、status 和 wake 都会在发送任何按键前拒绝操作。成功调用 tmux send-keys 并不视为已交付给提供方：桥接程序会观察提示词是否已被读取，并保留尚未确认的暂存提示词，以便之后仅重试 Enter，因此提供方启动不会导致提示词被搁置或重复。等待期间，桥接程序会按有界间隔断开连接，并在重新注册前再次验证会话、绑定关系和实时 Agent 窗格，因此消失的窗格不会无限期地继续显示为已注册。

  synapse codex-tmux start --identity myrepo/codex-main --session myrepo-codex --cwd "$PWD"
  synapse codex-tmux wait --identity myrepo/codex-main --session myrepo-codex --cwd "$PWD"
  

  对于无人值守运行，可用以下命令替换手动维护的 wait 进程： synapse waker install --identity myrepo/codex-main --session myrepo-codex --cwd "$PWD" --agent-command codex --start。waker 仅监督交付桥接程序并连接到现有的绑定会话；它绝不管理提供方终端的生命周期。

Agent 使用体验 — syn 命令

对于 Agent 每次会话都会运行的简短循环——启动等待器、发送消息、 读取收件箱、查看看板——该软件包还提供了 syn，这是一个基于上述命令的轻量、 身份正确的前端：

syn name                          # resolve and print this terminal's identity
syn arm                           # keep a directed-only waiter armed (named <project>-rx, distinct from the sender)
syn say REMANENTIA,CEO "ack"      # send to one, several, or all
syn ask CEO "status?"             # send, require an online recipient, and wait for replies
syn inbox                         # print messages addressed to you since the cursor
syn inbox --source hub --uri ws://127.0.0.1:8876  # read the connected hub journal
syn inbox --project-wide          # explicitly include every identity in this project
syn inbox --name PROJ/role        # read one exact identity under its own cursor
syn board                         # the shared task/progress board
syn who --me                      # show whether this identity and its -rx waiter are online
syn reap                          # list this identity's shell-hook waiter pidfile
syn reap --pid 1234               # remove a dead pidfile or SIGTERM only the verified waiter PID
syn locks                         # list this project's active leases with release commands
syn ack BUILD --evidence "pytest -q" --artifact coverage.xml
syn commit README.md -m "document the change"

它比手动编写的 shell 别名做得好的一点，就是身份。 项目依次通过 --project、$SYN_PROJECT 解析，只有在最后才会使用工作 目录。环境中的 $SYN_IDENTITY 绝不会被静默采用：只有在同时设置 $SYN_PROJECT 且两者一致时，它才会将身份细化为完整的 project/<type>-<id>；shell 钩子一同导出的这两个变量才表示明确选择启用。单独设置的 SYN_IDENTITY 或与之不一致的值（借用 shell 的特征）会被明确丢弃：命令会以本地身份继续执行并说明原因；如果本地回退值也看起来像是意外的设置（例如主目录或系统路径），则会直接拒绝执行。每个终端设置一次 $SYN_PROJECT，身份便会在各次工具调用之间保持稳定。 syn inbox 会按解析出的完整身份筛选，并推进以该身份命名的游标。它绝不会回退到共享项目游标。如果有意读取范围更广的项目消息流，请使用 --project-wide；要指定另一个精确地址，请使用 --name PROJ/name；要在各自独立的游标下读取多个常驻角色地址，请重复使用 --as PROJ/name。单独使用 --as PROJ 是明确指定项目范围别名的形式；$SYN_ALIASES 则用于提供同一份常驻别名列表。 对于远程 hub，请选择 syn inbox --source hub --uri ENDPOINT，或为 CLI 或 MCP 适配器设置 SYN_INBOX_SOURCE=hub。此模式会读取经过身份验证的日志页，并使用彼此独立的端点和身份游标，而不是过时的本地消息流。当 has_more 为 true 时，请重复读取；不可用结果不等于收件箱为空。Hub 模式会将别名视为精确身份，并排除带频道标签的聊天消息。请参阅远程收件箱。 在 hub 端，等待者身份受名称所有权租约保护：首次为某个名称执行 synapse wait/arm 时，会获发一个不透明令牌（保存在 ~/synapse/owner-lease/ 下）；每次重新布防都必须出示该令牌，并重新取得其自身名称；任何其他方认领此名称时，无论是否设置接管标记，都会被拒绝，并收到关闭代码 4016，直到租约失效（离线时的默认时长为一小时，可通过 --lease-offline-ttl 设置）。租约之下是零配置机器身份：首次连接时会为每台机器生成一个 Ed25519 密钥，hub 会在名称首次使用时将每个签名名称绑定到对应密钥（重启 hub 后仍会保留，可通过 --identity-pins 设置）；来自任何其他机器的认领都会被拒绝，直到操作员清除该绑定。一个名称，一个所有者，跨越重新连接和重启始终如此。 现在，每个自定义 hub --db FILE 都拥有自己的 FILE.identity-pins.json（路径以解析后的数据库路径为准），因此同一目录中的不同日志库无法相互改写默认绑定。常规的 ~/synapse/hub.db 和不带 --db 的 hub 仍使用历史上的主目录默认路径，SQLite 的 --db :memory: 也一样。升级时，带有旧版绑定的现有自定义日志库需要显式指定文件；请参阅绑定迁移。显式使用 --identity-pins FILE 和 --identity-pins "" 时，仍分别表示使用文件存储和仅在进程内存储。 hub 运行期间，还会监视每个尚未过期的认领以及所有已分配且未处于终止状态的看板任务。如果对应的确切所有者连续 30 秒没有新鲜的 -rx 等待者，hub 就会广播一条机器可读的 dark_seat_alert，其中包含受影响的工作以及确切的永久布防命令。重新布防会清除该事件；监视器绝不会自行释放或重新分配工作。 也会安装带连字符的别名 （syn-name/syn-wait/syn-say/syn-ask/syn-inbox/syn-board/syn-reap/syn-locks/syn-ack/syn-commit）。

命令	功能	做对的细节
syn name	解析并打印此终端的身份。	与每个 syn 命令使用相同的解析顺序——打印出的身份就是你协作时使用的身份。
syn arm	持续启用仅接收定向消息的等待器。	以 -rx 辅助身份连接（绝不占用发送方名称）；明确说明它会等待谁的消息；多次唤醒后仍保持启用。
syn-wait	唤醒原语：等待一条定向消息，打印后退出。	默认 --max-wakes 1，因此在后台任务退出时重新调用的编排程序确实会被唤醒；自动恢复连接意味着 Hub 重启后会透明地重新启用，只有真正收到唤醒消息才会结束等待。
syn say	向一人、多人或所有人发送消息。	即使等待器占用了 -rx 名称，发送时仍使用所有者身份。
syn ask	发送消息并等待回复。	要求接收方在线——问题不会悄无声息地发给无人。
syn inbox	打印发给你的消息。	默认使用精确解析出的身份及其独立游标，因此不会显示或消费发给另一终端的邮件；要扩大到整个项目范围，需使用 --project-wide。
syn board	共享的任务／进度看板。	所有 Agent 都能看到的统一计划视图。
syn who --me	查看此身份及其等待器的在线状态。	分别报告该身份、持久的 -rx 辅助身份和活动的 -pane-rx 辅助身份，因为接收器套接字不是 Agent。
syn locks	查看项目的活动租约。	打印持有者、范围、时长、剩余 TTL、检查点／Git 上下文，以及准确的 synapse release <task> --name <owner> 命令。
syn reap	清理 Shell 钩子的等待器辅助进程。	仅检查此身份的 pidfile；只有在实时命令行确认 PID 确实属于该等待器时才会向其发送信号——绝不会按模式批量杀进程。
syn ack TASK	提交证据并关闭看板任务。	可重复指定的 --evidence／--artifact 会作为由解析出的身份署名的评估备注提交；只有等待 Hub 确认后才会标记为 done。
syn commit	受租约保护、限定路径规格的提交。	持有项目 Git 租约，且仅暂存／提交指定路径，因此协作 Agent 已暂存的文件不会混入你的提交。

还有两项后续功能可补全这一流程。在 synapse arm 中添加 --mailbox，也会在等待器断开连接期间收到定向消息时唤醒它，弥补断线重连或重新启用的间隙——它会请求 Hub 在连接时重放消息，并从 ~/synapse/mailbox-cursor/ 下每个身份独立的游标处继续，以免重新启用时重放整个积压（默认关闭；需要 wire version 2 的 Hub）。 在每次邮箱唤醒中，同一持久化 Hub／序列号对的重复副本只会打印一次。文本相同但属于不同事件的消息仍会分别打印；不带有效正序列号的旧版帧仍会显示。等待器会先完成连接清理，再持久化已显示消息的游标。 Agent-tmux 使用独立的 <identity>-pane-rx 接收器，因此邮箱等待器可与实时窗格注入同时在线，且两个辅助身份互不占用对方的名称。synapse release 可附加由 Hub 回显的回执，其中包含证据、产物、变更文件、审批、已知失败、置信度和证据新鲜度；回执会附带建议性的 epistemic_status 元数据（supported、needs_freshness、stale、degraded 或 unsupported），并根据提交的证据生成原因；--receipt-json 可打印该信息，供自动化使用。 新的手动 release 会在执行变更前验证是否支持精确确认。 不受支持或无响应的中枢会返回 1，并显示 no release sent，同时保持 认领状态；已发布的中枢版本 0.48.0 和 0.99.27 需要升级到匹配的中枢版本。 手动 release 会使用 --reply-timeout 限制每次发送/回复交互的时长（默认为 30 秒）。 缺少确认时，会返回 3（结果未知），打印原始操作密钥和 SHA-256 指纹，并提供 --confirm-only 命令，用于读取精确的持久化结果，而不再次执行 release。有效的匹配授权 或持久化确认会返回 0；明确拒绝或无效的本地输入会返回 1。租约缺失和旧版回复无法提供 此类证明。关于日志和兼容性边界，请参阅 release 恢复。

若要让新终端自动连接，请安装一次 Shell 钩子：

synapse install-shell-hook --shell auto

之后，新开的 Bash/Fish/Zsh 终端会导出 SYN_PROJECT/SYN_IDENTITY，并保持一个 开销很低的 synapse arm 辅助进程运行。该钩子不会静默加入终端启动时所在的 任意 Git 检出目录。除非你明确设置 SYN_PROJECT/SYN_IDENTITY，或通过 .synapse/project 启用某个仓库，否则它会加入中性的 SYNAPSE_DEFAULT_PROJECT 通道；若该变量未设置，则加入 user：

mkdir -p .synapse
printf '%s\n' myrepo > .synapse/project

若要使用从 CWD 推导项目的旧版行为，请在该终端中设置 SYNAPSE_AUTO_PROJECT_FROM_CWD=1。该钩子还会通过 synapse worker-session 包装常见的服务提供商命令（codex、claude、 kimi、grok、gemini、agent、ask、ollama），使云端和本地大模型会话从进程启动时起 继承相同的 Synapse 身份。在交互式终端中，Codex/Claude/Kimi/Grok 会自动通过持久化 tmux 会话和定向唤醒桥接启动；用户仍然只需输入服务提供商命令。设置 SYNAPSE_PROVIDER_TMUX=0， 可让这些服务提供商使用直接执行路径；设置 SYNAPSE_AUTO_CONNECT=0，则可 为某个终端禁用该钩子。

持久性

传入 --db 后，中枢会使用仅追加的 SQLite 事件日志（标准库，WAL 模式）作为后端。声明、释放、任务更新、资源提供、任务看板写入和聊天消息都会被记录，中枢会在启动时通过重放日志重建状态。我们如实地根据工作负载区分持久性保证：带键的受覆盖协调变更会以 synchronous=FULL 一并提交其事件、规范请求摘要、确切响应和证据意图（可在操作系统崩溃后保留）；高吞吐量聊天／历史记录路径则以 synchronous=NORMAL 提交（可在应用程序崩溃后保留，但断电时可能丢失最后一次提交）。

如果存储初始化失败，SQLite 和 SQLCipher 连接会在错误传递给调用方之前关闭，包括初始化期间被中断的情况。现有事件行仍可用于诊断；不兼容的架构仍会导致启动被拒绝。此清理操作并不能保证架构迁移具有原子性。请参阅数据库启动失败。

Native Agent Evidence Format (AEF) v0.1 的生成是在此持久日志之上的显式选择加入功能。生成一个仅所有者可访问的 Ed25519 回执密钥，为中枢指定稳定身份，然后启用路由：

synapse merkle keygen ~/synapse/aef-receipt-key
synapse hub \
  --db ~/synapse/hub.db \
  --hub-id hub.example \
  --aef-signing-key ~/synapse/aef-receipt-key

受支持的证据行及其 AEF 输出箱游标会在同一个 SQLite 事务中提交。开始服务前，中枢会协调所有待处理游标；服务期间，专用工作线程会按顺序排空新行（默认间隔为一秒，可通过 --aef-drain-interval 配置）。如果在回执生成后、确认前发生崩溃，系统会复用已验证的回执，而不是重复生成。排空失败时，持久游标会保持待处理状态并重试；旧版行及其历史 Merkle 序列化方式绝不会被重写，也不会与原生 AEF 链合并。未指定 --aef-signing-key 时，中枢会保持仅支持旧版的状态。

在所有读取端消费者都已越过某个底线序列后，使用 synapse compact 对持久记忆主干进行限界。如果维护运行需要留下便于操作人员阅读的 HTML 记录，记录压缩前的事件快照，请添加 --archive-report：

synapse compact ./synapse.db --all --max-checkpoints-per-task 3 \
  --archive-report ./compact-report.html

该报告仅所有者可访问，包含事件计数、压缩底线、检查点／发现项移除计数、看板任务、发布回执备注，以及一条有界的协调时间线。它是本地事件存储的审计辅助资料；并不证明发布证据充分。

SQLCipher 实时事件存储（静态加密）

SQLCipher 提供可选的加密实时事件存储后端。 默认的 SQLite 后端除基础运行时外，不会增加加密依赖。如果需要在中心服务打开持久化协调日志时保护其页面级机密性，请安装可选扩展，并传入仅所有者可访问的密钥文件：

python -m pip install 'synapse-channel[sqlcipher]'
synapse encrypt-key generate ~/synapse/hub.key
chmod 600 ~/synapse/hub.key

# New encrypted store (main DB + WAL stay ciphertext on disk):
synapse hub --db ~/synapse/hub.db --db-key-file ~/synapse/hub.key

# Plaintext → encrypted offline migration (hub stopped; destination must not exist):
synapse encrypt-key migrate-sqlcipher \
  --key ~/synapse/hub.key \
  --source ~/synapse/hub-plain.db \
  --destination ~/synapse/hub.db

# In-place key rotation via PRAGMA rekey (hub stopped):
synapse encrypt-key generate ~/synapse/hub.key.new
synapse sqlcipher rekey \
  --db ~/synapse/hub.db \
  --old-key ~/synapse/hub.key \
  --new-key ~/synapse/hub.key.new

使用口令派生密钥时（可选），可在生成密钥时调整 scrypt 的计算成本：

synapse encrypt-key generate --from-passphrase \
  --scrypt-n 65536 --scrypt-r 8 --scrypt-p 1 \
  ~/synapse/hub.key

运维人员和分析 CLI 使用相同的密钥材料打开同一存储——缺少密钥或密钥错误时，会安全地拒绝访问（不会悄悄生成空报告）：

synapse doctor --db-path ~/synapse/hub.db --db-key-file ~/synapse/hub.key
synapse event-query ~/synapse/hub.db --db-key-file ~/synapse/hub.key 'task T timeline'
synapse postmortem ~/synapse/hub.db --db-key-file ~/synapse/hub.key T
synapse reliability ~/synapse/hub.db --db-key-file ~/synapse/hub.key
synapse causality contention ~/synapse/hub.db --db-key-file ~/synapse/hub.key
synapse dashboard --feeds-db ~/synapse/hub.db --feeds-db-key-file ~/synapse/hub.key
synapse multihub observe --peer-db ~/peer/hub.db --db-key-file ~/peer/hub.key

界面	SQLCipher 的保护范围
实时中心服务	synapse hub --db … --db-key-file — 对打开状态下的主数据库和 WAL 进行页面加密
Doctor	synapse doctor --db-path … --db-key-file — 验证密钥能否打开存储
读取器 / 分析	event-query、postmortem、merkle、causality、accounting、reliability、trust-graph、memory-recall、debug/reproduce、approval status、ttl-advice、workflow contention、participant costs、cross-repo --db、…
运维 UI	通过 --feeds-db-key-file 提供仪表板存储数据
多中心 / MCP	multihub observe --db-key-file；MCP 工具通过 event_store_key_file 获取路由观测和记忆召回所需的密钥文件

配套的整文件加密封装（可选的 [encryption] 扩展）通过 synapse encrypt-key profile|migrate|rekey|backup|restore 使用 AES-256-GCM 保护中继日志、A2A 状态文件、游标和归档。它们不能取代实时打开的 SQLite 数据库的页面加密——这正是 SQLCipher 的作用。

诚实说明其限制：SQLCipher 不保护中心服务的 RAM，不替代文件系统权限或连接身份验证，也不提供多租户隔离。未安装 [sqlcipher] 的标准安装会拒绝 --db-key-file，并提示安装方式。

完整的运维配置、密钥处理和轮换说明：静态加密。

节省令牌的观测

--relay-log 会以紧凑短键形式（encode_lite）将每条广播镜像写入换行分隔文件，因此受令牌预算限制的 Agent 可以通过 tail 文件监视通道，而无需保持套接字连接。synapse relay <file> 会将其解码为可读行，并可从已保存的 --cursor 恢复。版本 2 会保留结构化 JSON 载荷，并通过紧凑扩展映射保留所有辅助信封字段；解码器仍兼容现有的版本 1 日志。时间戳保留毫秒精度，--relay-max-lines 可限制文件大小。已提交的基准测试会比较相同完整字段集的 wire、minified 和 lite 形式——参见 benchmarks/。

暴露

默认情况下，中心服务绑定到 loopback，且不启用身份验证——这适用于一名运维人员在一台机器上使用的情况。如果这还不够（例如，使用工具的工作进程，或绑定到 loopback 以外地址的中心服务），--token 会要求提供共享密钥，连接的 Agent 必须通过 --token 提交该密钥。未提供令牌时，绑定到 loopback 以外地址会被拒绝，而不会悄悄暴露：除非设置令牌（启用指标时还需设置 --metrics-token），或明确传入 --insecure-off-loopback 接受风险，否则中心服务不会启动。这是一种适度的安全门槛，不是加密身份系统。 使用原生 wss:// 时，请同时传入 --tls-certfile 和 --tls-keyfile。TLS 可保护传输，但不能替代 --token；除非明确选择使用 --insecure-off-loopback，否则绑定到 loopback 以外地址的中心服务仍需要共享密钥。绑定到 loopback 以外地址时也必须使用 TLS，而非仅仅建议使用：通过明文 ws:// 在 loopback 以外地址传输的令牌会被拒绝（令牌和每个数据帧都可在网络上传输时被读取），因此请启用原生 TLS 或 wss:// 代理——或者传入 --insecure-off-loopback，接受在可信 LAN 上使用的风险。

MCP 服务外观

打包的 MCP 适配器会在文档所述的版本、传输和配置范围内，向宿主公开协调工具。安装可选扩展，并在受支持的宿主中注册：

python -m pip install 'synapse-channel[mcp]'
claude mcp add synapse -- synapse mcp
# or: codex mcp add synapse -- synapse mcp --name my-repo/codex

默认的 synapse mcp 会通过 stdio 运行一个模型上下文协议服务器，该服务器本身是一个 hub 客户端，并将发送、有限的持久收件箱、状态、认领、释放、交接和计划更新公开为 MCP 工具，同时将看板、状态和清单作为实时资源。它还提供只读资源模板，用于查看单个看板任务、一个 Agent 和一种资源类型。省略 --name 时，桥接会生成可见的项目标识；但并发客户端应指定不同的名称。它不会唤醒处于空闲状态的提供方；常驻等待程序仍是一条独立路径。意外的收件箱和建议存储故障会返回固定诊断信息；游标写入失败会保留原游标，并允许在故障恢复后重试。两种 MCP 传输都会使用相同的原生身份，通过有界串行重试恢复断开的 hub 连接。工具操作会保留原有的确认和重试约定；仅建立 MCP 会话并不能证明 hub 已就绪。对于私有远程客户端，synapse mcp --transport streamable-http 使用直接 TLS、预先配置的主体到席位授权，以及范围受限的项目级操作。HTTP 指南介绍了经验证的 Inspector CLI 功能范围；这并不代表兼容桌面应用或云应用。

hub 保持与 MCP 无关，核心安装也会将功能库设为可选项——请参阅 MCP 指南。

发现、建议式路由与记忆

本组中的所有界面都以提供建议为设计目标：它们会打印按优先级排序且带有来源标记的证据，供人类或 Agent 据此采取行动；这些界面都不会认领工作、预留容量、修改看板，也不会将能力卡转化为可执行信任。

界面	打印或提供的内容	权限范围
synapse a2a-card	将实时能力清单投射为 A2A Agent Card JSON 文档，可供轻量 HTTP 边缘服务用作 /.well-known/agent-card.json。	仅发现元数据。
synapse a2a-conformance	针对 A2A 1.0.0 操作模型的本地支持矩阵——支持、部分支持、不支持和外部行。	可从已安装的软件包查看；不构成外部一致性声明。
synapse directory	将能力清单与实时资源报价合并，构成仅用于发现的目录。	路由提示和审核证据；不涉及预留、授权或信任认证。
synapse route-task	按确定性本地信号对看板任务的候选 Agent 排序；使用 --event-store 时，会添加正向发布回执说明作为观测证据，每条说明均关联其来源任务和持久化事件序列。	不会认领工作、修改看板、预留资源或评定 Agent。
synapse resource-bids	按确定性理由对资源报价排序：类型、容量、任务类别／技能匹配度、描述和名称重合度、元数据。	仅提供类似市场的视图；不会预留或授权任何内容。
synapse memory-recall	对持久化发现、检查点和交接进行保留来源信息的召回：来源序列、事件类型、任务 ID、参与者、匹配的标记。	仅读取本地事件存储；不使用外部嵌入、不提供服务，也不认证事实真伪。

能力卡还可以携带声明式能力契约：按任务类别划分的 input_schema 和 output_schema 映射，以及可选的前置条件和 后置条件——这些是用于路由和审核的发现元数据，而非可执行信任授权。

现在还可以使用独立的卡片签名密钥，为能力卡添加域分离的 Ed25519 签名。synapse capability-card keygen|sign|verify 用于管理本地配置；worker --capability-card-key ... 为实时广告签名，而 hub --capability-card-trust ... 则对其进行验证。每种投射都会公开明确的验证结果，包括 valid、missing_signature、密钥／签名／过期失败、重放、降级、绑定、摘要和历史容量失败。 验证仍然仅提供建议，未签名的卡片仍然兼容。默认情况下，历史记录有界且仅保存在内存中；hub --capability-card-history-db FILE 会添加仅所有者可访问的 SQLite 重放／降级下限，该下限在 hub 重启后仍然有效；如果无法提交生命周期状态，则会明确报告 history_unavailable。

官方 Go 客户端

clients/go/synapse 为只读操作和 CI 工具提供官方 Go 客户端。它会获取 HTTP JSON 界面（例如 synapse dashboard 的 /snapshot.json），通过 DashboardSnapshot 或 GetJSON 获取数据；对于暴露的 HTTP 界面，还可选择使用 bearer 身份验证来验证仪表板令牌。 它不实现用于认领、聊天、看板写入、发布回执或在线状态的 WebSocket 变更协议。请参阅 Go 客户端指南。

官方 TypeScript/JavaScript 客户端

clients/js 提供官方的类型化 WebSocket 客户端，并以 @anulum/synapse-channel 的名称发布到 npm。与只读的 Go 客户端不同，它支持变更协议——聊天、声明、释放、看板读取、在线状态和回执。它未声明任何运行时包依赖，并要求提供兼容的全局 WebSocket，或显式提供 WebSocket 工厂。仅凭其 Node 20+ 引擎声明，并不能确定该全局对象可用。请参阅 TypeScript/JavaScript 客户端指南。

可选启用的作用域附件 API通过带签名且有界的 WebSocket 帧传输小型项目本地证据。Hub 将字节存储在私有本地存储中；仅凭哈希无法获得访问权限，大型数据集或权重仍保存在所有者控制的制品存储上。源还可以通过其私有对等方读取 API，单独允许确切的接收方 Hub、作用域、摘要和过期时间；每次元数据或分块请求都会重新检查对等方信任和所有者当前的授权。

A2A HTTP 桥接器

synapse a2a-serve --endpoint-url ... 可直接运行 Agent2Agent 边缘服务——这是一个刻意采用本地优先的 HTTP+JSON 桥接器：

• 提供公开的 Agent Card；将 POST /message:send 中的文本／数据／文件部分转发到 SYNAPSE 聊天；支持即时的 POST /message:stream Server-Sent Events；提供桥接器本地的任务列表／获取／取消路由和推送通知配置路由；提供经过身份验证、限定任务作用域且不含凭据的推送投递证据；在 /rpc 上接受 JSON-RPC 2.0。
• 运行边界：Bearer 身份验证加上请求大小／深度限制；使用 --state-file 持久化任务状态；使用 --task-timeout 使过期任务失败；使用 --subscribe-timeout 等待一次有界订阅；以及固定的、有界的三次尝试 webhook 重试计划，耗尽重试后将投递标记为死信，而不会改写已存储的任务状态转换。
• Bearer 凭据保管：运行服务和出站命令时，优先使用仅所有者可访问的 --a2a-token-file PATH。显式指定的 --a2a-token 仍可作为进程可见的兼容性覆盖选项。除非通过 --a2a-allow-insecure-http 接受风险，否则出站客户端会拒绝通过 HTTP 传递 Bearer 凭据，唯一例外是字面形式的环回 IP。
• 任务关联信息通过结构化聊天元数据（a2aTaskId、a2aContextId）传递——桥接器绝不会在聊天文本中追加或信任内联标记，因此用户编写的消息正文会作为数据处理，而非任务选择器。
• 安全措施：状态／临时文件仅供所有者访问；拒绝不安全的调用方 ID 和 webhook 目标（包括在投递时解析到本地网络的 DNS 或重定向目标）；对任务／历史记录／制品／重放保留期限进行限制，并清理终态任务；订阅重放仅限当前桥接器进程。

独立验证现已包括使用官方 a2a-sdk==1.1.0 完成的发现／发送／获取／列表／取消生命周期，以及官方 A2A TCK HTTP+JSON MUST 测试（55 项通过、5 项结构化响应失败、175 项跳过）。这是部分互操作性证据，并非认证或完全符合标准：结构化制品／直接 Message 场景、出站外部服务通过测试、公开 webhook 和代理／TLS 回执、持久化重放以及运营方部署签核仍未完成。验证仍是一系列可复现的验证回执——发现、任务生命周期、webhook、代理／TLS、重放和威胁模型——而非单一分数。可通过 synapse a2a-conformance 和 A2A 符合性矩阵查看已安装的支持矩阵；对外开放的部署还应遵循 A2A 部署威胁模型。

基于 Git 的声明

声明可以限定在其发生时所处的 git 分支，并由客户端解析：

synapse git-init --name project/agent            # persist exact identity/URI + install release hooks
synapse git-claim TASK-1 --paths src/auth.py     # or: synapse git-claim --task-id TASK-1 ...
synapse git-claim-check --staged                 # fail unless this owner covers the staged index
synapse git-claim TASK-2 --diff-base main        # optional [semantic] extra narrows safe edits to symbols
synapse git-hook install                         # (git-init already does this) auto-release on commit/merge
synapse conflicts --check-diff                   # predict cross-branch merge conflicts

围绕这些声明的是一系列安全与治理配置文件。每个配置文件都如实说明了当前状态——哪些功能已投入运行，以及每一层明确不作出哪些承诺：

配置	状态	提供的功能	明确未声称提供的功能
hub --team-secure	已发布	一键启用多席位信任配置：连接令牌、身份绑定、角色声明授权、私密定向消息（回环多 Agent 集群）。	—
hub --paranoid	已发布	严格的生产配置，并附带明确的缺失钩子检查清单：必须使用令牌的访问控制、持久事件日志、对选定帧进行逐消息身份验证、ACL + 原生 WSS、指标承载令牌身份验证。可与 --team-secure 组合使用。	—
hub --secure	已发布	严格的多席位生产总配置：组合 --team-secure 和 --paranoid，并限制每个 Agent（100/s）、每台主机（500/s）和每个主机连接（10）的洪泛速率。遇到缺失材料时会一次性列出全部内容并拒绝继续；保留更严格的操作员限制；生成一份汇总报告。	—
洪泛保护自动启用（--bridge-exposed、--expect-multi-seat）	已发布	未启用 --secure 时，如果 hub 启动时处于暴露状态（绑定到非回环地址、使用连接令牌、声明多席位意图或使用桥接），则补齐已禁用的洪泛限制。两个标志默认均关闭；也会根据已有的信任配置推断多席位意图。通过 hub 运行 A2A/MCP 的操作员应传入 --bridge-exposed。	不会自动检测运行时席位数量和桥接进程。
静态数据加密	已发布（需选择性安装额外组件）	对实时事件存储使用 SQLCipher 页面加密，并对中继日志、A2A 状态、游标和归档使用整文件 AES-256-GCM 信封；支持口令短语及明确选择的 PKCS#11 / TPM2 / 云服务商密钥封装接口、阈值托管和操作员 HMAC 声明检查。	内存保护、多租户隔离、硬件证明或新鲜度验证。PKCS#11 需要支持 AES 密钥和密钥封装，并且不支持 YubiKey PIV；物理硬件认证另行处理。
端到端加密通道	已发布（运行时）	使用 send --encrypt-key-file 加密选定的聊天载荷，并通过 listen --decrypt-key-file 在本地解密。	密钥发现和轮换；私密备注、检查点和制品属于后续工作。
私密通道	已发布（运行时）	按成员范围投递聊天消息、提供有界的仅限成员访问的历史记录、导出带通道标签的中继数据，以及仅基于元数据的事件查询筛选器。	载荷加密；密码学身份。
逐消息身份验证	已发布（可选启用）	连接身份验证后，对选定的变更帧使用 HMAC-SHA256：规范帧、密钥 ID、绑定发送方的 CLI 密钥、随机数、时间戳窗口、有界重放缓存、轮换和撤销。	载荷加密；公钥签名；身份强制实施。
身份与 ACL	已实现（TOFU + 可选的操作员强制实施）	安装 cryptography 后，使用机器密钥进行首次使用信任（TOFU）固定；支持操作员身份包、项目命名空间，以及默认拒绝的操作/目标 ACL（包括 mailbox 和 role-claim）。	自动化凭据生命周期、读取范围 ACL、所有者恢复和完整的多租户 IAM。
策略引擎	已实现首批功能（仅提供建议）	基于 git 原生声明、回执和事件日志证据，评估必需测试、严格类型检查、所有者审批、证据新鲜度、制品一致性以及无回执不得合并等规则。	不会单独阻止任何操作——由操作员决定将哪些规则设为钩子或 CI 门禁。
签名事件与 mTLS	库/运行时基础功能已发布；打包配置尚在准备中	Ed25519 帧验证、重放/范围检查、相互 TLS 服务端上下文，以及用于受保护多主机路径的证书固定信任包。	不会自动在投影后的日志行中保留发送方签名；hub CLI 尚不能加载签名事件信任和客户端 CA；不提供托管密钥生命周期、载荷加密或外部联合认证。
差分隐私黑板	设计目标	为多组织视图提供经过脱敏和加噪的黑板投影；操作员看到的本地原始黑板数据保持精确。	载荷加密；替代私密或端到端加密通道；匿名化原始日志。
签名能力卡	已发布（仅提供建议）	独立的 Ed25519 卡片密钥和限权信任包；严格规范的签名；过期、撤销、绑定、摘要以及重放/降级诊断；可选的仅限所有者访问的 SQLite 历史记录（跨 hub 重启保留）；通过清单、目录、仪表板、MCP 资源和 Agent Cards 提供投影。	授权工具；替代逐消息身份验证或签名事件；为 Agent 设置沙箱；托管密钥分发；强制准入。
synapse git-init 会将确切的身份和 hub URI 记录到本地 Git 配置中，可选择记录令牌的文件路径（绝不记录令牌内容），只安装非阻塞的 post-commit/post-merge 自动发布钩子，并写入一份简短的 .synapse/git-claims.md 指南。本仓库还会将 git-claim-check --staged 接入 pre-commit：它会自行读取以 NUL 分隔的 Git 索引；除非已配置的所有者在同一规范工作树和分支上拥有覆盖每个已暂存路径的可编辑声明，否则会安全地拒绝通过。对于语义声明，它会解析 HEAD 与索引之间的差异，并检查被改动的确切 tree-sitter 声明；证据不完整时，要求范围会扩大到整个文件；解析器失败则会拒绝通过。Git 序列化锁不属于路径声明。已暂存索引为空时，即使没有 hub 也会成功，因此 pre-commit run --all-files 仍保持隔离。synapse state 会显示每项声明的分支，而 synapse conflicts 会标记即将在合并到同一基准的分支上编辑相同文件的 Agent。
当两个分支的差异都可用时，--check-diff 会将目录或整个工作树声明缩小到两个分支实际都更改过的文件。
启用可选的 semantic extra 后，--check-semantic 还会比较固定版本上的命名声明。外层声明与其成员重叠；证据不可用或存在歧义时，会保留警告。缺少 hub 快照时会返回错误。这种已提交差异视图既不会预留工作，也不能证明行为彼此独立或合并时不会冲突。hub 保持与 git 无关——它会将分支作为不透明元数据存储，且从不运行 git 或读取文件系统——因此所有 git 操作都在客户端上进行。请参阅原生 Git 声明指南。

协调会话时，如需简洁的租约视图：

syn locks              # current project only
syn locks --all        # every active lease
syn locks --owner api  # one owner or project namespace

手动释放也作为收尾记录时，可直接附上证据：

synapse release BUILD --name api-dev \
  --evidence "pytest tests/test_feature.py -q: passed" \
  --changed-file src/synapse_channel/feature.py \
  --artifact coverage.xml \
  --receipt-json

如需观察而非手动输入收尾证据，synapse verify-release 会运行已声明的命令，记录退出代码和 stdout/stderr SHA-256 摘要，为指定的构件生成哈希，捕获 Git HEAD、树和已更改文件，然后写入收据 JSON，供 synapse release --receipt 使用：

synapse verify-release BUILD --name api-dev \
  --run ".venv/bin/python -m pytest tests/test_feature.py -q" \
  --artifact coverage.xml \
  --output verified-release.json
synapse release BUILD --name api-dev --receipt verified-release.json --receipt-json

最终的 supported 状态仍仅供参考：它描述的是新提交的证据，而不是对检查或构件是否充分的独立证明。

为更安全地选择任务并生成发布收据，本地测试归属映射会结合 AST 导入和保守的文件名回退规则，将源文件关联到可能归属的测试：

python tools/test_ownership_map.py --check \
  --source src/synapse_channel/core/receipts.py \
  --require-owned src/synapse_channel/core/receipts.py

它是一个确定性的本地辅助工具，可用于选择有针对性的测试；不能替代审查、覆盖率或发布收据证据本身。

当源代码更改可能导致生成的输出过期时，可通过生成输出依赖映射查询哪些生成路径应包含在同一项声明中：

python tools/generated_dependency_claims.py --claim-args \
  --source src/synapse_channel/core/receipts.py

该命令会为 synapse git-claim 输出 --paths ... 参数，也可为发布工具输出 JSON。它是一个确定性的协调辅助工具；实际负责生成构件的生成器（例如 python tools/capability_manifest.py --check）仍负责检查生成构件本身是否为最新。

对于语义任务范围，可将模块、公共符号、API 表面、测试、生成构件、迁移或源路径解析为普通声明路径：

python tools/semantic_claims.py --selector \
  symbol:synapse_channel.core.receipts.build_release_receipt \
  --claim-args

对于符号或 API 选择器，解析器会输出一个合成的后代路径，例如 src/synapse_channel/core/receipts.py/.synapse-symbol/build_release_receipt；可能归属的测试和生成输出仍作为整个文件的配套项。模块、源文件、测试、生成文件和迁移选择器也仍以整个文件为单位。hub 会使用现有的路径祖先规则：不同函数可以共存，而类、整个文件或父目录声明仍会与其下的每个符号冲突。

对于日常声明，synapse git-claim 可直接解析相同的选择器：

synapse git-claim TASK-RECEIPTS \
  --symbol synapse_channel.core.receipts.build_release_receipt \
  --semantic-evidence-json semantic-evidence.json

该命令会在本地解析当前 Git 根目录，将选择器展开为规范的声明路径，并在需要时写入可用于回执的选择器证据。

若要从实际跟踪的差异中推断范围，请安装可选的本地解析器包，并从基准版本进行声明：

pip install 'synapse-channel[semantic]'
python tools/semantic_diff_claims.py --base main --claim-args
synapse git-claim TASK-WORKER \
  --diff-base main \
  --diff-path src/synapse_channel/core/worker.py \
  --semantic-evidence-json semantic-evidence.json

客户端会将新旧源代码两侧的零上下文代码块映射到最小的命名声明，支持 Python、JavaScript/JSX、TypeScript/TSX、Rust、Go、Java、C# 或 Ruby。重命名会同时声明两个符号名称。对于添加／删除／重命名状态、模块级编辑、不受支持或无效的语法、超大源文件，以及其他所有不完整映射，范围都会扩大到整个文件。语法包会随额外组件一起安装；运行时不会下载任何内容，不会新增线缆字段，也不会由 hub 访问 Git。JSON 是规划证据，不是正确性证明。

语义范围会在客户端端到端强制执行。只有当同一物理源文件和工作树中没有其他所有者持有不同符号时，精确的提供方编辑工具（Edit／replace／search_replace 风格）才能暂时使用符号声明。整文件写入和补丁工具必须声明整个文件。暂存门控会在提交前验证索引中的确切符号，而自动释放会重新检查已提交的差异，并且只释放实际更改的符号。暂存门控遇到不明确或不可用的语义证据时会采取失败关闭策略；非阻塞的提交后释放则会保留声明。并发编辑同一文件中不同符号时，请使用隔离的 Git 工作树。

在合并或交接之前，导入图合并风险雷达会将更改文件与已声明路径、包内 Python 导入邻接项、CODEOWNERS 和已映射的测试所有者进行比较：

python tools/import_merge_risk.py --changed src/synapse_channel/core/receipts.py \
  --claimed src/synapse_channel/core/state.py --check

使用 --base main --head HEAD 替代 --changed 来读取本地分支差异，或使用 --claims-json claims.json 输入来自外部声明快照的路径。该雷达是本地的建议性规划检查；它会预测可能发生的冲突，但不能替代测试、审查或发布回执证据。

若要事后调查协作情况，请直接查询持久化事件日志：

synapse event-query ./synapse.db "task TASK-1 timeline"
synapse event-query ./synapse.db "task TASK-1 at seq 120" --json
synapse event-query ./synapse.db "path src/auth.py between 0 9999999999"
synapse event-query ./synapse.db "conflicts at seq 120"
synapse event-query ./synapse.db 'timeline("TASK-1").'
synapse event-query ./synapse.db 'MATCH (task:TASK {id:"TASK-1"}) RETURN timeline'
synapse postmortem ./synapse.db TASK-1
synapse debug ./synapse.db --fork-at 142 --set status=blocked
synapse reproduce ./synapse.db TASK-1 --expect 9f2c…
synapse causality causes ./synapse.db 142
synapse causality causes ./hub.db peer:96 --peer peer=./peer-hub.db
synapse merkle root ./synapse.db
synapse reliability ./synapse.db
synapse accounting report ./synapse.db --pricing pricing.json --budget budget.json
synapse fleet-scorecard ./synapse.db --trend bench-trend.db --out fleet-scorecard.json
synapse approval request --name dev --subject TASK-1 --reason "needs sign-off"
synapse approval status ./synapse.db --pending
synapse ttl-advice ./synapse.db

此时间事件日志查询路径为只读。它会从 synapse hub --db 创建的 SQLite 事件存储中重建任务时间线、指定序列号或时间戳时的任务状态、路径触碰时间窗口，以及历史文件范围冲突。类似 Datalog 和 Cypher 的示例只是同一小型查询模型的原型别名，并非独立的图数据库或可变策略引擎。

当任务需要可重放的事后分析报告用于交接或事件记录时，请使用 synapse postmortem ./synapse.db TASK-1。报告包含持久化任务时间线、所有者、释放记录、评估证据、重建的路径重叠冲突，以及可能未获回复的消息。可能未获回复的消息是指日志中存在提及该任务 ID 的定向聊天，且之后没有匹配的聊天回复；这是一种审计信号，并不能证明任何意图。

使用 synapse debug ./synapse.db --fork-at 142 可回溯日志中的任务并检查假设情形。它会重建任务在该序列号时持有的确切声明状态——所有者、状态、路径和已保存的恢复检查点——然后打印 Agent 可从该处继续执行的恢复清单（使用 --set FIELD=VALUE 可覆盖恢复字段），并列出随后实际发生的事件。hub 不会运行任务，因此这只是只读检查，并非重新执行；如果任务在该时点没有有效声明，它会以 1 退出。

使用 synapse reproduce ./synapse.db TASK-1 可将任务的权威历史记录指纹化为可移植的 SHA-256 摘要。hub 状态是只追加日志的纯折叠结果，因此相同的声明快照和释放记录在每台机器上重放后都会得到相同摘要；--expect DIGEST 可将其用作门控，在任何不一致时失败，方式与验证发布回执相同。 使用 synapse causality causes ./synapse.db 142 可追溯日志中的协调因果关系。该命令会将持久化事件折叠为一个有向无环图，其中包含三种已记录的关系：任务自身的生命周期、由依赖项完成而满足的声明式 depends_on，以及让之后与之路径重叠的声明得以继续的释放事件；它还会针对事件序列回答问题：causes 查询某事件之前发生了什么，effects 查询该事件促成了什么，counterfactual 查询如果没有该事件作为已记录的原因，哪些下游事件会失去其记录的原因。这是根据已记录的调度语义推断出的协调因果关系，并非统计因果发现；每条边都有具体事件作为依据，反事实则是对推断图进行的结构化假设分析。使用 --peer HUB=PATH 时，相同的查询可追溯跨联邦 hub 的因果关系：日志按确定性的多 hub 顺序合并，事件使用 HUB:SEQ 标识；由两个不同 hub 分别记录边两端的边会标记为 federation——这是按时钟排序的证据，因为各 hub 没有共享的序列；其行为与多 hub 读取侧一样，仅供观察。--clock-skew HUB=SECONDS 会在离线联邦报告中标注测得的本地与对端时钟偏差警告；--dot 会将联邦查询结果渲染为 Graphviz 有向图，每个 hub 对应一个集群，并为联邦边着色，一眼即可看出跨 hub 拓扑。 synapse causality otel 会将该图投影到 OpenTelemetry span 上——每个任务对应一个 trace，跨任务依赖／争用边对应 span 链接，ID 为确定性的——并将结果写为 JSON（--out），或通过 HTTP 推送真正的 OTLP（--endpoint，可选额外安装项：pip install 'synapse-channel[otel]'）；--service-name 用于区分共用一个可观测性租户的 hub，--filter TASK_ID 可将投影范围缩小到指定任务，而不会截断它们的跨任务链接；记录生命周期失败终态的事件会将 span 状态设为 ERROR；--watch 会按固定间隔重新导出——由于 ID 具有确定性，因此可在采集器端实现幂等。synapse causality health 会遍历同一张图，并标记孤立声明（已声明，之后无动静）、从未完成的声明式依赖，以及超过阈值后仍无动静且尚未释放的声明——时间长度以日志自身的最终时间戳为准，结果具有确定性且可重放；退出码 1 表示存在异常。

使用 synapse compliance export ./synapse.db --json 可生成只读快照包，其中包含 Merkle 承诺、不含负载的元数据和明确的行 MAC 溯源信息。compliance retention 会根据六个日历月的周年日进行观察；compliance report 会在 eu-ai-act 标签下汇总两者。这些观察不会给出合规性判定。有关现有密钥要求、完整导出的预算和时钟限制，请参阅记录观察结果。

使用 synapse merkle root ./synapse.db 可将持久化日志提交为单个 Merkle 根——这是涵盖每个事件的 32 字节指纹，因此，持有相同日志的两位操作者或两个联邦 hub 会得出相同的根；若根不匹配，则证明日志并不相同。synapse merkle prove ./synapse.db 142 会为单个事件生成 O(log n) 包含性证明，而 synapse merkle verify proof.json 无需事件存储，即可离线使用受信任的根验证该证明——这就是关注者运行的轻客户端验证。该树遵循 RFC 6962（证书透明度），因此叶哈希无法伪造为内部节点。它对日志所含内容作出承诺——即完整性和包含性——以覆盖整个日志、可增量验证的承诺，补充 reproduce（单个任务的摘要）。 带日志的中心还会在日志之外，将该承诺持久化为哈希链检查点——存放在日志旁、仅所有者可访问的 <db>.checkpoint.db 中——并在提供服务前根据最新链环验证日志：如果日志被截断末尾或替换，启动时会直接触发 AntiRollbackError，而不是静默重启；通过验证的链顶会锚定为下一条链环。服务期间，它每隔 --checkpoint-interval 秒锚定一次（默认为 60 秒），并在正常停止时再次锚定，因此启动后写入的内容也会受到保护；只有崩溃前最后一个间隔内的内容尚未锚定。synapse merkle checkpoint ./synapse.db 可显示最新链环，而 --verify 会重新检查日志是否与其一致（干净时退出码为 0，检测到问题时为 2）。这是本地防回滚层；外部见证仍受所有者权限限制。诸如 synapse compact 这样的有意重写会按设计触发检测；操作员的补救措施是删除检查点存储，让中心锚定一条新链。

使用 synapse reliability ./synapse.db 获取仅基于证据的可靠性记忆。它会跟踪过时声明、已声明的失败检查证据、中断的交接候选项，以及合并冲突频率，将其作为审计信号，而非评分。它不会对 Agent 排名、评定信任等级，也不会取代对底层事件行的审查。

使用 synapse accounting 可选择启用模型成本／令牌用量统计。此统计投影不会请求模型提供商；单独配置的工作进程和参与者可以调用其后端。用量总计来自记录的备注：synapse accounting record 会提交一条 usage 类型的进度备注，而 synapse accounting report ./synapse.db 会将这些备注汇总为按 Agent 和模型统计的总量；可选的 --pricing 用于估算成本，--budget 用于提供预算证据。预算是证据，不是强制执行关卡。

使用 synapse fleet-scorecard ./synapse.db --out fleet-scorecard.json，将现有的因果跨度、选择启用的统计、咨询性质的声明争用，以及仅基于证据的可靠性报告，合成为一个原子写入、仅所有者可访问的 JSON 包。--trend bench-trend.db 会纳入带完整主机上下文标签的基准测试历史记录。使用可选的 otel 扩展时，可将 --out 替换为 --endpoint http://127.0.0.1:4318：该命令会将追踪信息和当前评分卡指标推送到采集器的标准 HTTP 信号路径。它不会收集用量、对 Agent 排名、抢占声明，也不会假装当前指标能补齐历史基准测试时间戳。

使用 synapse approval，为暂停的任务或受策略控制的发布设置人在回路中的审批关卡。synapse approval request 会将主题置为 awaiting_approval，synapse approval decide --approve|--reject 会记录决定，而 synapse approval status ./synapse.db 会将备注重放为每个主题的当前状态（以最新事件为准，因此重新请求会重新打开关卡）。它是咨询性质的证据和审计跟踪，并非硬性运行时关卡；发布回执可通过 synapse release --approval 引用已批准的主题。

使用 synapse attention，将待审批事项、交付失败、恢复情况以及可选的私有配额新鲜度投影到一个仅限所有者本地的队列中。synapse attention list 可区分安静的队列和缺失的观察器；延后提醒和解决提醒只会影响警报，不会影响底层审批或交付。当 synapse dashboard --attention-store 指定其数据库时，经过身份验证的驾驶舱可读取同一队列。通用桌面摘要需要显式选择启用 --desktop。 Agent 信任图谱将这些可靠性信号、正向发布凭证、交接结果和冲突历史连接成可检查的证据图谱：synapse trust-graph ./synapse.db 会打印带事件日志溯源信息的类型化证据边，并可按 --agent、--task 或 --since 衰减时间窗口筛选，支持文本、JSON 或 Graphviz DOT 格式。它不会对 Agent 排名、评定信任等级、授权执行、取代代码审查，也不会取代身份与 ACL；路由集成和负责人批注工作流仍是设计目标。

联邦信任模型提供了可选的运行时：默认拒绝的对等方策略和生命周期存储、签名帧授权、受防护的多中心路径，以及 federation offer/fetch/import/list/rotate/revoke 捆绑工作流。运营人员仍需通过带外比对指纹来建立信任；没有自动信任分发、证书颁发机构或外部联邦认证，本地优先的默认设置也保持不变。

Agent 空中交通管制架构说明了已发布的组件如何组合成一个控制循环——隔离（声明）、合并风险雷达（冲突）、证据门控完成（凭证、策略检查、审批）、事后重放（事后分析、可靠性）和记忆（摄取接口）。这是一个架构，而不是调度器：只有声明会限制变更，其余一切都是只读或建议性的。

已发布的跨 Agent 适配器套件提供 synapse adapters，用于检测已安装的编码工具，并在每个工具的原生配置中写入精简的声明感知型适配器。Kimi Code 同时支持用户级 kimi skill（位于 $KIMI_CODE_HOME 下）和优先级更高的显式 kimi-project skill；其原生声明钩子是单独选择启用的。Python 框架垫片仍是有文档说明的轻量客户端模式。适配器只传达“编辑前声明、提交时释放、连接到中心”——Synapse 保持角色中立，不添加新的协调原语。

通用安装会拒绝覆盖现有的、未归属的专用文件；显式使用 --adopt-existing 会保留这些文件的原始字节，以便卸载。记录的托管信息也会保留共享文件中的外部文本，并拒绝更改已托管的内容。使用 synapse adapters recover TOOL 可协调中断的更新。 多中心同步（CRDT）研究探讨了多个中心能否在保持声明安全和本地优先的同时同步状态。核心结论是：诚实的只追加事件日志使用唯一的 (hub_id, seq) 标识时可以收敛，但如果同一标识对应的内容冲突，就会在发布状态或游标前拒绝操作，并将对等端隔离。声明用于互斥，不是 CRDT——它们按每个命名空间单一所有者的原则进行路由，并在网络分区时拒绝操作。目前提供的功能是由运维人员管理的对等连接：synapse multihub follow 和 --observed-peer HUB=URI 视图会将对等端日志作为建议性的 observed@HUB 状态进行观察；本地声明权限仍由本地掌控，或明确路由至所属中心。两个中心上的 Agent 可以直接通信：使用 synapse hub --message-peer HUB_ID=URI，发送给 PROJECT/seat@HUB_ID 的聊天或投递意图会通过已固定的双向 TLS 转发给该对等端。对等端必须授予目标命名空间权限。聊天会从持久化发件箱重试，直到收到回复或过期；对等端会对重试去重，因此聊天只会在对端排队一次（协议）。初始请求和重试请求若重叠，会共享同一个转发会话；其他聊天彼此独立。终态回执会合并，并在离线发送方下次注册时继续保持待处理状态，即使重启后也是如此。已停止的持久化监视器只有在运维人员接受新的日志世代或检查点后，才能通过 synapse multihub recover 记录显式恢复；仅重新连接永远不会解除隔离。网络对等端观察拉取还会携带游标延迟和对等端欢迎帧的时钟偏差，便于运维人员了解按时间戳排序的跨中心证据何时依赖于其配置的时钟一致范围之外的时钟。

沙盒工具与市场研究探讨了如何安全运行不可信工具代码——使用受限能力的 WebAssembly 沙盒（默认拒绝文件系统、网络和资源访问）——并且只有在此基础上，才能构建基于已签名能力卡、显式权限清单和运行回执的市场。该沙盒仅适用于通过 synapse sandbox 启动的模块，不涵盖普通提供方进程和远程 MCP 工具。它通过可选的 [wasm] extra 提供。已签名能力卡和 ACL 工具是独立功能，并未组合成市场准入流程；CLI 会检查所提供清单的摘要并要求使用 --approve，但不会验证卡片签名或调用方身份。WASI 时钟仍可用；来宾资源限制不会限制编译或实例化过程。WASM 沙盒入门指南将带领运维人员从工具源码开始，依次执行 validate、test 和 run。市场分发层仍只是一份边界规范——始终坚持本地优先和默认拒绝。

托管 GitHub App 设计明确了托管式跨 PR 冲突预测的边界：预测本身复用现有的本地核心冲突查找器，而使其成为托管服务的一切——webhook、GitHub 身份验证、checks API 和托管——均不纳入本地核心。可独立安装的 App 框架会验证已签名的 webhook 并写入中性的 checks；注册和托管是独立的准入环节。本地审查反馈工作流会保留已签名的审查证据，要求中心独立作出决定，并将通知路由到确切的作者席位和原生会话绑定，不会自动合并或执行模型。

使用 synapse ttl-advice ./synapse.db 获取只读的自适应租约 TTL 建议。它会从事件日志中提取已完成任务的持续时间样本、活跃的实时声明数量和过期声明数量，然后打印建议的默认值。它不会更改中心默认值，显式设置的手动 TTL 值仍优先生效。

协调模型

1. 开始工作前先领取任务：Agent 按 ID 租用任务；有效租约会阻止其他 Agent 领取同一任务。
2. 领取时声明文件范围（worktree 和 paths）；如果文件与另一 Agent 的有效领取范围重叠，Hub 会拒绝此次领取。这是授予时的互斥机制，而文档说明的提供方钩子和暂存 Git 门禁会确保受支持的修改路径符合要求。不同的 worktree 标签不会在 Hub 发生竞争，因此并发编辑时请使用实际隔离的 Git worktree。
3. Hub 操作（例如心跳和快照查询）会评估租约是否过期。文档说明的修改操作会检查所有权，并在提供租约 epoch 时检查该值。--require-fencing-epoch 会拒绝未提供 epoch 的受支持租约修改；这些检查无法阻止外部进程写入文件。所有者可以保存持久检查点字符串；租约过期后，新领取者可以将其作为恢复提示继承。Hub 本身不会重启 Agent、恢复进程状态，也不会验证检查点内容。
4. 完成后释放任务；任务进行期间可以附上状态和可选的制品引用。已持有的任务也可以原子地移交给另一位在线 Agent，同时保留其范围、状态和上下文，不给第三位 Agent 留下在移交期间抢占任务的机会。
5. 随时可以查询在线状态、who、完整状态快照和聊天历史。重新连接到同一个运行中的 Hub 后，Agent 可以通过 idem_key 恢复（只要 Hub 保留幂等缓存，重试领取就不会重复执行），并通过 resume 游标准确获取错过的消息。

除了租约注册表，共享黑板还保存团队计划：其中包含带依赖关系的已声明工作任务清单（Hub 会拒绝依赖循环，因此 ready 任务的状态定义明确），以及监督者可读取、用于发现停滞情况的只增进度清单。已声明的 LedgerTask 是计划；领取是执行该计划的租约——两者共用任务 ID，但彼此独立，因此简单的领取流程仍可正常使用。Hub 会在全局、每位作者和每个任务 ID 维度限制进度视图的大小（--max-progress、--max-progress-per-author、--max-progress-per-task），而持久事件日志会一直只增，直至显式压缩。持久发现结果也设有每位 Agent 的准入上限（--max-findings-per-agent），以免单个生产者填满共享记忆主干。使用 synapse board 查看黑板。

synapse supervisor 仍是确定性的，不使用 LLM。达到固定的 --idle-seconds 上限后，它会重新提供 in_progress 任务；默认情况下，如果同一黑板中已完成任务的进度节奏显示本地模式更快，还可以调低此上限。使用 --no-predictive-stall 可停用基于历史节奏的补充机制；这是一种本地黑板参考性启发式，并不能保证工作确实已被放弃。

请参阅 TEAM_PROTOCOL.md，了解工作约定和消息参考。

为什么不直接使用 git worktrees？

Worktree 是一种很好的工具，SYNAPSE 会与它们配合使用，而非与之竞争： 一个 claim 会声明其 worktree，携带不同规范 worktree 身份的 claim 不会争用文件。但 worktree 只能解决文件隔离问题，而且只是将冲突 推迟到合并时才处理。它们无法提供以下能力：

• 工作去重 — 两个 Agent 在两个 worktree 中可能各自构建同一项功能；共享看板上的任务一旦被 claim，在其租约有效期间就无法再次被 claim。
• 实时 claim 准入 — 在同一个 worktree 中（共享检出目录的常见情况），只要第一个权限仍然有效，hub 就会拒绝第二个与之重叠的文件范围 claim。此拒绝规则用于控制 claim 准入；涵盖范围内的提供商钩子、已暂存 Git 门禁以及隔离 worktree，则分别提供其文档中说明的变更边界。
• 可见性 — 你可以查询在线状态、有效 claim、带依赖关系的任务看板和进度，而不必通过各个 Agent 的分支差异来了解它们做了什么。
• 连续性 — 租约会过期，检查点可在崩溃后保留，任务可原子性交接；Agent 失效后留下的 worktree 只不过是一个过时目录。
• 持久记录 — 追加式事件日志会记录谁 claim、执行和释放了什么，可在事件发生后回放（synapse causality、synapse debug），而分支拓扑无法记录这些信息。

如果你已经在使用按 Agent 划分的 worktree 并且效果不错，就继续使用——让 hub 在这些 worktree 之间传递 claim、计划和审计跟踪。

库的使用

import asyncio
from synapse_channel import SynapseHub, SynapseAgent


async def main() -> None:
    hub = SynapseHub()
    asyncio.create_task(hub.serve("localhost", 8876))
    agent = SynapseAgent("ALPHA", uri="ws://localhost:8876")
    # ... drive the agent: claim, chat, request state ...

类型化的 log_recall(..., idem_key=...) 和 record_finding(..., idem_key=...) 助手接受由调用方保留的重试键。 使用 SynapseHub(journal=...) 时，每次获准的记忆写入及其精确响应都会一同提交：相同的重试请求会在重启后重放，而将同一个键用于不同内容则会遭到拒绝，且不会泄露该键或先前的值。此键不会让未记录日志的 hub 具备持久性；被拒绝的发现也仍属于非事件，而非持久化的成功操作。

两个独立且可运行的演示位于 examples/： coordination_demo.py 通过总线演示完整的任务流程（声明、阻塞、claim、拒绝重叠请求、解除阻塞、交接），llm_team_demo.py 则向频道内的模型工作者提问。每个演示都会启动自己的进程内 hub，因此运行 python examples/coordination_demo.py 即可，无需进行其他设置。

架构

模块	职责
state	在线状态、作用域任务认领租约、epoch/版本和资源提供项（与传输方式无关）。
ledger	共享黑板：已声明的任务计划（含依赖项）和有界进度流。
scoping	检测工作树和路径重叠，并拒绝冲突的有效认领。
lifecycle	类型化的任务状态及中心强制执行的合法转换。
deadlock	检测等待图中的循环，拒绝循环等待认领。
protocol	线路上的消息封装和消息类型常量。
relay_codec	带版本的轻量/重量封装编解码器（encode_lite/decode_lite），兼容旧版行格式。
relay	仅追加的 NDJSON 日志、游标、裁剪，以及供基于文件的观察者使用的命令规范化辅助函数。
archive_report	为压缩后的事件存储历史和发布回执说明生成静态 HTML 存档报告。
hub	路由核心：连接、名称、历史记录、广播。
a2a_http_handler, a2a_http_routes	有界 HTTP 接入和有序 A2A 路由，通过 a2a_http.build_a2a_handler 绑定。
dashboard_handler_binding, dashboard_http_pages, dashboard_http_live	每个服务端的读取器、外壳/快照和有界 NDJSON 传输，受仪表板现有访问检查保护。
pane_wake	通过 agent_tmux.inject_wake 分阶段准备并提交唤醒，包含经过验证的窗格绑定和重试状态。
agent_pane_state	提供方标记优先级、提交就绪状态、分阶段提示观察结果和选择启用的原生输入就绪状态，供 agent_tmux 外观层使用。
opencode_composer, opencode_composer_files, opencode_composer_probe, opencode_composer_startup, opencode_composer_state	选择启用的 OpenCode mini 输入验证：私有回调文件、精确草稿比较、符合条件的新客户端启动、进程绑定回读和启动绑定唤醒状态。
lingering_close	在有界时间、字节数和数量限制内，有序结束请求尚未读取完毕的 HTTP 连接，适用于两种 HTTP 服务端。
client	可复用的异步 Agent 连接和协调辅助函数。
persistence	基于 WAL 的事件存储，具有文档说明的持久性类别，并可恢复保留的受支持事件。
journal	将变更记录为事件，并在重启时重放事件以重建状态。
ratelimit	已配置的每 Agent/每主机令牌桶和每主机连接上限，约束其接入面；它们并不能防止资源耗尽。
auth	可选的共享密钥连接令牌（提供适度保护，并非加密身份凭证）。
chat_backends	可插拔的回复后端（兼容 OpenAI 的 HTTP、基于规则）。
routing	将请求分类为任务类别，并将其路由到分层后端。
llm_worker	通过后端回答定向消息的通道内 Agent。
stall	确定性的固定阈值和历史节奏停滞策略。
supervisor	无需大模型的监视器，用于发现停滞的计划任务并重新提供这些任务。
capability	Agent 能力卡片（A2A 形态）和中心聚合的清单。
capability_contracts	由清单卡片携带的声明式输入/输出能力契约。
capability_directory	仅用于发现的目录，整合能力卡片和资源提供项。
semantic_routing	基于任务板任务和能力卡片，为任务到 Agent 的匹配提供本地建议。
capability_observations	保留来源信息的已观察发布回执证据，供建议式路由使用。
resource_bidding	基于实时能力目录对资源提供项进行建议式竞标。
memory_projection	对持久化发现、检查点和交接内容进行确定性的本地回忆。
launcher	一条命令即可启动本地中心和工作器。
cli	统一的 synapse 命令。

功能清单

模块与界面清单 — 由 CI 根据源代码树同步维护计数。

SYNAPSE CHANNEL 功能清单

界面	当前清单
软件包版本	0.99.38
公共 API 导出项	70
软件包模块	810
类	1185
线路消息类型	114
CLI 子命令	258
测试函数	11638
基准测试工具	11
文档页面	87
GitHub Actions 工作流	27
可选依赖组	14

此快照是根据源代码树生成的静态清单。性能和覆盖率声明均有各自提交的证据，请参阅 VALIDATION.md 和 benchmarks/。

文档与项目

• 初次接触？使用案例 · 对比说明 · 常见问题 · 故障排除 · 术语表
• ARCHITECTURE.md — 模块图与协作模型。
• TEAM_PROTOCOL.md — 工作约定与线路参考。
• VALIDATION.md — 测试方式以及变更必须通过的门槛。
• CONTRIBUTING.md · SECURITY.md · GOVERNANCE.md · ROADMAP.md
• 完整文档站点：https://anulum.github.io/synapse-channel

安全态势

协作保证由不变量符合性计划跟踪。该计划生成的六边界注册表经过机器检查，目前报告的整体符合性为部分符合；未完成的边界会明确标出，而不会因常规测试覆盖率而继承绿色状态。

默认优先本地运行：中心绑定到 loopback；除非配置了令牌（或操作人员通过 --insecure-off-loopback 明确接受暴露风险），否则拒绝绑定到非 loopback 地址。部署跨越此边界时，所有控制措施均为选择启用，且默认拒绝：

• 连接身份验证 — 使用恒定时间比较的共享密钥令牌（优先使用 --token-file 或 SYNAPSE_TOKEN，而非 --token，后者会显示在进程列表中）。
• 逐消息身份验证 — 使用 --message-auth-key 并启用 --require-message-auth，可在连接身份验证后，要求选定的变更帧进行绑定发送方的 HMAC 身份验证。使用 --db 时，CLI 还会将已接受的随机数持久化到 <DB>.message-auth.db，使重放拒绝在重启后仍然生效；--db-key-file 会加密这两个存储。没有日志的已验证集线器会警告：除非提供 --message-auth-replay-db，否则其随机数缓存仅限当前进程。
• 已签名事件和可信对等端 — 嵌入式集线器可接受 Ed25519 事件签名，作为逐消息身份验证的替代方案；受保护的多集线器／联邦路径可将实时证书固定与经操作员确认的对等端策略结合使用。打包的集线器 CLI 不会加载 Ed25519 事件信任包。其 --multihub-serving-policy 配置会加载客户端 CA 并请求可选的客户端证书；策略会单独验证对等端身份。普通客户端无需证书即可连接。仅使用 --tls-certfile --tls-keyfile 配置的是服务器 TLS，而非要求客户端证书的 mTLS。
• 默认拒绝的 ACL — 使用 --acl-policy 并启用 --require-acl，可拒绝策略未授权身份发送的变更帧。
• 经过身份验证的防护证据 — 原生文件声明钩子拒绝的操作可通过单独进行令牌身份验证、仅包含摘要的 guard_denial 帧写入日志；开放式或无日志的集线器会拒绝此证据路径。
• 有界资源 — 连接、帧大小、JSON 深度、速率和历史记录上限可限制其配置的准入、保留和解析范围；但无法保证免受资源耗尽影响。
• 一键严格模式 — synapse hub --paranoid 可一次启用整套严格设置。

除线路层之外，还有多个子系统可加固静态数据和特权操作；每项功能均需选择启用并有文档说明：

• 静态数据加密（完整的双配置方案） —
  • SQLCipher — 可选地对实时 Hub 事件存储进行页面加密 （pip install 'synapse-channel[sqlcipher]'、synapse hub --db-key-file、 migrate/rekey-sqlcipher、doctor，以及使用相同密钥的分析读取器）。 完善了在 WAL 模式下保持数据库打开时的保护方案。参见 SQLCipher 实时事件存储的静态数据加密。
  • 整文件 AES-256-GCM 信封 — 通过 synapse encrypt-key 加密中继日志、A2A 状态、游标和 存档，并提供故障安全的配置检查、迁移/轮换密钥/备份/恢复，以及可选的口令短语 / PKCS#11 / TPM 2.0 密钥 封装（[encryption] extra）。参见 静态数据加密。
• 能力受限的工具沙箱 — synapse sandbox 在默认拒绝的能力清单下运行 WebAssembly 工具（文件系统、网络和资源授权均绑定到 模块内容摘要），拒绝主机路径解析后经过符号链接的预打开路径，并返回有界且可验证的运行回执。此功能为实验性功能，需安装可选的 [wasm] extra。参见 WASM 沙箱。
• 受治理的跨 Hub 中继 — 跨 Hub 强制释放必须说明理由；若为紧急破窗操作，则会加上标记；应用前还可要求两名不同的操作员（选择启用双人 审批）。持久化 Hub 重启后只会重建经过验证的待处理入站审批，绝不会重建审批结论。单人审批、待处理审批或正在完成法定人数的中继可以携带稳定的 --idem-key，使获授权的重试能够重放已提交的确切结论，而不会重复释放；该密钥也会绑定到已验证的联邦主体，且重放前仍会执行实时授权。
• 持久化自动操作启用策略 — Hub 可执行哪些自动操作由操作员明确管理的策略决定，并在重启后保留，而不是按会话设置默认值。

供应链也受到同样的门禁保护：对暂存变更运行 gitleaks 提交前钩子，并在 CI 中对完整代码树运行固定摘要的 gitleaks 全面扫描；采用哈希锁定的 CI 工具链（通过 uv 编译并使用 --generate-hashes，安装时使用 --require-hashes），GitHub Actions 固定到完整提交 SHA，Docker 基础映像固定到摘要；每次推送都会运行 pip-audit，并同时运行 CodeQL 和 OpenSSF Scorecard 工作流。 make install-hooks 还会安装仓库的 commit-msg 门禁：每个新提交都必须包含且仅包含一个供应商中立的 Seat: <seat-suffix> 尾注，以及完全匹配的项目署名行。专用工作流会审计每个新增提交，并每周重新检查完整的只增不改历史记录。主分支 CI 还会为每次推送的提交头分配独立的并发组，且绝不取消该任务；拉取请求和手动运行仍可在共享引用上替换过期任务。暂存 Python 文件或 pyproject.toml 时，也会通过仓库虚拟环境对完整代码树运行严格的 mypy 检查，而非仅检查变更文件名。SYNAPSE_MYPY_PYTHON=/absolute/path/to/python 可选择有意使用的替代环境；路径无效时会安全失败。 已安装的推送前阶段耗时仅需数秒：它会拒绝过期的能力快照、无效的提交尾注历史或版本表面不一致。它不会运行 pytest、覆盖率或穷尽式预检；这些检查由 CI 在每次推送时负责。 威胁模型以及漏洞报告方式见 SECURITY.md。

已知限制

• 单个中枢，单台机器。 没有内置故障转移或水平扩展能力；中枢是一个进程，设计刻意以本地优先。中枢重启后会从持久日志恢复，但它不是高可用集群。用于连接其他机器的联邦基础功能都包含在此软件包中；将其作为生产服务运行属于下文商业版 Fleet 层级的职责。
• 连接身份验证采用适度的共享密钥，而非密码学身份系统。启用 encryption extra 后，默认客户端会使用机器密钥对注册请求签名，中枢会在首次有效使用时固定名称；由运维人员管理的部署也可以改为要求已登记的身份包。逐消息身份验证、Ed25519 事件签名信任、对等证书固定和默认拒绝的 ACL 仍是彼此独立的可选项（参见安全态势）。每次联邦对等连接仍须通过带外方式决定是否信任：身份包字节可以通过网络传输（synapse federation offer/fetch，比较指纹，但绝不自动信任），但没有自动信任分发机制。不要将中枢暴露在不可信网络中，并仅依赖令牌进行保护。
• 优雅关闭有时间限制，并非事务性的。 SIGTERM/SIGINT 会停止接受新套接字，在 --shutdown-close-timeout 指定的时间内关闭活动的 WebSocket 会话，并依靠每次变更时的持久化机制保存中枢已接受的状态。
• 接管是本地恢复工具，而非身份验证。 中枢通过 --takeover-cooldown 限制重复接管的频率，并记录接管/冲突结果以及发送方、远程主机和关闭原因，但 Agent 仍被视为可信的本地进程。
• Agent 可信。 总线负责协调 Agent，但不会对其进行沙箱隔离。运维人员对 Agent 运行所在进程的信任程度，就是对该 Agent 的信任程度。
• 任务类别路由基于启发式规则。 分类器按请求长度和一组关键词对请求分类；请根据工作负载调整阈值。不会离线评测各层级模型的延迟（这需要实时模型服务）。
• 文件范围声明仅供参考，不代表可访问文件系统。 声明包含范围元数据，但不会授予对所列文件的访问权限。旧版路径采用字面上的文件/目录重叠判断，而配置的规范化范围和语义范围各自具有独立的标识与比较边界。普通相对路径会保持范围较窄；而 ../../etc/passwd 这类绝对路径或类似路径遍历的声明会扩大到整个工作树，以免声明范围过窄而漏掉冲突。这些声明不会授予文件系统访问权限。参见 SECURITY.md。
• 指标为可选功能，默认关闭。 synapse hub --metrics 会在中枢端口上开放 Prometheus /metrics 和 JSON /health 端点；若不指定此标志，中枢不会提供 HTTP 服务。该端点包含运维元数据，因此请将其绑定到回环地址，或在开放端点前要求提供 --metrics-token。默认令牌传递方式为请求头 Authorization: Bearer <token>。默认禁用查询字符串形式 ?token=<token>；只有使用已弃用的兼容标志 --metrics-query-token-ok 时才会接受此形式。解析时会显示警告，并将在 0.101.0 中移除，因为查询参数中的令牌很容易泄漏到日志和历史记录中。实时面板、状态和清单仍可通过 CLI 和 MCP 资源获取。
• 默认情况下，synapse --version 不会发起网络请求。 设置 SYNAPSE_UPDATE_CHECK=1 可选择启用尽力而为的 PyPI 新版本检查（24 小时内复用最近一次成功检查的缓存；失败或缓存过期时可能重试）。选择启用后，获取操作为同步执行，且可能使用过期的缓存通知。设置 SYNAPSE_NO_UPDATE_CHECK=1，即使已选择启用，也会停用此检查。

超越单台机器：SYNAPSE CHANNEL Fleet

开源核心包含所有联邦基础功能：多枢纽跟随器、声明转发、默认拒绝的联邦网关（采用 mTLS + Ed25519），以及线协议。SYNAPSE CHANNEL Fleet 是商业套件，可在多台机器之间将这些基础功能作为持久服务来运行。它是专有软件——依据 SYNAPSE 企业许可证，通过私有 wheel 分发给被许可方，绝不会发布到公共 PyPI——并基于该核心的精确固定版本构建，因此线协议兼容性和联邦逻辑仍保持开源，让所有对等端都能验证。

graph LR
    subgraph MA["Machine A"]
      HA["SynapseHub (OSS core)<br/>event log"]
      FD["synapse-fleet sync daemon<br/>persisted per-peer mirror<br/>fail-closed cursors"]
      OV["fleet status · doctor · observed<br/>advisory views from the mirror"]
      HA --- FD --> OV
    end
    subgraph MB["Machine B"]
      HB["SynapseHub (OSS core)"]
    end
    subgraph MC["Machine C"]
      HC["SynapseHub (OSS core)"]
    end
    FD -- "mTLS + Ed25519 pins<br/>deny-by-default, live trust generations" --> HB
    FD -- "budgeted polls<br/>backoff-isolated per peer" --> HC

Fleet 功能	作用
sync 守护进程	将跟随器循环作为持久服务运行：为每个对等端保存持久化镜像，可在重启后继续使用；通过页面数／新事件数／时间预算，让大型积压任务能够断点续作并实现部分成功；通过指数退避隔离，避免某个缓慢的对等端依次阻塞正常对等端；使用失败关闭游标——轮询失败绝不会推进镜像。
实时信任重载	将版本化的操作员信任架构组装为不可变的信任代；在变更后的代能够打开套接字之前，重建授权和固定 TLS；无效的实时更新会拒绝该次轮询，而不是回退到缓存的允许状态。
synapse-fleet CLI	独立的二进制文件：sync status 显示每个对等端的时钟偏差；只读联邦 doctor（可达性、RTT、游标延迟、镜像完整性、证书到期时间、吊销状态）；observed 从镜像离线呈现对等端的协调状态，并为每项声明标记 observed@<hub>（仅供参考，绝非本地权威）；federation 密钥／证书生命周期管理，遵循操作员排序的先添加新项、再吊销旧项的流程；以及严格的 journal verify／repair-cursor。仅有轮换流程并不能保证服务不中断。
ResilientClaimForwarder	一个库层，在核心声明转发接口周围添加重试、幂等性和指标，用于跨枢纽声明路由。

Fleet 不会更改本套件的任何功能，也不会移除任何功能；它只是在此基础上增加多机器运维层。有关许可，请参阅下文的商业用途，或联系 [email protected]。

商业用途

SYNAPSE CHANNEL 采用双重许可，开源构建版和商业构建版的功能完全相同：两者都使用公开的 Core 代码库。商业许可证改变的是条款，而不是代码。可选依赖项、平台支持和文档所述的运行时限制仍然适用。单独许可的 Fleet 套件是面向多机器运维的附加产品，基于此核心公开的联邦基础功能构建——此处没有任何内容被保留以便为它腾出空间。根据 AGPL，Core 许可证不收取按席位计费的费用；基础设施和外部提供商费用另计。付费层增加约定的权限、托管、支持和便利功能。

• 在遵守适用条件的前提下，根据 AGPL-3.0 使用，包括向远程用户提供修改版本的对应源代码，以及传播受许可作品时的源代码要求。商业、研究或内部用途等标签本身并不能决定适用哪些条件。

• 如果你的部署无法满足这些条件，请申请商业条款。仅托管使用并不要求开放整个软件栈；请查阅 LICENSE 和 COMMERCIAL-LICENSE.md，了解受许可作品和授权范围。

• 免费运行，而且觉得它对你有帮助？ 开发工作由我们独立进行并自行资助——欢迎请我们喝杯咖啡： ☕ 请我喝杯咖啡 · GitHub Sponsors · PayPal · TWINT (CH) — 也可以发送加密货币（与 anulum.li 上公布的地址相同）：

  币种	地址
  BTC	bc1qg48gdmrjrjumn6fqltvt0cf0w6nvs0wggy37zd
  ETH	0xd9b07F617bEff4aC9CAdC2a13Dd631B1980905FF
  LTC	ltc1q886tmvtlnj86kmg2urd8f5td3lmfh32xtpdrut

层级	适用对象	可获得的权益
社区版 — 免费（AGPL-3.0）	自托管、研究、个人和内部使用	公开的 Core 功能集；适用著佐权条款和已记录的运行时限制
组织许可证 — USD 490/年	仅需商业使用许可的单一法人实体	获准使用和嵌入本软件，无需遵守 AGPL 著佐权条款；不包含托管服务、仪表板、SLA、支持或 Fleet 权益
Pro — USD 19/月或 190/年	发布闭源产品或私有托管服务的单个开发者	为一名开发者提供商业许可、带推送功能的移动应用 (计划中)，以及电子邮件支持
Team — USD 39/用户/月或 390/用户/年	负责共享协调工作流的团队；至少 3 个席位	一个法人实体内的无限项目、托管仪表板 (计划中)（运营数据仍保留在本地）、安全补丁 SLA 和入门指导
FLEET Enterprise — 询价	受监管、多枢纽或多组织部署	单独授权的私有软件；联邦、SSO、审计导出、托管服务、合规支持和 SLA 范围需根据具体部署另行协商并进行资格评估

标记为 (计划中) 的项目目前尚不可用；它们不属于任何方案现阶段提供的权益。

SYNAPSE CHANNEL FLEET 是单独授权的私有软件，并非公共核心的隐藏商业构建版本。

当前方案和购买联系信息请见**商业信息页面**。如需企业、OEM、学术、非营利、托管或共同所有权条款，请发送邮件至 [email protected]，并提供 docs/commercial.md 中列出的评估详情。完整条款请见 COMMERCIAL-LICENSE.md。

如何引用

如果你在工作中使用 SYNAPSE CHANNEL，请引用它。元数据见 CITATION.cff；BibTeX 条目如下：

@software{sotek_synapse_channel,
  author  = {Šotek, Miroslav},
  title   = {SYNAPSE CHANNEL: Local-first multi-agent coordination bus},
  url      = {https://github.com/anulum/synapse-channel},
  doi      = {10.5281/zenodo.20801559},
  version = {0.99.38},
  year     = {2026}
}

显式建议型 Agent 排名

synapse reputation ./hub.db --json 根据保留的证据和源事件序列，提供可选择启用的人工分流顺序。默认信任图和执行防护措施保持不变。请参阅建议型 Agent 排名。

许可

双重许可：AGPL-3.0-or-later，并提供商业许可——计划详情请参阅 商业用途和 商业计划。LICENSE 包含完整的 AGPL 文本，COMMERCIAL-LICENSE.md 包含商业条款，而 NOTICE.md 说明许可边界。此仓库符合 REUSE 3.x 规范。

---

   

© 1998–2026 Miroslav Šotek · anulum.li · [email protected]

Git 声明超时意味着结果未知（退出码 3），并不能证明声明遭到拒绝。使用 --confirm-only，并提供原始身份和范围，以验证确切的有效租约，而不重放变更操作。声明恢复。