XYZZY 是一个面向团队协作场景的开源多智能体平台，核心目标是让多个人类与多个 AI 智能体在同一“房间”内共同工作，并保留完整的工作证据。
用途与定位 现代 AI 工具往往是“单人游戏”：一个人、一个对话、一个上下文。但真实工作发生在团队中。XYZZY 把协作作为一等公民，让多个参与者共享同一份事件历史、产物、任务和决策，并持久化到 SQLite，通过 WebSocket 驱动实时同步。智能体可以并行分支产出，由人类选择或排除结果，最终发布不可变的决策简报及其背后的证据链。
主要能力
- 持久化房间与事件溯源：每个操作都是有序事件，所有状态由事件历史驱动。
- 多智能体编排：支持生成、暂停、恢复、重定向智能体，以及在智能体之间委派任务。
- 人在回路：智能体的操作在执行前需要请求并等待人类批准或拒绝。
- 产物版本管理：可创建文档、代码等产物并维护版本。
- 文件附件：支持向消息上传图片，受 XYZZY_MAX_ATTACHMENT_BYTES 限制。
- 选择性综合：显式包含或排除智能体输出，发布不可变决策简报。
- 证据本体：类型化、可审查的 Decision → Claim → AgentOutput 关系。
- 有限元推理：权限感知的“为什么”与决策证据回答，支持精确下钻。
- 决策跟踪：记录与审计架构和产品决策。
- 共享记忆：房间级、工作空间级和组织级记忆。
- 实时协作与重连：WebSocket 广播所有房间事件；重连时提供完整状态快照加增量事件重放。
- 治理与可证明性：操作等待人类批准后才执行；房间事件日志采用哈希链，篡改或删除某行会破坏其后所有哈希，可通过 audit CLI 校验。决策链接到底层 Claims 和 AgentOutputs，综合结果可下钻到具体运行。
- 可选 NEXUS 集成：通过 NexusAgentBridge 将轻量智能体运行时 NEXUS 适配到多人上下文，提供 AgentExecutor、Budget、PolicyEngine、StateStore 等能力；设置 XYZZY_NEXUS_PATH 启用，未设置时桥接直接运行配置的模型提供商。
使用方式 本地运行需要 Python 3.11 或更高版本，数据库是文件，无需预先启动服务。macOS/Linux 与 Windows PowerShell 均有对应安装命令；也可用 Docker 运行演示工作空间。演示模式无需账号、无需配置，一键进入已处于决策中的工作空间：包含频道对话、含两个专家输出的分支供比较，以及一份证据链完整的已发布决策简报。演示未配置 API key 时，专家输出和简报会显示明显标注的“SIMULATED workflow output”，但协作机制相同。
配置方面，除 /api/v1/health 和若干凭据前 OIDC 端点外，所有 /api/v1 路由需要 Bearer token。凭据存储在数据库中并哈希保存，每 token 一行，可撤销而无需重启；operator CLI 可铸造和撤销凭据。可设置 XYZZY_LOCAL_MODEL_BASE_URL 将专家指向任意 OpenAI 兼容的 chat-completions 服务器（如 Ollama、LM Studio、vLLM、llama.cpp 服务器），该设置优先于 OPENAI_API_KEY。模型凭据不会从 API 请求接受、不会写入 SQLite，也不会包含在智能体输出中。
适用场景 适合团队需要与多个 AI 智能体共同做技术或产品决策、并希望保留可审计证据链的场景。也适合希望在本地或自有基础设施上运行、使用本地模型而非托管 API 的团队。
限制与注意事项
- 哈希链只能证明日志内部自洽，无法区分诚实历史与数据库文件持有者的整体重写。
- 事件日志仅追加，删除个人数据不能直接删行，需通过墓碑标记和内容替换实现。
- 默认单进程；扩展时需设置 XYZZY_REDIS_URL，且所有进程必须共享真实本地文件系统，不支持 NFS/SMB 等网络文件系统。
- 速率限制按进程计数，多副本部署需在负载均衡层分配预算。
- 当前仓库门禁为 1284 个测试（1283 通过，1 个在无 OPENAI_API_KEY 时跳过）加 Ruff 格式/检查与严格 mypy。
- 许可证为 Apache 2.0。
