# agent-task-planner

> 数字管道 · AI Agent 工具链 #1 —— 把高层目标拆成可执行的任务计划 DAG（Agent 的「规划大脑」积木）

`agent-task-planner` 是一个轻量、模型无关的任务规划器：给它一个高层目标，它输出一个**带依赖关系、带验收标准、带质量门控**的结构化任务计划。可作为本地 CLI 使用，也可作为 **MCP 工具**被任意 Agent 调用。

## 定位

Agent 工具链的第一块积木：**规划**。在「想做一件事」和「开始做」之间，先有一份可验证的计划。它不替你执行，只负责把目标结构化，并守住质量门控（依赖无环、验收齐全、含验证步）。

## 数字管道契约

```
输入   goal (高层目标)  +  constraints (可选约束)
  │
  ▼
处理   拆解引擎：LLM 语义拆解（默认 Ollama 本地模型）│ 启发式规则拆解（离线兜底）
  │
  ▼
输出   Plan = 任务列表[
         id, title, type(research|design|code|write|verify),
         depends_on[], acceptance[], effort(S|M|L)
       ]  +  质量门控(validate)
```

## 双引擎

| 引擎 | 触发条件 | 特点 |
|------|----------|------|
| LLM 语义拆解 | 设置 `ATP_LLM_BASE_URL` / `ATP_LLM_MODEL` 或调用时传入 `llm=` | 贴合目标的语义级拆解，走任意 OpenAI 兼容接口 |
| 启发式拆解 | 未配置 LLM | 基于关键词的规则拆解，**离线即可用**，保证工具永远能跑 |

LLM 调用失败时自动回退启发式，不会让工具「罢工」。

## 安装

```bash
cd agent-task-planner
pip install -r requirements.txt
# 可选：启用 LLM 引擎
pip install openai
```

## 用法

### 1. CLI

```bash
# 拆解为 markdown 计划（默认）
python cli.py plan "为一个 Python 库实现 MCP 接入并发布到 GitHub"

# 导出 mermaid（可直接贴进支持 mermaid 的 Markdown 渲染器）
python cli.py plan "写一个爬虫抓取天气数据" -f mermaid

# 导出 json 并落盘，再校验
python cli.py plan "搭建个人博客" -f json > plan.json
python cli.py validate plan.json
python cli.py export plan.json -f markdown
```

### 2. MCP 工具（推荐给 Agent）

启动后向 MCP 客户端暴露 3 个工具：

| 工具 | 说明 |
|------|------|
| `plan_task(goal, constraints_json)` | 拆解目标为任务计划 DAG（JSON） |
| `validate_plan(plan_json)` | 校验计划：依赖完整性、是否存在环、验收标准、质量门控 |
| `export_plan(plan_json, format)` | 导出 markdown / json / mermaid |

接入 WorkBuddy：把 `examples/workbuddy_mcp.json` 的内容合并进
`~/.workbuddy/mcp.json`，并在连接器面板「信任」该服务。

### 3. 作为库调用

```python
from planner import plan
p = plan("为项目补充单元测试")
print(p.to_markdown())
v = p.validate()   # {"ok": True, "issues": [], "task_count": 4}
```

## 配置 LLM（可选）

设置环境变量即可切换为 LLM 语义拆解（任意 OpenAI 兼容接口）：

```bash
export ATP_LLM_BASE_URL="http://localhost:11434/v1"   # Ollama 本地
export ATP_LLM_API_KEY="ollama"
export ATP_LLM_MODEL="qwen2.5:7b"
```

## 自检

```bash
python examples/check_planner.py
```

验证 拆解 → 导出(markdown/mermaid) → 校验 → 环检测 全链路可用。

## 项目家族

属于「数字管道」开源家族的 **AI Agent 工具链** 分支：

- `agent-task-planner`（本仓库）—— 规划大脑
- （规划中）mcp-tool-router —— 工具路由网关
- （规划中）agent-skill-forge —— 技能脚手架生成器

## License

MIT