pingtai_agent/specs_agent/README.md

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	合并生成完整规范文档

快速开始

本地运行

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

Docker 运行

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

使用示例

输入

创建一个数据去重Agent

阶段1输出（需求文档）

# 需求文档: 数据去重 Agent

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

## 2. 用户故事

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

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

阶段2输出（设计文档）

# 设计文档: 数据去重 Agent

## 1. 系统架构

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

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

阶段3输出（任务清单）

# 任务清单: 数据去重 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