使用说明
pypddlengine
Python PDDL引擎和 MCP（模型上下文协议） 该服务器使AI代理能够交互式地探索PDDL规划问题。
特性
- 独立PDDL发动机 --解析、验证和执行PDDL域和问题
- 交互式计划探索 --逐步执行计划，查询可执行的操作，检查世界状态
- MCP服务器 --将引擎作为工具暴露给任何兼容MCP的AI代理（Claude Desktop、VS Code等）
- Python API --使用结构化JSON响应进行直接编程访问
- 会话日志记录 --将代理交互记录到CSV/JSON进行分析
支持的PDDL功能
| 功能 | 要求 | 注意事项 |
|---|---|---|
| 条状物 | :strips |
基本行动、积极/消极先决条件和影响 |
| 打字 | :typing |
类型化对象/参数、类型层次结构 |
| 平等 | :equality |
(= ?x ?y) 在前提条件下 |
| 负面先决条件 | :negative-preconditions |
(not ...) 前提条件和目标 |
| 否定前提条件 | :disjunctive-preconditions |
(or ...) 在前提条件下 |
| 存在的先决条件 | :existential-preconditions |
(exists (?x - type) ...) |
| 普遍先决条件 | :universal-preconditions |
(forall (?x - type) ...) 在前提条件下 |
| 条件效应 | :conditional-effects |
(when ...) 和 (forall ... effect) |
| 含义 | :adl |
(imply ...) 在前提条件下 |
| 数字分数 | :numeric-fluents |
increase, decrease, assign, scale-up, scale-down |
| 行动成本/指标 | :action-costs |
(total-cost) 随着 (:metric minimize ...) |
| 常量 | -- | :constants 在域中 |
不支持的PDDL功能
| 功能 | 备注 |
|---|---|
持续行动(:durative-actions) |
用描述性消息引发显式错误 |
派生谓词(:derived) |
未解析；将在负载下失效 |
| 最大化指标 | 仅 minimize 支持 |
| 条件中的算术 | 数值表达式，如 (+ ?x ?y) 不支持先决条件 |
安装
git clone https://github.com/kgoe-ait/pypddlengine
cd pypddlengine
uv sync
或者从PyPI安装（发布后）：
pip install pypddlengine
用法
Python API-模拟器
from pypddlengine.engine import Simulator
sim = Simulator(domain_str, problem_str, plan_str)
sim.step_all()
print(sim.is_goal_reached())
手动完成步骤：
sim = Simulator(domain_str, problem_str)
sim.step(("move", ("loc1", "loc2")))
print(sim.get_executable_actions())
print(sim.is_goal_reached())
Python API-探索API
具有结构化JSON响应的高级API，专为AI代理工具使用而设计：
from pypddlengine.api import PDDLExplorationAPI
api = PDDLExplorationAPI(domain_str, problem_str)
actions = api.get_available_actions() # {"count": 4, "actions": [...]}
result = api.execute_action("move", ("a", "b")) # {"success": true, ...}
api.is_goal_reached() # {"goal_reached": false, ...}
api.reset()
会话记录器
将探索API打包，并将每次交互记录到CSV/JSON：
from pypddlengine.session_logger import PDDLSessionLogger
session = PDDLSessionLogger(domain_str, problem_str, session_id="experiment_1")
session.execute_action("move", ["loc1", "loc2"])
session.export_to_csv("session.csv")
session.export_to_json("session.json")
session.print_summary()
MCP服务器（克劳德桌面）
添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：
{
"mcpServers": {
"pddl-engine": {
"command": "uv",
"args": ["run", "python", "-m", "pypddlengine.server"],
"cwd": "/path/to/pypddlengine"
}
}
}
MCP服务器（VS代码）
已在中配置 .vscode/mcp.json --打开此项目时，它可以开箱即用。
MCP工具
一旦连接，AI代理就可以使用这些工具：
| 工具 | 说明 |
|---|---|
pddl_init |
使用域和问题PDDL字符串初始化会话 |
pddl_init_from_files |
从域和问题文件路径初始化会话 |
pddl_get_available_actions |
获取当前状态下的所有可执行操作 |
pddl_execute_action |
按名称和参数执行操作 |
pddl_get_current_state |
查看所有真实谓词和符 |
pddl_is_goal_reached |
检查是否满足目标条件 |
pddl_reset |
重置为初始状态 |
pddl_get_action_history |
审查迄今采取的行动 |
pddl_get_domain |
重新阅读PDDL域定义 |
pddl_get_problem |
重新阅读PDDL问题定义 |
运行测试
uv run pytest
项目结构
pypddlengine/
├── server.py # MCP server
├── api.py # Exploration API (structured JSON responses)
├── session_logger.py # Session logging wrapper
└── engine/ # Core PDDL engine
├── simulator.py # Plan simulation
├── parser/ # PDDL lexer & parser
├── interpreter/ # Domain/problem interpretation
└── execution/ # State management & action execution
许可证
Apache 2.0——请参阅 许可证.
