# devTestPlatPy

**Repository Path**: aurkas/dev-test-plat-py

## Basic Information

- **Project Name**: devTestPlatPy
- **Description**: 云蝶AI产研平台的LLM端(Python)
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-09-18
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 开发测试平台 Python Agent 服务

面向开发测试平台的 Python 后端服务，为 Java 业务端和前端提供 AI 驱动的需求处理能力。服务使用 FastAPI 对外提供内部 API，通过 Redis/ARQ 执行耗时任务，并将会话、草稿和执行审计保存到 MySQL。

[English README](README.en.md)

## 能力概览

- **需求生成**：创建需求会话，异步生成 PRD 草稿；支持澄清、驳回后再生成，以及审批同步至 Java 产品服务。
- **需求微调**：对现有需求树异步生成细化节点；支持澄清和驳回重试。
- **原型与流程图**：按需求生成、再生成或微调原型；生成流程图并处理补充澄清。
- **头脑风暴**：围绕指定需求生成产品头脑风暴内容。
- **研发端方案**：基于需求、应用和仓库上下文生成技术方案草稿，规划受影响仓库分支并拆解开发任务；在质量校验通过后可同步 Java 研发端。
- **本地 Coding Agent 协作**：通过独立的本地 Skill 包拉取研发上下文，并回写开发进度、自测、commit 和 Review 结果。
- **可追踪执行**：任务状态、Agent 执行记录和审批记录均落库，可通过 `X-Trace-Id` 串联跨服务链路。

## 技术栈

| 类别 | 组件 |
| --- | --- |
| Web API | FastAPI、Uvicorn、Pydantic v2 |
| Agent | LangGraph、Pydantic AI、OpenAI 兼容模型服务 |
| 异步任务 | Redis、ARQ |
| 数据库 | MySQL、aiomysql |
| 外部协作 | Java Open API、HTTPX |

## 目录说明

```text
app/
├── api/          # FastAPI 路由、内部鉴权与请求处理
├── agent/        # 产品与研发工作流、Schema 与 Agent Skills
├── common/       # 配置与通用实体
├── integration/  # Java 产品服务客户端
├── repo/         # MySQL 数据访问层
├── service/      # 原型、流程图等业务服务
└── worker/       # ARQ Worker、Redis 连接与异步 Job
local_skills/     # 本地 Coding Agent Skill 包，直连 Java Open API，不参与服务端打包
sql/              # 初始化脚本与历史增量迁移
scripts/          # API、Worker 启动脚本
docs/             # 架构设计与需求规格
```

本地 Coding Agent Skill 包的安装方式见 `local_skills/devplat-coding-skills/README.md`，一键安装：

```bash
cd local_skills/devplat-coding-skills && ./install.sh --global
```

安装后，本地 Coding Agent 可按需使用以下研发协作能力：

- 拉取需求、技术方案、任务和仓库上下文；
- 回写开发进度、自测结果、commit 与 Review 结论；
- 在本地编制技术方案并预览、回传平台草稿。

这些 Skill 直连 Java Open API，不经过 Python 服务端；具体触发方式、参数与安装说明见 [本地 Coding Agent Skill 包说明](local_skills/devplat-coding-skills/README.md)。

## 快速启动

### 前置条件

- Python 3.11 或更高版本
- 可访问的 MySQL 和 Redis
- 一个 OpenAI 兼容的模型服务及 API Key
- 若需要需求审批、原型或流程图等 Java 侧数据，需可访问 Java Open API

### 1. 配置环境变量

```bash
cp .env.example .env
```

编辑 `.env`，至少填写数据库密码、模型 API Key 与内部服务 Token。完整配置项见[环境变量](#环境变量)。请勿提交 `.env` 或任何真实密钥。

### 2. 创建虚拟环境并安装依赖

```bash
python3 -m venv .venv
.venv/bin/python -m pip install -e .
```

### 3. 初始化数据库

新环境执行完整初始化脚本：

```bash
mysql -h "$DB_HOST" -P "$DB_PORT" -u "$DB_USER" -p "$DB_NAME" \
  < sql/001_init_agent_schema.sql
```

`sql/001_init_agent_schema.sql` 包含当前完整表结构。`sql/002_*.sql` 及之后的文件用于已有环境按版本增量升级；不要在已通过完整初始化脚本建库的环境中重复执行历史迁移。

### 4. 启动 API 服务

```bash
./scripts/start-api.sh
```

默认监听 `0.0.0.0:8000`，日志写入 `logs/api.log`。本地调试可启用热重载或覆盖地址：

```bash
RELOAD=true HOST=127.0.0.1 PORT=8080 ./scripts/start-api.sh
```

启动后可在 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) 查看 Swagger UI，或访问 `/openapi.json` 获取 OpenAPI 定义。

### 5. 启动异步 Worker

需求生成和需求微调会投递到 Redis 队列，生产或联调时需单独启动 Worker：

```bash
./scripts/start-worker.sh
```

Worker 日志写入 `logs/worker.log`。API 与 Worker 必须使用同一份 `.env` 中的 Redis、MySQL 和模型配置。

## 环境变量

以下变量来自 [`.env.example`](.env.example)。未特别说明的变量均有代码默认值，但建议在部署环境显式配置。

| 变量 | 必填 | 说明 |
| --- | --- | --- |
| `DB_HOST` / `DB_PORT` | 是 | MySQL 主机与端口，默认端口为 `3306` |
| `DB_NAME` / `DB_USER` / `DB_PASSWORD` | 是 | MySQL 数据库、用户名与密码 |
| `DB_POOL_MIN_SIZE` / `DB_POOL_MAX_SIZE` | 否 | 连接池大小，默认 `1` / `10` |
| `AI_MODEL` | 否 | 模型名称；示例为 `deepseek-v4-flash` |
| `AI_BASE_URL` | 否 | OpenAI 兼容模型服务地址 |
| `AI_API_KEY` | 是 | 模型服务访问密钥 |
| `INTERNAL_SERVICE_TOKEN` | 是 | Java 调用内部接口时使用的 Bearer Token |
| `JAVA_OPEN_API_BASE_URL` | 按功能需要 | Java 产品服务地址 |
| `REDIS_HOST` / `REDIS_PORT` / `REDIS_PASSWORD` / `REDIS_DB` | 启用异步任务时是 | ARQ 使用的 Redis 连接配置 |
| `ARQ_JOB_TIMEOUT` | 否 | 单个异步任务超时秒数，默认 `600` |
| `ARQ_MAX_RETRIES` | 否 | 任务最大重试次数，默认 `3` |

> Java Open API 的业务凭证由应用配置动态查询，不需要写入本服务的环境变量。

## Java / 前端联调

### API 文档与路由

服务将以下路由注册到 FastAPI；请求与响应的精确 Schema 以运行中的 Swagger UI 为准。

| 路由前缀 | 主要用途 |
| --- | --- |
| `/internal/agent/requirement-sessions` | 需求会话的创建、运行、查询、澄清、驳回和审批 |
| `/internal/agent/demand-refine-sessions` | 需求微调会话的创建、运行、查询、澄清和驳回 |
| `/internal/agent/prototype` | 原型生成、再生成、微调与流程图操作 |
| `/internal/agent/brainstorm` | 需求头脑风暴生成 |
| `/internal/agent/tech-proposal-sessions` | 技术方案草稿会话的创建、生成、澄清、评审与同步 |
| `/internal/agent/development` | 研发方案生成：汇集上下文、生成方案、规划分支并拆解开发任务 |

需求生成、需求微调和技术方案生成的 `run` 请求只负责入队并返回会话状态；调用方应随后查询对应的 `GET /{session_id}` 接口，直到状态进入草稿完成、等待澄清或失败等终态。研发端方案生成会以 Java 侧需求、仓库、既有方案和任务为上下文；Python 侧保存执行审计和中间产物，技术方案、仓库分支和开发任务等业务数据以 Java 侧为准。

### 必需请求头

所有内部业务接口均要求下列请求头：

```http
Authorization: Bearer <INTERNAL_SERVICE_TOKEN>
X-Trace-Id: <全链路唯一标识>
X-Operator-Id: <正整数操作人 ID>
X-App-Id: <正整数应用 ID>
```

- `Authorization` 缺失或 Token 无效时返回 `401`；服务未配置 Token 时返回 `503`。
- `X-Trace-Id`、`X-Operator-Id` 或 `X-App-Id` 缺失/非法时返回 `400`。
- 创建或读取会话时，服务会校验请求中的应用上下文与会话所属应用一致；不一致返回 `403`。

### 联调建议

1. 由 Java 网关统一注入上述请求头，前端不直接持有 `INTERNAL_SERVICE_TOKEN`。
2. 将 `X-Trace-Id` 透传到 Java 服务和日志系统，便于定位异步任务与跨服务错误。
3. 使用 Swagger UI 确认每个版本的模型字段，并以会话状态驱动前端轮询、澄清和重试交互。

## 运行与排查

| 现象 | 检查项 |
| --- | --- |
| API 脚本提示找不到虚拟环境 | 确认 `.venv/bin/python` 存在，并执行依赖安装命令 |
| 会话一直处于运行中 | 确认 `./scripts/start-worker.sh` 正在运行，且 API/Worker 指向同一个 Redis DB |
| 数据库连接失败 | 检查 `.env` 中 `DB_*` 配置、MySQL 网络连通性及初始化脚本是否已执行 |
| 内部接口返回 401/503 | 检查 `INTERNAL_SERVICE_TOKEN` 是否已配置，且调用方 Bearer Token 一致 |
| 生成任务失败 | 查看 `logs/api.log`、`logs/worker.log`，再确认模型服务地址、模型名称与 API Key |

## 常用命令

```bash
# 启动 API
./scripts/start-api.sh

# 启动异步 Worker
./scripts/start-worker.sh

# 使用热重载启动 API
RELOAD=true ./scripts/start-api.sh
```

## 相关文档

- [Python Agent 服务实现计划](docs/architecture/python-agent-service-implementation-plan.md)
- [Java 与 Python 集成说明](docs/architecture/java-frontend-python-agent-integration.md)
- [v1.2.0 研发端 Agent 与 Skills 技术方案](docs/v1.2.0/development-agent-skills-tech-design.md)
- [本地 Coding Agent Skill 包说明](local_skills/devplat-coding-skills/README.md)
- [README 完善设计规格](docs/superpowers/specs/2026-08-28-readme-revamp-design.md)

## 参与贡献

提交变更前，请确保文档、配置示例和代码实现保持一致；不要提交 `.env`、日志或任何凭证信息。功能设计与架构材料请放在 `docs/` 下的相应目录中。