#moonpddl

$ moon run --target native cmd/moonpddl -- solve \
    examples/blocksworld/domain.pddl examples/blocksworld/problem.pddl \
    -s astar -H hmax
; moonpddl: solved
; cost = 4
; expanded = 6, generated = 11
; heuristic = hmax, search = astar
(pick-up b)
(stack b c)
(pick-up a)
(stack a b)

#为什么是 PDDL

• 带类型层次与量词的一阶逻辑公式编译；
• 条件效果、负前提、析取目标下的接地语义；
• 数值 fluent（函数）在前提、目标与效果中的完整求值；
• 可采纳的删除松弛启发式与前向状态空间搜索；
• 与求解器解耦、可定位到源码行的计划验证。

#符合性终点：PDDL 2.1 Level 1 完整支持

#功能特性

• 完整前端：词法分析、S 表达式解析、带行列位置的 PDDL 解析；语法错误与 不支持构造均返回结构化 PddlError，不使用全局状态或静默降级。
• 类型化接地：类型层次（含 either 多继承）、域常量与问题对象合并、参数 类型检查、量词展开、公式 DNF 编译、条件效果因式分解、数值表达式编译， 并限制 DNF 与接地动作规模。
• 可达性剪枝：接地后用删除松弛正向可达性剔除"前提永远无法满足"的接地 动作（过近似，保证不丢失任何可用动作）。
• 五种启发式：blind、goal-count、hmax、hadd、hff。其中 hmax 基于删除松弛，在非负动作代价下可采纳；数值约束在松弛中被丢弃，因此 可采纳性对真实任务依然成立。
• 三种搜索策略：GBFS、A*、加权 A*（WA*）。二叉堆开放表、best-g 去重、A* 更优路径重开、可配置扩展/生成上限；数值 fluent 值参与状态去重。
• 独立验证器：不依赖搜索轨迹，重新解析计划文本并逐步执行；报告未知动作、 错误参数、不可应用步骤（含未满足的数值前提）、未达成目标，以及 ; cost = N 标注不一致（判为无效）。
• CLI 与 JSON：solve / validate / check / ground 四个子命令， 稳定退出码与机器可读输出，适合脚本与 CI 集成。
• 可复现工程：五个可运行示例、91 个单元/集成测试、跨 wasm 与 native 目标验证、可选的性能基准。

#快速开始

moon add sa2360/pddl

# 静态检查与测试（默认 wasm 目标）
moon check
moon test

# 同时验证 native 后端
moon test --target native

# 构建原生 CLI
moon build --target native cmd/moonpddl

moon run --target native cmd/moonpddl -- version
moon run --target native cmd/moonpddl -- check \
  examples/blocksworld/domain.pddl examples/blocksworld/problem.pddl

#命令行用法

moonpddl solve <domain.pddl> <problem.pddl> [options]
moonpddl validate <domain.pddl> <problem.pddl> <plan.txt> [--json]
moonpddl check <domain.pddl> <problem.pddl> [--json]
moonpddl ground <domain.pddl> <problem.pddl> [--json]
moonpddl version

#求解

moon run --target native cmd/moonpddl -- solve \
  examples/delivery-numeric/domain.pddl examples/delivery-numeric/problem.pddl \
  -s astar -H hmax

; moonpddl: solved
; cost = 34
; expanded = 6, generated = 12
; heuristic = hmax, search = astar
(drive t1 a b)
(refuel t1 b)
(drive t1 b c)

{"status":"solved","cost":34,"steps":3,"expanded":6,"generated":12,
 "heuristic":"hmax","search":"astar",
 "plan":["(drive t1 a b)","(refuel t1 b)","(drive t1 b c)"]}

#验证

moon run --target native cmd/moonpddl -- validate \
  examples/logistics/domain.pddl examples/logistics/problem.pddl \
  examples/logistics/plan.pddl
# plan valid: 9 step(s), cost 9

{"valid":true,"steps":9,"executed":9,"cost":9,"declared_cost":9,"issues":[]}

#查看模型与接地结果

moon run --target native cmd/moonpddl -- check \
  examples/delivery-numeric/domain.pddl examples/delivery-numeric/problem.pddl

model ok
  domain: delivery-numeric
  problem: delivery-1
  objects: 4
  atoms: 6
  fluents: 11
  actions: 12
  goal disjuncts: 1
  initial cost: 0
  cost mode: total-cost

#库 API

let domain = @pddl.parse_domain(domain_source)
let problem_ast = @pddl.parse_problem(problem_source)
let problem = @pddl.ground(domain, problem_ast)
let result = @pddl.solve(problem, @pddl.HFF, @pddl.AStar)
let plan_text = result.render_plan(problem)
let report = @pddl.validate_plan(problem, plan_text)
inspect(report.valid, content="true")

#语义约定

1. 前提条件在接地阶段编译为 DNF；状态满足任一析取分支即可应用动作。 数值比较是分支内的约束之一，在执行前的状态上求值。
2. 条件效果的条件（含数值比较）在动作执行前状态上求值；随后统一收集 删除与添加，先删除后添加，添加优先。
3. 数值效果的右端表达式全部在执行前状态上求值。同一函数上： increase/decrease 先做代数和，随后按出现顺序应用 scale-up/ scale-down（除以零时该项不生效）；assign 覆盖前两者，多个 assign 时最后一个生效。条件中除以零的结果定义为 0。
4. 代价模式：出现 :action-costs、total-cost 相关效果/初始赋值或 引用 total-cost 的 :metric 时进入代价模式，动作基础代价为 0，由 increase (total-cost) 累加；否则为经典单位代价。total-cost 只能被 increase，且必须无条件（when 内的代价会被拒绝）；动作代价表达式 只能读取静态函数（在 :init 赋值且无任何效果修改的函数）——这与 Fast Downward 的处理一致，状态相关的代价会导致搜索目标不可静态确定。 代价在内部用 Double 表示，整数代价精确到 2^53；单个动作与初始 total-cost 上限为 10^12，累计代价达到 10^15 视为饱和。
5. 目标同样编译为 DNF；命题部分查位集，数值部分读状态 fluent 数组。 total-cost 不进入状态（它是路径代价 g），因此条件中出现 total-cost 会被拒绝。
6. metric 的方向与表达式会被解析记录；搜索固定按代价（total-cost） 最小化。maximize 任务仍会返回合法计划，但不优化最大化目标。
7. 数值精度：fluent 值与代价用 IEEE 754 双精度存储；数值比较带 1e-9 容差，状态键与输出把非常接近整数的值规范化为整数。整数与简单小数 （0.5、3.25 等）全程精确。

#架构

PDDL 文本
   │  lexer.mbt + sexp.mbt
   ▼
S 表达式（带行列位置）
   │  parser.mbt → ast.mbt
   ▼
Domain / Problem
   │  ground.mbt（类型、对象、量词、DNF、条件效果、数值编译、静态代价、剪枝）
   ▼
GroundProblem（原子表 + fluent 表 + 位集/数组 State + 接地动作）
   ├── heuristics.mbt（删除松弛：hmax / hadd / hff）
   │        └── search.mbt（GBFS / A* / WA*）→ SearchResult → 计划文本
   └── validate.mbt（独立重放）→ ValidationReport（文本 / JSON）

#启发式与可采纳性

• hmax 在删除松弛上计算每个原子的最小达成代价并取目标最大值；在非负动作 代价下可采纳。配合 AStar 得到最优计划。数值约束在松弛中丢弃——松弛任务 是真实任务的放松，可采纳性保持。
• hadd 将目标代价求和，通常更有信息量但不可采纳。
• hff 在松弛任务上提取一条松弛计划并累加其代价，适合 GBFS/WA*。
• goal-count 统计未满足目标字面量数（含数值约束）；blind 恒为 0。

#示例

moon run --target native cmd/moonpddl -- validate \
  examples/delivery-numeric/domain.pddl examples/delivery-numeric/problem.pddl \
  examples/delivery-numeric/plan.pddl
# plan valid: 3 step(s), cost 34

#测试与基准

moon test                     # 91 个测试，wasm
moon test --target native     # 同一套测试，native
moon test --include-skipped -f "benchmarks:*"   # 可选性能基准

#限制与路线图

• 采用完全接地，动作数随对象数量组合增长；当前上限为 200,000 个接地动作、 8,192 个 DNF 分支，公式/效果/数值表达式的嵌套深度上限为 256（超出报错而 不是崩溃）。接地后有一遍删除松弛可达性剪枝，但没有基于相关性分析的 接地期剪枝。
• 搜索为前向最佳优先；尚无语义剪枝、landmark、SAS+ 或符号搜索。
• PDDL 2.1 Level 2 及以上（durative actions、连续效果、PDDL+ 时态模型）与 PDDL 2.2/3.x 扩展（派生谓词、timed initial literals、偏好、约束）不在 符合性终点内，遇到时明确报错。
• 动作代价表达式只能读取静态函数（与 Fast Downward 一致）；状态相关代价会 被明确拒绝。maximize metric 只记录不优化。
• GBFS 按启发式值 h 排序，不保证最优；需要最优解时使用可采纳的 hmax + A*。
• 计划验证基于同一套接地语义；它会独立重放计划，但不会重新推导领域语义。

#开发说明与 AI 使用披露

#许可证

#参考

• D. McDermott et al., PDDL — The Planning Domain Definition Language.
• M. Fox and D. Long, PDDL2.1: An Extension to PDDL for Expressing Planning Domains with Numeric Fluents.
• J. Hoffmann and B. Nebel, The FF Planning System: Fast Plan Generation Through Heuristic Search, JAIR 2001.
• M. Helmert, The Fast Downward Planning System, JAIR 2006.