watercooler

# 水冷器 Git 原生协作线程，适用于人类与 AI 协作编码团队。 [水冷器官网](https://watercoolerdev.com) 提供托管版本。 [](LICENSE) [](https://www.python.org/downloads/) [](https://modelcontextprotocol.io) [快速入门](#快速入门) • [文档](#文档) • [工作流示例](docs/WORKFLOW_EXAMPLES.md) • [工具参考](docs/TOOLS-REFERENCE.md) • [贡献](CONTRIBUTING.md) [](https://www.watercoolerdev.com) --- ## 什么是水冷器？ 水冷器是一个 MCP 服务器，带有 Git 支持的共享内存层，适用于代理编码团队 - 在代码旁边提供决策、推理和批评的持久记录。 > **Git 存储了更改内容。水冷器存储了更改的原因、考虑的因素、做出的决定和仍然不确定的内容。** 在代理进入协作过程之前，协作已经很困难。做好协作需要意图、注意力、判断力以及足够的共享上下文，以便人们可以一起评估权衡取舍。代理通过更快地生成代码、提案和部分解决方案，使这个问题变得更加困难，速度快于团队可以阅读、评估和理解它们的速度。 水冷器通过使工作的重要部分持久化来帮助团队：提案、权衡取舍、批评、理由、意图和决策。 人们决定将什么内容放在水冷器中。代理通常会进行编写。每个线程条目都是一个刻意的、由人类控制的上下文外部化 - 而不是会话噪音。一旦发布到水冷器中，该上下文就成为团队共享内存的一部分：版本控制、可搜索和可审查， 与代码一起。 **示例工作流：** ```diff Jay 使用 Codex: "让我们将新的团队权限模型放到水冷器中。" + Codex（jay，规划者）：发布提案和权衡取舍 -> 球被传递 Caleb 使用 Claude：读取线程，批评提案，建议修订 -> 确认 + Claude（caleb，批评者）：确认设计，发布决策 -> 创建 GitHub 问题 + Git：提案、批评、理由和决策与代码一起版本控制 ``` **您选择要外部化的内容。代理写入它。Git 使其持久化。** 水冷器不会被动地记录每个代理交互。您决定应该传达什么，代理会编写适当的构造线程操作，以便上下文、交接、决策和状态更改在 Git 中持久化，并可通过您的 MCP 客户端或 [水冷器仪表盘](https://www.watercoolerdev.com) 进行审查。这使得线程聚焦和有意图。 ### 核心概念 | 概念 | 它是什么 | |---|---| | 线程 | 与您的代码仓库绑定的命名对话通道。每个线程都有一个 `主题` 标识、状态和球。 | | 条目 | 通过显式写入操作（如 `say`、`ack` 或 `handoff`）发布到线程的单个消息。每个条目都有作者、角色、类型和时间戳。 | | 写入操作 | 显式变异操作：`say`（添加条目 + 翻转球）、`ack`（添加条目 + 默认保持球）、`handoff`（添加条目 + 显式传递球）、`set_status`（更新线程状态）。 | | 球 | 谁负责推动工作向前。球持有者拥有下一步行动 - 如果放下，线程就会停滞。`say` 将其传递给对手；`ack` 保持它；`handoff` 显式传递它。 | | 代理身份 | 谁是条目的作者。在团队中，使用 `Agent (person)` 命名，如 `Codex (jay)` 或 `Claude (caleb)`，以便多个使用相同客户端的用户保持可区分。 | | `主题` | 线程的标识符，如 `feature-auth`。用于所有工具调用；与显示标题不同。 | ### 水冷器的位置 水冷器是代码生命周期工件旁边的持久共享内存，用于推理、决策和批评。 <p align="center"> <img src="docs/images/watercooler-diagram.png" alt="水冷器图" width="600"> </p> ### 为什么是水冷器？ 随着 AI 加速代码生成，瓶颈从编写代码转移到理解代码 - 评估权衡取舍、做出决策和保持足够的共享上下文，以便团队能够协同工作。更快的输出而没有共享推理记录会导致返工、重复假设和较弱的批评循环。 水冷器通过使代码周围的思考持久化来解决这个问题：构思、提案、关键计划、理由和决策成为有组织的、线程化的 Git 记录。这样，团队就可以获得共享上下文，他们可以重新审视、查询和在此基础上构建，并有明确的记录，记录了提出了什么、决定了什么以及为什么。 --- ## 快速入门 ### 1. 身份验证 如果您的仓库托管在 GitHub 上： ```bash gh auth login gh auth setup-git ``` 如果您的仓库位于非 GitHub 远程（GitLab，Gitea，自托管服务器等），请跳过 `gh` 命令 - 水冷器只需要您将线程分支推送到的远程的凭据。请参阅 [AUTHENTICATION.md](docs/AUTHENTICATION.md)，了解 PAT、SSH 和环境变量设置。 > [水冷器开发网](https://watercoolerdev.com) 目前假设 GitHub 用于登录和仓库访问。核心 CLI 和 MCP 服务器适用于任何 Git 远程。 ### 2. 连接您的 MCP 客户端 请参阅 [MCP-CLIENTS.md](docs/MCP-CLIENTS.md)，了解 Claude Code、Codex 和 Cursor 的信息。`watercooler_health` 是连接后推荐的健全性检查，但它是可选的 - 您可以直接跳到发布第一个线程。 ### 3. 创建您的第一个线程 大多数协作者完全通过他们的 MCP 客户端工作： 1. **您：** “以 `feature-auth` 为主题创建一个线程，捕获计划并传递给审查。” 2. **代理：** 调用适当的写入工具（`watercooler_say`、`watercooler_ack`、`watercooler_handoff` 或 `watercooler_set_status`）并编写结构化的更新。 3. **另一个代理或队友：** 读取线程上下文并从当前球所有者/状态继续。 4. **您 + 代理：** 在工作进展过程中，将关键更新、决策和交接发布到线程。 --- ## 文档 **从这里开始。** 首次阅读时按此顺序： 1. **[QUICKSTART.md](docs/QUICKSTART.md)** - 10 分钟内完成第一个条目。 2. **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** - 线程存储位置、读取和写入的区别、分支范围。阅读一次；以下内容会引用它。 3. **[MCP-CLIENTS.md](docs/MCP-CLIENTS.md)** - Claude Code、Codex 和 Cursor 设置。 4. **[CONFIGURATION.md](docs/CONFIGURATION.md)** - 完整的配置和环境变量参考。 **然后，根据需要：** 5. **[WORKFLOW_EXAMPLES.md](docs/WORKFLOW_EXAMPLES.md)** - 单代理、多代理、团队和异步交接工作流的规范协作模式。 6. **[AUTHENTICATION.md](docs/AUTHENTICATION.md)** - GitHub CLI、PAT、环境变量和 SSH 设置。 7. **[TOOLS-REFERENCE.md](docs/TOOLS-REFERENCE.md)** - 每个 CLI 命令和 MCP 工具的统一参考，带有安全注释和示例。 8. **[DAEMONS.md](docs/DAEMONS.md)** - 可选后台工作器（线程审计员、同步守护程序、决策检测、决策提取）和查找确认工具。 9. **[FEDERATION.md](docs/FEDERATION.md)** - 从单个 MCP 服务器跨多个仓库搜索。 10. **[ROLES_CREATION.md](docs/ROLES_CREATION.md)** - 六个规范角色以及如何通过 `.watercooler/roles.toml` 添加自定义角色。 11. **[DASHBOARD.md](docs/DASHBOARD.md)** - 浏览器 UI 伴侣。 12. **[TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** - 设置流程图和常见问题及解决方法。 13. **[GLOSSARY.md](docs/GLOSSARY.md)** - 术语定义（球、孤立分支、工作树、查找、命名空间等）。 14. **[TRADEMARK_POLICY.md](docs/TRADEMARK_POLICY.md)** - 使用水冷器名称、徽标和品牌资产的规则。 --- ## 快速命令参考 | 命令 | 它做什么 | |---------|--------------| | `watercooler init-thread <topic>` | 创建新线程 | | `watercooler say <topic> --title "..." --body "..."` | 发布条目并翻转球 | | `watercooler ack <topic>` | 确认而不翻转球（默认行为） | | `watercooler list` | 列出所有线程 | | `watercooler config init` | 生成注释 `config.toml` | 有关带有所有标志的完整命令列表，请参阅 [TOOLS-REFERENCE.md](docs/TOOLS-REFERENCE.md)。 --- ## 对于 AI 代理 服务器公开了一个 `watercooler://instructions` MCP 资源，其中包含工作流指导、球机制和必需的参数格式。 --- ## 贡献 我们欢迎贡献！请参阅： - **[CONTRIBUTING.md](CONTRIBUTING.md)** - 指南和 DCO 要求 - **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** - 社区标准 - **[SECURITY.md](SECURITY.md)** - 安全策略 --- ## 许可证 水冷器核心在 [Apache-2.0](LICENSE) 下获得许可。请参阅 [NOTICE](NOTICE) 以获取归属详细信息。 "水冷器" 是 Mostly Harmless AI 的商标。请参阅 [TRADEMARK.md](TRADEMARK.md) 以获取使用指南。