星战科技xingzhan.cloud
返回市场
拼图盒

拼图盒

作者：cliffhall24 星标更新：2025-08-25
安装使用来源：spider==github.com

项目介绍

puzzlebox

puzzlebox

使用状态机协调代理

一个MCP服务器，托管作为动态资源的状态机，客户端可以订阅这些状态机并在其状态变化时接收更新。

功能路线图和状态

<details> <summary>正在进行的工作。很多已经完成，还有一些待完成。</summary>
  • 工具代码单元测试
  • MCP服务器集成测试（包括SSE和StreamableHttp）
  • SSE传输
  • StreamableHttp传输
  • 多个同时客户端连接（两种传输方式）
  • 创建谜题（状态机）作为动态资源
  • 订阅谜题
  • 当谜题改变时接收更新通知
  • 获取谜题快照（当前状态和可用操作）
  • 通过执行操作来改变谜题状态
  • 根据谜题状态创建资源（用于代理和守卫提示）
  • 创建过渡守卫提示（根据状态使用资源）
  • 通过采样进行过渡守卫
  • 命令行REPL
  • 通过REPL演示
</details>

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/MCP的服务器，端点为/sse
  • 必须在运行INSPECTOR之前启动

Inspector

格式化

  • 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 Inspector。

0 - 列出工具

0. 列出工具

1 - 添加谜题

1. 添加谜题

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

2. 获取谜题快照

3 - 对谜题执行操作

3. 对谜题执行操作

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

4. 获取谜题快照

5 - 对谜题执行操作

5. 对谜题执行操作

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

6. 获取谜题快照

7 - 列出资源

7. 列出资源

8 - 资源模板

8. 资源模板

9 - 未订阅资源

9. 未订阅资源

10 - 订阅资源

10. 订阅资源

11 - 资源更新通知

11. 订阅资源更新

</details>