Metadata-Version: 2.4
Name: structured-planning-agent
Version: 1.1.0
Summary: 结构化独立规划引擎：符号系统主导 + LLM 语义补充的生产级规划 Agent（LLM 全局重构 + 向量记忆 + 多 Agent 协作）
Author: Marvis
License: MIT
Keywords: agent,planning,state-machine,llm,orchestration
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pydantic<3,>=2.5
Requires-Dist: pydantic-settings>=2.1
Requires-Dist: httpx>=0.26
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"

# 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` 汇总各角色结果，输出协作报告。

## 安装

```bash
pip install -e .
```

## CLI 用法

```bash
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 客户端（同步接口）
```

## 测试

```bash
python -m pytest
```

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

## 配置项（环境变量）

| 变量 | 默认 | 说明 |
|------|------|------|
| `SPA_LLM_PROVIDER` | `mock` | `mock` / `openai` |
| `SPA_LLM_API_KEY` | - | OpenAI API Key |
| `SPA_LLM_BASE_URL` | - | OpenAI 兼容端点 |
| `SPA_LLM_MODEL` | `gpt-4o-mini` | 模型名 |
| `SPA_MEMORY_DIR` | `~/.spa/memory` | 向量记忆持久化路径 |
| `SPA_MEMORY_TOP_K` | `3` | 检索注入的记忆条数 |
| `SPA_CHECKPOINT_DIR` | `~/.spa/checkpoints` | 计划 checkpoint 目录 |
