pingtai_agent/specs_agent/USAGE.md

Specs Agent 使用指南

概述

Specs Agent 是一个项目规范生成工具，采用三阶段流程将一句话需求转化为完整的项目规范文档。

API 使用

认证

所有 API 请求需要在 Header 中提供 API Key：

# 方式1: api-key header
-H "api-key: your-api-key"

# 方式2: Authorization header
-H "Authorization: Bearer your-api-key"

---

阶段一：需求分析

1.1 生成需求文档

POST /api/v1/requirements

curl -X POST http://localhost:8000/api/v1/requirements \
  -H "Content-Type: application/json" \
  -H "api-key: your-api-key" \
  -d '{
    "brief_description": "创建一个数据去重Agent",
    "context": "用于处理大量文本数据的去重需求"
  }'

请求参数:

参数	类型	必需	说明
brief_description	string	是	一句话需求描述
context	string	否	额外上下文信息

响应示例:

{
  "success": true,
  "phase": "requirements",
  "document": "# 需求文档: 数据去重 Agent\n\n## 1. 项目背景\n...",
  "next_step": "请审阅需求文档，如需修改请调用 refine_requirements，确认后调用 create_design 进入设计阶段"
}

1.2 修改需求文档

POST /api/v1/requirements/refine

curl -X POST http://localhost:8000/api/v1/requirements/refine \
  -H "Content-Type: application/json" \
  -H "api-key: your-api-key" \
  -d '{
    "current_requirements": "# 需求文档: 数据去重 Agent\n...",
    "feedback": "请添加支持JSON格式数据的去重功能"
  }'

请求参数:

参数	类型	必需	说明
current_requirements	string	是	当前需求文档
feedback	string	是	修改意见

---

阶段二：设计规划

2.1 生成设计文档

POST /api/v1/design

curl -X POST http://localhost:8000/api/v1/design \
  -H "Content-Type: application/json" \
  -H "api-key: your-api-key" \
  -d '{
    "requirements_doc": "# 需求文档: 数据去重 Agent\n...",
    "tech_stack": "使用 Python 3.12，优先使用内置库"
  }'

请求参数:

参数	类型	必需	说明
requirements_doc	string	是	确认后的需求文档
tech_stack	string	否	技术栈偏好

响应示例:

{
  "success": true,
  "phase": "design",
  "document": "# 设计文档: 数据去重 Agent\n\n## 1. 系统架构\n...",
  "next_step": "请审阅设计文档，如需修改请调用 refine_design，确认后调用 create_tasks 进入任务拆解阶段"
}

2.2 修改设计文档

POST /api/v1/design/refine

curl -X POST http://localhost:8000/api/v1/design/refine \
  -H "Content-Type: application/json" \
  -H "api-key: your-api-key" \
  -d '{
    "current_design": "# 设计文档: 数据去重 Agent\n...",
    "feedback": "请添加批量处理的API端点"
  }'

---

阶段三：任务拆解

3.1 生成任务清单

POST /api/v1/tasks

curl -X POST http://localhost:8000/api/v1/tasks \
  -H "Content-Type: application/json" \
  -H "api-key: your-api-key" \
  -d '{
    "design_doc": "# 设计文档: 数据去重 Agent\n..."
  }'

请求参数:

参数	类型	必需	说明
design_doc	string	是	确认后的设计文档

响应示例:

{
  "success": true,
  "phase": "tasks",
  "document": "# 任务清单: 数据去重 Agent\n\n## 任务总览\n...",
  "next_step": "请审阅任务清单，如需修改请调用 refine_tasks，确认后调用 get_full_spec 获取完整规范文档"
}

3.2 修改任务清单

POST /api/v1/tasks/refine

curl -X POST http://localhost:8000/api/v1/tasks/refine \
  -H "Content-Type: application/json" \
  -H "api-key: your-api-key" \
  -d '{
    "current_tasks": "# 任务清单: 数据去重 Agent\n...",
    "feedback": "请将Task-002拆分为两个更小的任务"
  }'

---

获取完整规范

合并三阶段文档

POST /api/v1/full-spec

curl -X POST http://localhost:8000/api/v1/full-spec \
  -H "Content-Type: application/json" \
  -H "api-key: your-api-key" \
  -d '{
    "requirements_doc": "# 需求文档: 数据去重 Agent\n...",
    "design_doc": "# 设计文档: 数据去重 Agent\n...",
    "tasks_doc": "# 任务清单: 数据去重 Agent\n..."
  }'

响应示例:

{
  "success": true,
  "document": "# 数据去重 Agent - 完整规范文档\n\n> 本文档由 Specs Agent 自动生成...\n\n---\n\n# 第一部分：需求分析\n...\n\n---\n\n# 第二部分：设计规划\n...\n\n---\n\n# 第三部分：任务拆解\n...",
  "message": "完整规范文档已生成，可以开始按任务清单执行开发"
}

---

MCP 协议使用

工具列表

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

调用工具

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "api-key: your-api-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "analyze_requirements",
      "arguments": {
        "brief_description": "创建一个数据去重Agent"
      }
    }
  }'

---

错误处理

所有 API 在失败时返回：

{
  "success": false,
  "error": "错误信息",
  "phase": "requirements/design/tasks"
}

常见错误：

• 缺少 API Key: 请在 Header 中提供有效的 API Key
• 需求描述不能为空: brief_description 参数不能为空
• 需求文档不能为空: 进入下一阶段前需要提供上一阶段的文档