puzzlebox

使用状态机协调代理

一个 MCP 服务器，它将 有限状态机 作为动态资源托管，客户端可以订阅这些资源，并在其状态更改时收到更新。

puzzlebox 解决了什么问题？

<details> <summary>协作和协调是相关但不同的问题。协作适用于非平凡但相对简单的任务。为了应对长期努力，puzzlebox 解决了协调问题。</summary>

团队需要协调

将多个代理引导到一个大目标比仅仅将请求分解为任务，将它们分配给可用的代理并 启用它们之间的协作 更难。

正如几个代理可以协作完成一个小项目一样，几个具有流程意识的代理团队需要在不同的项目阶段内运作，以应对长期努力。

考虑企业级软件开发流程：

• 一个大型软件项目通常会经历一个多步骤、偶尔回溯的路径，从构思到设计到构建到测试到文档到营销到生产。

• 不同的团队随着时间的推移专注于不同的方面，这些方面受到之前发生的事情的影响，并且着眼于根据经验教训不断改进的目标。

• 即使在一个阶段内，团队也可能会经历他们自己的阶段，例如敏捷冲刺。为冲刺确定一定数量的工作范围，团队处理他们的部分，并在冲刺结束时决定接下来要处理什么。它接受每个冲刺都可能改变未来发展的方向。这些周期也可以表示为谜题。

使用 puzzlebox，可以使代理团队的成员具有流程意识，但流程本身不受幻觉的影响。

场景：团队传递火炬

三个代理正在工作。他们共享的谜题的当前状态是“规范”。

• 代理 1 正在指定领域语言。
• 代理 2 正在定义项目范围。
• 代理 3 正在生成规范文档。
• 代理协作以完成最终规范文档。
• 规范完成后，代理 3 启动到“设计”状态的转换。
  • 首先，规范由出口守卫（即，LLM 采样）检查其完整性。
    • 如果发现问题，则取消状态转换，团队继续。
    • 如果可以接受，则状态更改为“设计”。
      • “规范”代理正在监视谜题，现在应该退出。
        • 它们的长（且昂贵）的上下文已被提炼成规范。
        • “设计”团队从这里开始，以规范作为资源，并且它们的上下文是新鲜的且特定于角色的。

</details>

什么是谜题？

<details>

<summary>谜题是一个有限状态机。只是更容易说、写和思考。</summary>

你可以对其采取行动的有状态事物

想象一下魔方谜题。它有 43 千万亿个状态，为了在它们之间转换，你可以通过旋转机构的相交平面来对其采取行动。

谜题的属性

• 有限数量的离散状态，例如“系列概念和基调”、“世界构建”、“弧线情节”、“剧集计划”、“情节线融合”、“剧集大纲”、“剧本写作”等。
• 每个状态可以有任意数量的动作（包括 0），这些动作会启动到另一个状态的转换。
• 有一个初始状态。
• 有一个当前状态，在对谜题执行操作后可能会有所不同。
• 转换可以被状态退出和进入守卫取消，例如，通过客户端采样请求咨询 LLM。

一个简单的例子

{
  "initialState": "LOBBY",
  "states": {
    "LOBBY": {
      "name": "LOBBY",
      "actions": {
        "START_GAME": { "name": "START_GAME", "targetState": "PLAYING" }
      }
    },
    "PLAYING":  {
      "name": "PLAYING",
      "actions": {
        "END_GAME": { "name": "END_GAME", "targetState": "GAME_OVER" }
      }
    },
    "GAME_OVER": {
      "name": "GAME_OVER",
      "actions": {
        "RESTART": { "name": "RESTART", "targetState": "PLAYING" }
      }
    }
  }
}

</details>

什么是 puzzlebox？

<details>

<summary>大多数 MCP 服务器与客户端具有一对一的关系。Puzzlebox 是不同的。</summary>

多个客户端共享动态资源

Puzzlebox 是一个 MCP 服务器 实现，它：

• 支持多个客户端连接，这些连接可以创建和监视共享的动态资源。
• 管理谜题实例
• 公开以下工具：
  • 添加谜题
  • 获取盒子中给定谜题的状态和可用操作的快照
  • 对盒子中的给定谜题执行触发状态转换的操作
• 将注册的谜题公开为资源
  • 客户端可以使用 Puzzle Snapshot 资源模板按 ID 获取资源
  • 资源 URI 是 puzzlebox:/puzzle/{puzzleId}
  • 客户端可以订阅/取消订阅单个资源 URI

它是如何工作的

1. 客户端连接到 puzzlebox SSE 服务器。
2. 客户端向服务器注册谜题。
3. 客户端可以订阅给定的谜题，以便在其状态更改时接收更新。
4. 客户端对谜题执行操作，这些操作可能会更改其状态和可用操作。
5. puzzlebox 服务器确保任何尝试的操作对于给定谜题的当前状态都是有效的。
6. 如果操作有效，则启动到目标状态的转换。
7. 在转换期间，可选的退出和进入守卫可能会向客户端发送采样请求，其结果可能会导致取消转换（想想利益相关者的验收测试）
8. 如果守卫通过，则状态转换完成。
9. 当客户端收到资源更新通知时，他们可以读取资源或使用 get_puzzle_snapshot 工具来获取当前状态和可用操作。
10. 客户端根据新状态更新其 UI。

</details>

MCP 工具

<details> <summary>这些函数公开给代理以管理谜题。</summary>

⚙️ add_puzzle

添加一个谜题（有限状态机）的新实例。

• 输入： 无
• 返回： 具有布尔值 success 和 puzzleId 的 JSON 对象

⚙️ get_puzzle_snapshot

获取谜题的快照（其当前状态和可用操作）。

• 输入： puzzleId
• 返回： 具有 currentState 和 availableActions 数组的 JSON 对象
• 注意： 不支持资源订阅的 MCP 客户端可以轮询此工具以监视状态更改。

⚙️ perform_action_on_puzzle

对谜题执行操作（尝试状态转换）。

• 输入： puzzleId 和 actionName
• 返回： 具有 currentState 和 availableActions 数组的 JSON 对象

⚙️ count_puzzles

获取注册谜题的计数

• 输入： 无
• 返回： 具有注册谜题的当前 count 的 JSON 对象

</details>

本地设置

<details> <summary> 在本地运行需要 <a href="https://nodejs.org/en/download" target="_blank">安装 Node 和 npm</a>。然后按照以下步骤操作... </summary>

安装依赖项

• cd /path/to/puzzlebox/
• npm install

构建

• npm run build
• 在 /dist/index.js 构建 MCP 服务器运行时

启动

• npm run start
• 在端口 :3001 上使用端点 /sse 启动基于 SSE 的/MCP 服务器
• 必须在运行 INSPECTOR 之前启动

检查器

• npm run inspector
• 运行 模型上下文协议检查器
• 检查器 UI 将在以下位置可用：http://localhost:5173
• 在检查器 UI 中：
  • 确保 传输类型 设置为 SSE
  • 确保 URL 设置为 http://localhost:3001/sse
  • 单击其 “连接” 按钮以连接到 puzzlebox 服务器。
    • 您应该看到绿灯 🟢 和 “已连接” 消息。
  • 单击其 列出工具 按钮

格式化

• npm run format
• 在代码上运行 prettier，调整格式

类型检查

• npm run typecheck
• 运行带有参数的 tsc 以检查和报告类型问题

代码检查

• npm run lint
• 运行 eslint 以非破坏性地检查和报告语法问题

代码检查修复

• npm run lint:fix
• 运行 eslint 以检查和修复语法问题

测试

• npm run test
• 运行单元测试

</details>

截图

<details><summary>这些屏幕截图显示了服务器实现的各种 MCP 工具和资源。</summary>

服务器的测试是使用官方参考客户端 - MCP 检查器 完成的。

0 - 列出工具

1 - 添加谜题

2 - 获取谜题快照（初始状态）

3 - 对谜题执行操作

4 - 获取谜题快照（新状态）

5 - 对谜题执行操作

6 - 获取谜题快照（另一个新状态）

7 - 列出资源

8 - 资源模板

9 - 未订阅的资源

10 - 订阅的资源

11 - 资源更新通知

</details>