技能介绍

要解决的问题

当任务足够复杂时，直接让 Agent 开跑容易出三类问题：拆解依赖靠拍脑袋，做到一半才发现前置产出不对；中途上下文断裂，Agent 忘了前面收集了什么；执行过程没有留痕，出错后难以定位到具体步骤。unclekk-roadmap-planner 把 AgentScope 论文中 Meta Planner 的思想落地成一个零第三方依赖的命令行脚本，用一份可校验的 JSON Roadmap 替代隐式的「想一想再做」。

工作机制

脚本位于 scripts/planner.py，能力分为三层：

结构层：roadmap.json 定义子任务的 depends_on、parallel_group、condition、success_criteria 等字段；validate 做 schema 校验、DAG 无环检测和依赖存在性检查，不合法直接以退出码 1 失败。
调度层：step 按拓扑序返回当前可执行的子任务，同一 parallel_group 的任务一起返回供 Agent 并行消费；complete 前对照 success_criteria 做产出自检，上游未完成时拦截跳步；reset 支持按 id 或全局重置。
留痕层：每个子任务记录状态、assigned_worker、desired_auxiliary_tools 与时间戳，原子写（临时文件 + os.replace）避免文件因中途崩溃而截断。

适用边界与注意点

需要明确的分工边界：真正的 LLM 调用、Worker 执行和真并行都由调用方 Agent 完成，本技能只回答「下一步做什么、带什么上下文、建议什么工具」。另外，condition 表达式仅允许白名单标识符（outputs、goal、context 与 len、bool 等），写错会直接报错；如果跳过 complete 前的 success_criteria 自检，下游会拿到不达标的输入继续跑，这是日常使用中最容易被忽视的纪律。