迷箱
将代理与状态机协调
功能路线图和状态
A work in progress. Much is done, a few bits remain to be done.
- \[x\] 工具代码的单元测试
- \[x\] MCP服务器的集成测试（SSE和StreamableHttp）
- \[x\] SSE运输
- \[x\] 流式Http传输
- \[x\] 多个同时进行的客户端连接（两种传输方式）
- \[x\] 创建谜题（状态机）作为动态资源
- \[x\] 订阅谜题
- \[x\] 谜题更改时接收更新通知
- \[x\] 获取拼图快照（当前状态和可用操作）
- \[x\] 通过在拼图上执行动作来更改拼图状态
- \[\]按谜题状态创建资源（由代理和守卫提示使用）
- \[\]创建过渡保护提示（按状态使用资源）
- \[\]通过取样进行过渡保护
- \[\]命令行REPL
- \[\]通过REPL演示
puzzlebox解决了什么问题？
Collaboration and coordination are related but different problems. Collaboration is good for non-trivial yet relatively simple tasks. To tackle long horizon efforts, puzzlebox solves for coordination.
团队需要协调
将多个代理编组到一个大目标上比将请求分解为任务、将它们分配给可用代理和 促进协作 他们之间。
正如少数代理可以协作完成一个小项目一样，几个具有流程意识的代理团队需要在不同的项目阶段进行操作，以处理长期工作。
考虑企业级软件开发过程：
- 大型软件项目通常会经历一个多步骤的过程，偶尔会回溯从开始到设计、构建、测试、文档、营销到生产的过程。
- 随着时间的推移，不同的团队专注于不同的方面，了解过去的情况，并着眼于根据经验教训不断完善的不断变化的目标。
- 即使在一个阶段内，团队也可能在自己的阶段中循环，比如敏捷冲刺。一定量的工作是为冲刺确定的，团队各司其职，在冲刺结束时，他们决定下一步要处理什么。它承认每一次冲刺都可能改变未来的发展进程。这些循环也可以表示为谜题。
有了puzzlebox，代理团队的成员可以意识到过程，但过程本身不会产生幻觉。
场景：传递火炬的团队
三名特工正在工作。他们共同谜题的当前状态是“规范”。
- 代理1正在指定域语言。
- 代理2正在定义项目范围。
- 代理3正在生成规范文件。
- 代理协作以达成最终规范文件。
- 一旦规范完成，代理3将启动向“设计”状态的转换。
- 首先，通过出口防护（即LLM采样）检查规范的完整性。 - 如果发现问题，状态转换将被取消，团队将继续。 - 如果可以接受，状态将更改为“设计”。 - “规范”代理正在监控这个谜题，现在应该下班了。 - 它们漫长（且昂贵）的上下文已被提炼到规范中。 - “设计”团队从这里开始选择，将规范作为资源，其上下文新鲜且特定于角色。
什么是谜题？
A puzzle is a finite state machine. It's just easier to say, write, and think about.
一个你可以采取行动的有状态的东西
想象一下魔方谜题。它有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" }
}
}
}
}什么是益智箱？
Most MCP servers have a one-to-one relationship with the client. Puzzlebox is different.
许多客户共享动态资源
Puzzlebox是一个 MCP服务器 实施：
- 支持多个客户端连接，可以创建和监视共享的动态资源。
- 管理谜题实例
- 展示以下工具：
- 添加谜题 - 获取框中给定谜题的状态和可用操作的快照 - 对框中的给定谜题执行触发状态转换的操作
- 将已注册的谜题作为资源公开
- 客户可以使用 Puzzle Snapshot 按ID获取资源的资源模板 - 资源URI为 puzzlebox:/puzzle/{puzzleId} - 客户端可以订阅/取消订阅单个资源URI
运作原理
- 客户端连接到益智箱SSE服务器。
- 客户端向服务器注册谜题。
- 客户端可以订阅给定的谜题，以便在其状态发生变化时接收更新。
- 客户端对谜题执行操作，这些操作可能会改变其状态和可用操作。
- puzzlebox服务器确保任何尝试的操作对于给定谜题的当前状态都是有效的。
- 如果操作有效，则启动向目标状态的转换。
- 在过渡期间，可选的出入防护人员可能会向客户发送采样请求，其结果可能会导致过渡取消（想想利益相关者的验收测试）
- 如果警卫通过，则状态转换完成。
- 当客户端收到资源更新通知时，他们可以读取资源或使用
get_puzzle_snapshot获取当前状态和可用操作的工具。 - 客户端根据新状态更新其UI。
MCP工具
These functions are exposed to the agents for managing puzzles.
⚙️ add_puzzle
添加谜题的新实例（有限状态机）。
- 输入： 无
- 退货： 带布尔值的JSON对象
success和puzzleId
⚙️ get_puzzle_snapshot
获取拼图的快照（其当前状态和可用操作）。
- 输入：
puzzleId - 退货： JSON对象
currentState和availableActions数组 - 注： 不支持资源订阅的MCP客户端可以轮询此工具以观察状态变化。
⚙️ perform_action_on_puzzle
在拼图上执行一个动作（尝试状态转换）。
- 输入：
puzzleId和actionName - 退货： JSON对象
currentState和availableActions数组
⚙️ count_puzzles
获取已注册谜题的数量
- 输入： 无
- 退货： 当前JSON对象
count已注册的谜题
本地设置
Running locally requires Node and npm be installed. Then follow these steps...
再进行
cd /path/to/puzzlebox/npm install
构建
npm run build- 在以下位置构建MCP服务器运行时
/dist/index.js
开始
npm run start- 在端口上启动基于SSE/MCP的服务器
:3001带端点/sse - 必须在运行检查器之前启动
检查员
npm run inspector- 运行 模型上下文协议检查器
- Inspector UI将在以下位置提供：http://localhost:5173
- 在检查器UI中：
- 确保 Transport Type 设置为 SSE - 确保 URL 设置为http://localhost:3001/sse - 点击其 “连接” 按钮连接到益智箱服务器。 - 你应该看到绿灯了🟢和 “已连接” 消息。 - 点击其 列出工具 按钮
格式
npm run format- 跑
prettier在代码上，调整格式
类型检查
npm run typecheck- 跑
tsc使用args检查和报告类型问题
棉绒
npm run lint- 跑
eslint非破坏性地检查和报告语法问题
LintFix
npm run lint:fix- 跑
eslint检查并修复语法问题
测试
npm run test- 运行单元测试
截图
These screenshots show the various MCP tools and resources implemented by the sever.
服务器的测试是使用官方参考客户端完成的- MCP检查员.