agentrelay

中继 ## 一个项目，多智能体，无**让AI在另一个AI停止的地方继续。** 它、任务租约、建议的文件所有权、决策尝试、Git状态和交接，以便Codex、Claude体可以在不需要从头重建上下文的情况下继续彼此的工作内置的tmux传输还允许这些智能体读取和消息的窗格，而无需安装第二个MCP服务器。 聊天记忆。 一个用于编码智能体的本地协调层。 .4.0版本功能 - 在存储库或内使用本地SQLite存储 - 使用子存储库Git上下文工作区边界 - 具有十个协调工具实时终端工具的MCP服务器 - 内置tmux传输，无需`tmux-bridge-mcp`运行时依赖 -窗格标签和防止的单会话tmux 经过编辑、大小限制的终端读取和单行 - 持久化读取前发送保护和无内容终端审计- 智能体心跳 - 过租约 - 具有重叠警告的建议文件和符声明 - 结构化开发事件和架构决策 - 潜在的决策冲突检测 - 跨事件、决策的FTS5搜索 - 标记预算上下文包 - 确定性Git感知Markdown交接 - 适用于没有生命周期钩子的 机密编辑和敏感路径过滤 - 无需外部模型或托管服务 ## 工作流程 智能体A加入 -> 声明任务和文件范围 -> 记录决策、 -> 创建Git感知交接并释放租约 智能体 -> 构建任务特定上下文包 之前的尝试、决策、任务和文件声明 -> 从验证的项目状态开始 ``` ## 安装 尚未发布到 npm。 将当前 GitHub 仓库安装自包含的 CLI 和 MCP 服务器： ```bash -g github:arumwu/agentagentrelay --version ``` 或者，从源代码检出进行安装： ```git clone https://github.com/arumwu/agentrelay.git relay npm install npm run build npm link ``` 需要 Node.js 22.13 或更高版本。协调和内存功能无需 tmux；实时终端工具还要求 tmux 3.2 或更高版本。 ## 快速开始 在 Git 运行这些命令，或使用 `--repo /absolute/path` 将 固定到更大的工作区，然后执行子命令。 ```agentrelay --repo /workspaces/company init agentrelay --workspaces/company join \ --agent codex-01 --type codex \ --cwd products/api \ "实现OAuth回调" ``` `join` 命令返回一个会话UUID。使用它进行声明和事件记录： ```bash agentrelay claim-task \ --session SESSION_UUID \ --title "实现OAuth回调" \ --description "验证回调并交换令牌" agentrelay claim-scope \ --session SESSION_UUID \ --pattern "src/auth/**" agentrelay event \ --session SESSION_UUID \ --type attempt \ --summary "服务账户方法失败" \ --content "普通用户OAuth需要授权码流" agentrelay context "完成OAuth刷新流程" --cwd products/api --budget 5000relay handoff \ --session SESSION_UUID \ title "OAuth实现交接" ``` ## 连接 在 Codex实际 Git 仓库中配置 AgentRelay。在该目录下创建 `..toml`：toml [mcp_servers.agentrelay] command = "agentrelay" args = [ "--repo", "/absolute/path/to/your/workspace", "serve" ] ``` 不要使用全局用户`codex mcp add`，除非您故意希望每个Codex会话都启动AgentRelay。 Codex根目录停止项目配置发现，因此仅在父多项目工作区中放置`.codex/config.toml`继承，当Codex嵌套仓库内。 为应该参与的每个实际仓库添加项目仍然可以指向同一个AgentRelay工作区边界。 ## 连接 Claude Code 在每个实际仓库中运行此命令，并使用本地作用域，以免不相关的Claude Code会话启动AgentRelay： ```bash claude mcp add --scope local agentrelay -- \ agentrelay \ --repo /absolute/path/to/your/workspace \ serve ``` AgentRelay通过MCP初始化宣传其生命周期指令。对于不使用服务器指令的客户端，请在存储库的`AGENTS.md`或`CLAUDE.md`中放置[`examples/AGENTS.md`](examples/AGENTS.md)中的备用规则。 ## 实时tmux传输 AgentRelay直接包含终端传输。安装`@arumwu/agentrelay`或GitHub软件包就足够了；无需安装或注册单独的`tmux-bridge-mcp`服务器。 在单个tmux会话中运行的智能体。当AgentRelay在tmux中启动时，它会自动将终端访问限制到当前会话： ```bash agentrelay terminal list agentrelay terminal name %3 codex agentrelay terminal read codex --lines 40 agentrelay terminal send codex "检查src/auth报告任何回归" ``` `terminal read`为该演员和窗格打开一个90秒的一次性保护。在发送一次消息后，请再次格，然后再发送另一条消息。 AgentRelay存储审计元数据，例如窗格、字节数和关联ID，但绝不保留捕获的终端输出或消息内容。 如果AgentRelay在tmux外部启动，请显式允许一个会话： ```bash agentrelay terminal --tmux-session agent-work list ``` 对于在tmux外部启动的MCP客户端，请在该服务器的环境中设置`AGENTRELAY_TMUX_SESSION`。仅在使用非默认套接字时设置`AGENTRELAY_TMUX_SOCKET`。 所选会话以外的终端目标将被拒绝。 `terminal_send`类型为一行文字消息，接着是一个换行符。 shell窗格可以将该文本解释为命令，因此请仅标记和定位您信任的窗格。 AgentRelay故意不公开任意按键或通用shell执行工具。 ## 工作区模式 一个工作区可能包含多个独立的Git仓库和非Git项目： ```text /workspaces/company/ <- 固定的AgentRelay边界 ├── .agentrelay/ <- 共享工作区内存 ├── products/api/.git/ ├── products/web/.git/ └── research-notes/ ``` MCP服务器固定在 `/workspaces/company`。 每个 `agent_join` 和 `build_context` 调用都可能包含 `working_directory`，例如 `products/api`。 AgentRelay 拒绝固定工作区以外的目录，并从包含该工作目录的子仓库中获取 Git 状态。 任务和范围声明在工作区范围内。 在上面的示例中，请声明 `products/api/src/**` 而不是仅 `src/**`，以避免子项目之间的歧义。 ## MCP 工具 | 工具 | 用途 | |---|---| | `project_init` | 初始化或检查工作区本地存储及其固定边界 | | `agent_join` | 注册智能体会话及其当前工作区目录 | | `agent_status` | 读取协调状态并可选地心跳会话 | | `claim_task` | 创建或声明过期任务租约 | | `claim_scope` | 声明工作区相对文件或通配符并接收重叠警告 | | `record_event` | 记录尝试、结果、问题、发现、测试、注释或完成 | | `record_decision` | 记录结构化决策并识别潜在冲突 | | `search_memory` | 使用SQLite FTS5搜索事件、决策和交接 | build_context` | 编译任务特定的Git、协调上下文 | | `create` | 生成Markdown交可选地释放租约 | | `terminal_list`出仅在允许的tmux会话中的窗格 `terminal_read` | 读取编辑、限额窗格一次性发送保护 `terminal_send` |文字消息，并在最近读取后发送Enter | | `` | 分配AgentRelay特定的窗格标签 | terminal_doctor` | 诊断tmux二进制、字、会话和安全限制 | ## 本地数据 每个协调的仓库或工作拥有自己的内存： .agentrelay/ relay.db ├── events.jsonl └── handoffs/ └── 2026-...-handoff.md ``` `.agentrelay/` 默认情况下被排除在此存储库的 Git 历史记录之外。 在非 Git 工作区中，它仍然是一个隐藏的本地目录。 团队可以选择对其编辑的交接导出进行版本控制，但数据库通常应保持本地。 现有安装将在自动迁移到relay/agentrelay 存储布局。 ##语义 任务租约在活动期间是独占 如果第二个智能体请求相同的任务，AgentRelay 将所有者和过期时间的范围声明是建议性的文件或通配符模式可能重叠时， 会发出警告，但它并不假装可以防止智能体 之外的文件。 智能体和钩子视为协调停止。 决策冲突也是建议性的。 AgentRelay 根据任务、标题和范围重叠标记相关的活动人类或智能体必须显式覆盖旧决策。 边界 - 工作区根服务器启动时解析一次。 - 智能目录必须存在于该固定工作区内。 -工具无法逃逸到另一个工作区路径。 - AgentRelay 不公开通用 shell、测试命令工具。 - 终端访问仅当前或显式配置的 tmux 会话。 终端发送需要最近的读取，拒绝自我定位，并文字。 - 经过编辑，大小有限；捕获的输出和消息文本不会被保留。 - shell 窗格仍可能执行文本，因此终端访问于受信任的窗格。 - Git 检视使用固定参数数组，无需 shell。 - `.env`类似凭证的路径被过滤。 - 常见的密钥、令牌、cookie 和承载标头在存储前会被编辑。 详见 [SECURITY.md](SECURITY.md) 了解报告和威胁模型详情。 ## 开发 ```bash npm install npm run check集成测试创建临时 Git 仓库，并测试任务冲突、范围重叠、内存搜索、决策冲突、交接生成和真正的内存 MCP 客户端/服务器握手。了 tmux 时，它们还会创建一个隔离的套接验证真正的窗格列表、标签、读取前发送消息传递、自目标拒绝和跨会话隔离。 CI 始终安装 tmux 并运行此路径。 ## 路线图 - 用于自动生命周期捕获的智能体特定 - Git 提交/适配器 - 任务完成和阻塞状态命令 - 可选的语义检索和重排序 - 便携式编辑导出和仓库同步 - GitHub 问题和拉取请求预测 - 一个小型协调仪表板 ## 许可证 AgentRelay 遵循 Apache License 2.0 许可。 参见 [LICENSE](LICENSE)。 内置终端传输包含适用于MIT声明的`tmux-bridge-mcp`的改 参见 [THIRD_PARTY_NOTICESTHIRD_PARTY_NOTICES.md) 和 [LICENSEmux-bridge-mcp-MIT.txt](LICENSESbridge-mcp-MIT.txt)。