# Specs Agent

将一句话需求转化为完整的项目规范文档。

## 核心功能

**只做一件事**：将模糊的一句话需求转化为结构化的、可执行的项目规范文档。

专为 **Agent 开发项目** 设计，采用三阶段流程：

```
需求分析 → 设计规划 → 任务拆解
```

### 三阶段流程

| 阶段 | 工具 | 输出 |
|------|------|------|
| 1. 需求分析 | `analyze_requirements` | 用户故事 + 验收标准 |
| 2. 设计规划 | `create_design` | 架构图 + 接口定义 |
| 3. 任务拆解 | `create_tasks` | 任务清单 + 代码要点 |

每个阶段支持人工确认和修改（`refine_*` 工具）。

### 提供能力

| 工具 | 功能 |
|------|------|
| `analyze_requirements` | 分析需求，生成需求文档 |
| `refine_requirements` | 根据反馈修改需求文档 |
| `create_design` | 生成技术设计文档 |
| `refine_design` | 根据反馈修改设计文档 |
| `create_tasks` | 生成任务清单 |
| `refine_tasks` | 根据反馈修改任务清单 |
| `get_full_spec` | 合并生成完整规范文档 |

## 快速开始

### 本地运行

```bash
cd specs_agent
pip install -r requirements.txt
python run_api_server.py
```

### Docker 运行

```bash
docker build -t specs-agent:latest .
docker run -p 8000:8000 -e OPENAI_API_KEY=your-key specs-agent:latest
```

## 使用示例

### 输入

```
创建一个数据去重Agent
```

### 阶段1输出（需求文档）

```markdown
# 需求文档: 数据去重 Agent

## 1. 项目背景
创建一个智能Agent，用于检测和去除数据集中的重复项...

## 2. 用户故事

### US-001: 基础去重功能
**作为** 数据处理人员
**我想要** 对数据列表进行去重
**以便于** 获得无重复的干净数据

**验收标准**:
- **Given** 一个包含重复项的数据列表
  **When** 调用去重工具
  **Then** 返回去除重复后的数据列表
...
```

### 阶段2输出（设计文档）

```markdown
# 设计文档: 数据去重 Agent

## 1. 系统架构

### 1.1 架构图
[Mermaid 架构图]

## 2. MCP 工具设计
| 工具名称 | 功能描述 |
|---------|---------|
| deduplicate | 精确去重 |
| fuzzy_deduplicate | 模糊去重 |
...
```

### 阶段3输出（任务清单）

```markdown
# 任务清单: 数据去重 Agent

## 任务列表

### Task-001: 创建项目目录结构
**文件**: src/__init__.py, src/server/__init__.py
**验收标准**:
- [ ] 目录结构符合规范
...
```

## 环境变量

| 变量 | 必需 | 说明 |
|------|------|------|
| OPENAI_API_KEY | 是 | OpenAI 或 LiteLLM API Key |
| OPENAI_BASE_URL | 否 | API Base URL |
| MODEL_NAME | 否 | 模型名称，默认 taiji/gpt-4o-mini |
| API_PORT | 否 | 服务端口，默认 8000 |

## 项目结构

```
specs_agent/
├── Dockerfile
├── README.md
├── USAGE.md
├── requirements.txt
├── run_api_server.py
└── src/
    ├── __init__.py
    └── server/
        ├── __init__.py
        ├── api_server.py
        ├── mcp_server.py
        └── prompts/
            ├── __init__.py
            ├── requirements_prompt.py
            ├── design_prompt.py
            └── tasks_prompt.py
```

## 服务端点

| 端点 | 方法 | 说明 |
|------|------|------|
| `/` | GET | 服务状态 |
| `/health` | GET | 健康检查 |
| `/mcp` | POST | MCP JSON-RPC |
| `/mcp/sse` | GET/POST | MCP SSE 流式 |
| `/api/v1/requirements` | POST | 生成需求文档 |
| `/api/v1/requirements/refine` | POST | 修改需求文档 |
| `/api/v1/design` | POST | 生成设计文档 |
| `/api/v1/design/refine` | POST | 修改设计文档 |
| `/api/v1/tasks` | POST | 生成任务清单 |
| `/api/v1/tasks/refine` | POST | 修改任务清单 |
| `/api/v1/full-spec` | POST | 获取完整规范 |

## 部署信息

| 配置项 | 值 |
|--------|-----|
| 镜像地址 | agnettaiji.azurecr.io/ai-agents/specs-agent:latest |
| 服务端口 | 8000 |
| 健康检查 | /health |