TUT — 轮到你啦

English | 简体中文

多个编程智能体——不同模型、不同命令行工具——在同一项目中协作：上下文自动共享，工作流自动推进，人类仅在审批关卡介入。

TUT 是一个运行在本地机器上的多智能体协作系统。其核心是 Context Hub——一个作为智能体之间共享内存的本地 MCP 服务器（一个仅追加的任务日志）。任务状态通过一个纯函数从记录序列推导而来；Notifier 轮询状态变化，驱动设计→实现→评审→修订循环（手动或自动模式）；人类仅在审批点做出决策。

问题所在

传统协调多个智能体的方式是文件交接（传递 design.md / review.md）。这存在三个痛点：

• 上下文通过文件交接传递：交接文件只包含结论——推理过程和被放弃的备选方案丢失了。下一个智能体得到的是“是什么”，而非“为什么”

• 工作流由人工驱动：评审-修订循环通常需要 2-3 轮，每轮手动触发，每次都要重新调整提示词并重新简述上下文

• 工具之间相互隔离：智能体会话无法互相看见；没有统一的状态或编排入口

TUT 的答案：将流程记忆放入 Hub（写入永远不会因工作流规则被拒绝），将工作流状态变为日志的派生视图（从不存储，从不强制），并将“谁按启动按钮”变为两种模式选择——手动/自动。人类是工作流的关键关卡，而非路由器。

Related MCP server: kitty-hive

核心机制

• 仅追加记录：智能体通过 5 个 MCP 工具（create / publish / read / list / decide）向任务日志追加记录——设计、代码变更、评审、修订、备注、决策。记录从不删除；任何人从零开始都可以仅凭日志重建每个决策及其理由

• 派生状态：任务状态（进展到哪一步，轮到谁）不是存储的，也不是强制的——它是通过一个纯函数从记录序列计算出的视图。状态表之外的组合（例如在单人任务中发布评审）仍然会写入磁盘，但会设置 needs_attention，以便人类处理

• 审批关卡：一旦评审通过，派生状态变为 pending_approval，人类必须发布一条决策记录（批准/拒绝）才能继续。close 在任何状态下都有效——人类保留随时结束任务的权力

• 流程变体：创建任务时选择 --flow full|direct|solo——full 运行完整循环；direct 跳过设计阶段（仓库已有设计）；solo 对小型变更跳过评审——无评审但非无审批（直接进入审批关卡）

• 手动/自动推进：在手动模式（默认）下，当轮到某人时通知人类，由人类启动下一步；在自动模式下，Notifier 通过启动器直接启动下一个智能体（通过角色白名单实现分级信任），人类仅做决策调用

架构

┌─────────────────────────────── local machine ────────────────────────────────┐
│                                                                              │
│  coding agent ──MCP read/write──► Context Hub ──► storage (local JSON)       │
│       ▲                            (memory + state projection)               │
│       │ launch                          ▲                                    │
│  Agent Host ──state events──► Notifier ─┘                                    │
│  (signal source + launcher, pluggable)   │ reads derived state (GET /state)  │
│                                          │                                   │
└──────────────────────────────────────────┼───────────────────────────────────┘
                                           ▼ notifications
                                        Channel ──► human
     manual: the human starts the next one | auto: the Notifier starts it via the launcher

任务状态从记录序列中派生：

designing → implementing → reviewing ─┬─ pass       → pending_approval → human decide(approve) → approved → closed
                                       ├─ fail_code  → revising → revision → back to reviewing
                                       └─ fail_design → sent back to designing

快速开始

前置条件：Node.js ≥ 20，Herdr（智能体主机，提供智能体所在的终端窗格；通过 brew install herdr 安装，项目主页 https://github.com/herdrdev/herdr），以及至少一个编码智能体 CLI。平台：macOS / Linux 专属（启动器是 POSIX shell；Herdr 对 Windows 的支持仍在测试阶段）。

git clone https://github.com/ianf-ai/take-ur-turn.git
cd take-ur-turn
npm install
npm run build

构建输出是 dist/cli.js。使用 npm link 将 tut 命令添加到 PATH；如果不想链接，始终可以使用 node dist/cli.js <子命令>（以下简称为 tut）。

启动工作区（总开关，幂等——两个系统窗格：hub 窗格 + notify 窗格）：

tut up

启动任务（向架构师窗格发送一句话需求；然后轮询 tut list 直到任务出现）：

tut new "add a --url flag to the CLI's mode subcommand"

之后，智能体通过 MCP 工具从自己的窗格读写 Hub 来推进任务；tut status 显示概览，Notifier 在需要审批时通知您，您通过 tut decide <task_id> --decision approve --by <your-name> 做出决策。

Notifier 的侧边通道（即时阻塞警报、完成交叉检查）依赖于 Herdr 将每个窗格的智能体状态变化转发到 scripts/on-agent-event.sh——这是一次性的环境设置（Herdr 插件）；接线说明见 design/system-design.md 第 7.2 节。

智能体 CLI 接入（一次性设置）

Hub 通过 Streamable HTTP 在 http://127.0.0.1:3001/mcp 暴露其 MCP 工具（tut serve 启动后即可用；无状态，无需会话流）。为每个参与智能体 CLI 配置一次：

Codex CLI (~/.codex/config.toml)：

[mcp_servers.tut]
url = "http://127.0.0.1:3001/mcp"

其他支持 Streamable HTTP 的 MCP 客户端：指向同一 URL 即可。

配置完成后，智能体会看到 5 个工具：context.create / context.publish / context.read / context.list / context.decide。

不支持 MCP-over-HTTP 的 CLI：使用等效的 CLI 通道——tut create / publish / read / list / decide 子命令与 MCP 工具一一对应，因此智能体可以直接从 shell 调用它们（技能中的“每个角色的工具速查表”——MCP | CLI 映射——正是为这些 CLI 准备的；两个通道可以混合使用；在同一任务中，每个角色使用自己的通道完全兼容）。

无法配置 MCP 的环境（例如某些会话中的沙箱限制）：如上所述回退到 CLI 通道。

命令概览

运行 tut 不带参数会打印完整用法。此处直接引用原文：

tut serve [--port <n>] [--root <dir>]
tut notify [--url <u>] [--interval <s>] [--event-port <p>] [--stall-timeout <m>]
tut mode <manual|auto> [--url <u>]
tut start-next [<task_id>] [--url <u>] [--force]
tut create --title <t> --description <d> --creator <c> --role <r> [--flow <full|direct|solo>] [--cast <role=agent,...>] [--url <u>]
tut publish <task_id> --role <r> --content-type <t> --summary <s>
             (--body <text> | --payload-file <md>)
             [--verdict <pass|fail_code|fail_design>] [--commits <a,b>]
             [--ref-version <n>] [--expected-version <n>] [--agent <a>] [--model <m>] [--url <u>]
tut read <task_id> [--since-version <n>] [--json] [--url <u>]
tut list [--status <s>] [--json] [--url <u>]
tut decide <task_id> --decision <approve|reject|close> --by <b> [--reason <text>] [--url <u>]
tut new "<one-sentence requirement>" [--pane <label>]
tut assign <role> <agent>
tut up [--url <u>] [--dry-run]
tut ack <task_id> [--note <text>] [--url <u>]
tut status [--json] [--url <u>]

智能体侧的等效通道是 5 个 MCP 工具（context.create / context.publish / context.read / context.list / context.decide）；CLI 子命令与它们一一对应。

典型工作流

Architect publishes design
    ↓ derived: designing → implementing
Executor reads context → codes the implementation (runs tests) → publishes code_changes
    ↓ derived: implementing → reviewing
Reviewer reads context → reviews (each finding carries a closing condition) → publishes review
    ├─ pass        → pending_approval → human decide(approve) → approved
    └─ fail_code   → revising → Executor publishes revision → back to reviewing
(The Notifier polls state changes: in manual mode it notifies the human to start the next step; in auto mode it can advance automatically)

上图是默认流程 full。变体在创建任务时选择（创建时固定，持久化后不可更改）：

• direct：仓库已有设计，因此跳过设计阶段——任务从实施开始；评审和人类审批照常进行

• solo：小型变更跳过评审——代码变更直接派生出 pending_approval，等待人类批准/拒绝。无评审，但非无审批：批准仍然是人类的关卡

配置

三个配置层面，性质和位置各不相同：

① 项目运行时配置 — .context-hub/config.json（gitignore，每个项目一份）

控制 Hub 和 Notifier 的行为。更改在下一次轮询周期生效——无需重启：

② 工作区配置 — scripts/workspace.json（随仓库提供）

默认阵容：角色 → { label, agent }（窗格标签 + 占据该位置的智能体 CLI）。为没有显式分配角色的任务解析；使用 tut assign <role> <agent> 编辑。routes.json 作为旧格式回退保留。

③ 调用参数 — CLI 标志和环境变量

还有一项一次性环境设置：Herdr 事件连接插件（参见快速入门末尾的连接说明）。

开发

依赖项列于 package.json 中：运行时依赖为 @modelcontextprotocol/sdk + zod（zod 已显式声明，以便与 SDK 共享单个实例）；没有其他运行时依赖。

npm install        # install dependencies
npm test           # run tests (vitest)
npm run typecheck  # type-check
npm run build      # compile to dist/

各代理角色的行为指令位于 skills/ 中（架构师/执行者/审查者/主持人——行为模板，而非身份绑定：任何加载了模板的代理都可以执行该类型的工作）。

文档

• design/system-design.md — 系统设计（当前权威）：架构、状态推导规则、MCP 工具 schema、模块契约、技术选型

• design/context-design.md — 上下文设计：包含的内容（范围/记录类型/载荷信封与正文模板）以及管理方式

设计文档和技能当前为中文；代码、CLI 输出和提交惯例为英文。

故障排除与已知限制

故障排除：

• 代理报告看不到 context. 工具*：确保 tut serve 正在运行（curl http://127.0.0.1:3001/state 有响应则表示存活）；检查 CLI 的 MCP 配置是否指向了 /mcp 端点；某些 CLI 会话可能被沙盒隔离，无法访问 localhost 回环——此时可让该代理改用 CLI 通道（tut read / tut publish），行为完全等价

• 端口 3001 已被占用（EADDRINUSE）：使用 tut serve --port <n> 切换端口，并通过 --url 将其余命令指向新地址（tut up 的配置探测亦包含在内）

• npm i -g 后自定义阵容丢失：tut assign 会写入包内部的 scripts/workspace.json（位于 node_modules 内），升级时会重置——如需自定义阵容/布局，请克隆仓库并从本地安装

已知限制（设计权衡，非缺陷）：

• 代理的窗格为单一会话：当多个任务同时等待同一代理时，轮询提示会依次在同一会话中到达（串行执行，共享上下文）

• Notifier 以轮询粒度观察状态：轮询窗口内的中间状态无法被观察到（版本号可能出现跳跃）；重放记录是事实来源，任何中间状态均可从日志重建

• 在自动模式下，没有密码学方法可以验证决策记录“确实来自人类”——当前退路是通知审计加通过 by 字段追踪；更结构化的解决方案留待多机部署场景处理

鸣谢

代理托管由 Herdr 提供支持——需单独安装的运行时前提；本包不分发其代码。

许可证

Apache-2.0