structured-planning-agent (spa)

结构化独立规划引擎：符号系统主导 + LLM 语义补充的生产级规划 Agent。

生成计划 → 状态机执行 → 工具调用 → 失败自愈（三级重规划）→ checkpoint 持久化。 零配置（无 API Key）即可完整跑通，接入真实 LLM 后自动增强。

核心能力

1. LLM 全局重构（真正落地）

• 计划部分子任务失败且无法在子任务级修复时，触发全局级重构：LLM 基于 【已完成成果】重写剩余部分，成功子任务原样保留，新方案与成功成果合并后校验落回执行。
• 三级重规划层级：步骤级重试 → 子任务级局部重写 → 全局级 LLM 重构（限次数）。
• 无 LLM 时回退符号级重置（失败子任务重置重跑），流程永不中断。

2. 向量记忆检索

• 本地哈希向量（无需外部向量库）：embed_text + cosine_similarity。
• VectorMemoryBackend：跨任务语义召回相似轨迹（默认仅召回成功轨迹，可含失败）。
• 支持任务类型过滤、向量持久化到 JSON，执行时作为上下文注入提示词。

3. 多 Agent 协作

• 角色：PlannerAgent（规划）/ ExecutorAgent（执行）/ ReviewerAgent（评审）。
• 两种协作模式：
  • PIPELINE：规划 → 执行 → 评审 顺序接力；
  • FAN_OUT：规划后并行分发多个执行单元，再统一汇总评审。
• Orchestrator 汇总各角色结果，输出协作报告。

安装

pip install -e .

CLI 用法

spa plan "编写一个 Python 数据分析脚本" --run      # 生成并执行计划
spa plan "重构订单模块" --type coding --run          # 指定任务类型
spa list                                             # 列出已保存计划
spa status <plan_id>                                 # 查看计划状态
spa resume <plan_id> --run                           # 恢复并继续执行
spa agents "整理开发文档" --mode pipeline            # 多 Agent 管线协作
spa agents "实现支付模块" --mode fan_out --verbose   # 多 Agent 分工并行

架构

src/structured_planning_agent/
├── engine.py         # 总入口 / 事件订阅 / 记忆上下文注入
├── config.py         # 配置（含 memory_dir / memory_top_k）
├── agents/           # 多 Agent 协作（planner/executor/reviewer/orchestrator）
├── generation/       # 计划生成（模板兜底 + LLM 增强双路径）
├── execution/        # runner / state_machine / tools / registry
├── replanning/       # 三级重规划（步骤/子任务/全局 LLM 重构）
├── validation/       # 计划静态校验
├── store/            # checkpoint 持久化
├── memory/           # 向量记忆后端（embed + 检索 + 持久化）
└── llm/              # Mock / OpenAI 客户端（同步接口）

测试

python -m pytest

覆盖：模板执行全链路 / 步骤重试 / 子任务重规划 / checkpoint / LLM 全局重构落地 / 向量记忆检索 / 多 Agent 协作。

配置项（环境变量）