内容
# Hefesto
> 从想法到测试，一步到位。Hefesto 是一个由 AI 辅助的 QA/PO 平台，也被称为 **MCP 服务器**，它可以将需求（文本或屏幕截图）转化为 Jira 中的故事、测试用例和覆盖率报告。
```
_ _ _____ _____ _____ _____ _____ _____
| | | | | ___| | ___| | ____| | ___| |_ _| | _ |
| |_| | | |__ | |__ | |__ | |__ | | | | | |
| _ | | __| | __| | __| |___ \ | | | | | |
| | | | | |___ | | | |___ ___) | | | | |_| |
|_| |_| |_____| |_| |_____| |____/ |_| |_____|
```
[](LICENSE)
[](#开始使用)
[](#开始使用)
[](./docs/MCP.md)
**中文** · [English](./README.en.md)
<p align="center">
<img src="docs/media/ui-jira-detail.png" width="860" alt="Jira 面板中的 Hefesto，带有 AI 操作：审查（INVEST）、覆盖率和生成测试">
</p>
---
## 目录
- [概述](#概述)
- [功能](#功能)
- [MCP 服务器](#mcp-服务器)
- [工作流程](#工作流程)
- [开始使用](#开始使用)
- [架构和技术栈](#架构和技术栈)
- [专家代理](#专家代理)
---
## 概述
编写故事、审查、创建测试用例、附加证据、更新 Jira。在纸面上很简单；但实际上，这需要在聊天、Jira、电子表格和文档之间来回切换，每个部分都丢失了前一部分的上下文。Hefesto 将所有这些功能集中在一个地方，利用 AI 完成繁重的工作，并以 Jira 作为事实的来源。
从 **文本或屏幕截图** 中提取需求，Hefesto：
1. **编写故事**（标题、描述和验收标准）；
2. **评估其准备度**，使用 INVEST 标准（差距、风险、评分）；
3. **生成测试用例**，并在 Jira 中创建子任务；
4. **衡量覆盖率**，将验收标准与测试用例进行交叉，并指出未覆盖的部分。
并且它以两种方式完成。通过 **网页界面**，在一个端到端的引导流程中。并且通过 **自然语言**：由于后端也是一个 **MCP 服务器**，因此相同的功能可以通过自然语言在您的 Claude Code/Desktop 中使用（“分析此需求，在项目 X 中创建故事并生成测试用例作为子任务”），无需离开编辑器。
专为 **QA、开发人员和产品负责人** 设计，他们已经在日常工作中使用 AI，并希望停止手动处理上下文。
## 功能
**从需求到故事，由 AI 驱动。** 粘贴需求或附加屏幕截图。Hefesto 理解图像中的内容（字段、按钮、流程），并返回一个完整的故事：标题、描述和可测试的验收标准。审查并一键创建 Jira。
**代码前的质量。** 准备度审查应用 INVEST 标准，并返回 0 到 100 的评分，指出差距、风险和缺失的验收标准。如果您愿意，可以在 Jira 问题上记录所有内容。团队在开发故事时已经成熟。
**可追溯的测试。** 测试生成创建 **每个测试用例作为子任务** 在故事下，格式为 `TC-NNN`。然后，**覆盖率矩阵** 将验收标准与测试用例交叉，并清楚地显示哪些标准尚未被测试：就像 QA 高级工程师手动制作的电子表格一样。
**真正的 Jira（读取和写入）。** 通过 JQL 搜索、读取描述/标准/评论和完全写入：创建、更新、转换和评论问题和子任务（REST API v3），带有本地化的类型。
**多 LLM，包括离线。** 为每个任务选择模型：Claude（官方和视觉模型）、**本地 `.gguf` 模型** 通过 `llama-server`（100% 离线，无云）、Copilot 通过 VS Code 扩展。切换模型是一个下拉菜单；添加新模型是实现接口。
**执行和证据。** 测试用例的交互式卡片、证据附件（截图/日志）、HTML/PDF 报告带有摘要和内联证据，以及分析仪表盘（KPI、延迟、时间序列）。所有这些都存储在 SQLite 中，无需基础设施。
<p align="center">
<img src="docs/media/ui-create-story.png" width="560" alt="带有 AI 辅助的新故事模态（文本或屏幕截图）">
</p>
<p align="center"><sub>从文本或屏幕截图创建故事，由 AI 辅助</sub></p>
## MCP 服务器
后端不仅是一个 Web API：它 **是一个 MCP 服务器**（基于 SSE）。任何 MCP 客户端，如 Claude Code 或 Claude Desktop，都可以通过自然语言操作 Hefesto，并且命令变成现成的快捷方式。
```bash
# Claude Code（原生 SSE 传输）
claude mcp add --transport sse hefesto http://localhost:8080/sse
```
- **14 个工具**，例如 `jira_search`、`jira_create_story`、`review_story`、`generate_test_cases`、`create_test_subtasks`、`coverage_report`、`chat`。
- **2 个资源**：`hefesto://agents`、`hefesto://models`（客户端拉取的上下文）。
- **3 个命令**：`revisar_historia`、`gerar_testes_no_jira`、`rascunhar_historia`。
端点：`GET /sse` + `POST /mcp/message`。完整的参考资料见 [docs/MCP.md](./docs/MCP.md)。
## 工作流程
### PO → QA 工作流程，从需求到覆盖率
在 **Jira** 标签页中：
1. **新故事**：粘贴需求或附加屏幕截图。AI 生成草稿（标题、描述、标准）；调整，选择项目/类型并创建。
2. **审查（INVEST）**：准备度评分，带有差距、风险和缺失标准的可选评论在 Jira 中。
3. **在 Jira 中生成测试**：测试用例成为故事的子任务。
4. **覆盖率**：标准 × 测试矩阵，突出未覆盖的部分。
相同的工作流程通过 MCP 以自然语言运行（参见 [docs/MCP.md](./docs/MCP.md)）。
<p align="center">
<img src="docs/media/ui-coverage.png" width="860" alt="覆盖率矩阵：每个验收标准映射到涵盖它的测试用例，带有覆盖率百分比">
</p>
<p align="center"><sub>覆盖率矩阵：验收标准 × 测试用例，显示未覆盖的部分</sub></p>
### 测试执行流程
使用 QA 高级代理创建一个聊天会话，附加 Jira 问题和手册作为上下文，请求测试用例（它们作为交互式卡片到达），执行并标记每个用例，附加证据并生成 HTML 报告。
<p align="center">
<img src="docs/media/ui-chat-qa.png" width="860" alt="与 QA 高级代理聊天的对话，生成结构化的测试用例，带有场景、步骤和预期结果">
</p>
<p align="center"><sub>QA 高级代理直接在聊天中生成结构化的测试用例</sub></p>
## 开始使用
### 要求
- **Java 17+** 和 **Maven 3.9+**（后端），**Node.js 20 LTS+**（前端）
- 已安装并登录的 **Claude Code CLI**（`claude --version`）：默认适配器和视觉模型用于从图像创建草稿
- *(可选)* **Atlassian Cloud 账户**，带有 API 令牌，用于 Jira
- *(可选)* **`llama-server`** ([llama.cpp](https://github.com/ggml-org/llama.cpp)) + `.gguf` 模型，用于离线运行本地模型
- *(可选)* **VS Code + GitHub Copilot**，带有 Hefesto Bridge 扩展
### 启动项目
```bash
git clone https://github.com/SEU_USUARIO/hefesto.git
cd hefesto
# 后端 → http://localhost:8080
cd hefesto-backend && mvn spring-boot:run
# 前端（另一个终端）→ http://localhost:5173
cd hefesto-frontend && npm install && npm run dev
```
[`agentes/`](./agentes) 文件夹已包含 9 个代理。编辑 `.md` 文件或创建新的。无需重启，使用 `curl -X POST http://localhost:8080/api/agents/reload` 重新加载。
### 配置凭证
凭证存储在 `hefesto-backend/src/main/resources/application-local.yml`（已忽略 git）。要使用 Jira：
```yaml
claude:
cli:
path: /caminho/do/claude # Windows: C:\Users\...\claude.exe
jira:
url: https://suaempresa.atlassian.net
email: voce@empresa.com
token: "API_TOKEN_DO_ATLASSIAN_ID"
```
令牌：[id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)。保存后重启后端。对于本地模型，使用 [`scripts/start-llama-servers.bat`](./scripts/start-llama-servers.bat) 启动 `llama-server`。
## 架构和技术栈
UI 和 MCP 客户端通过不同的路径进入，但落入 **相同的服务**：业务逻辑被共享，而不是被复制。模型层是可插拔的，每个 LLM 都是一个 `LlmAdapter`。
```mermaid
flowchart LR
UI["浏览器 · React UI<br/>:5173"]
MCPC["MCP 客户端<br/>Claude Code / Desktop"]
subgraph BK["Hefesto 后端 · :8080"]
direction TB
API["REST + WebSocket"]
MCPS["MCP 服务器 · SSE<br/>14 个工具 · 2 个资源 · 3 个命令"]
SVC["服务<br/>Jira · 故事 / 审查 / 覆盖率<br/>测试用例 · 遥测 · 报告"]
REG["LlmAdapterRegistry"]
API --> SVC
MCPS --> SVC
SVC --> REG
end
UI -- "REST / WS" --> API
MCPC -- "SSE" --> MCPS
REG --> CC["Claude Code · 视觉"]
REG --> LL["llama-server · 本地 .gguf"]
REG --> CP["Copilot · Gemini · Codex"]
SVC --> JIRA[("Jira REST v3<br/>读取 + 写入")]
SVC --> DB[("SQLite")]
```
### 技术栈
**后端**
**前端**
**VS Code 扩展**：TypeScript，VS Code Language Model API。
详见 [hefesto-backend/README.md](./hefesto-backend/README.md) 和 [docs/MCP.md](./docs/MCP.md)。
## 专家代理
每个代理都是 [`agentes/`](./agentes) 中的一个 **`.md` 文件**，无需修改代码即可进行热重载。Frontmatter 定义元数据；正文是系统提示。
```markdown
---
description: "高级测试用例设计师"
defaultPromptTemplate: "分析和生成测试用例。"
extractsTestCases: true
---
您是一名高级 QA 专家。您的任务是...
```
| 文件 | 角色 |
|---|---|
| `QAseniorAgent.md` | 高级 QA，生成结构化的测试用例 |
| `EscritorDeHistorias.md` | 从需求或图像编写故事草稿 |
| `RevisorDeHistorias.md` | 使用评分、差距和风险评估准备度（INVEST） |
| `AnalistaDeCobertura.md` | 交叉验收标准与测试用例 |
| `AnalistaDeNegocios.md` | 评估 Jira 故事（清晰度、完整性、差距） |
| `TechWriter.md` · `Arquiteto.md` · `CodeReviewer.md` · `Default.md` | 文档、技术分析、代码审查、通用助手 |
完整文档： [agentes/README.md](./agentes/README.md)。
## 贡献
参见 [CONTRIBUTING.md](./CONTRIBUTING.md)：`feat/`/`fix/`/`docs/` 分支、约定提交、适配器和解析器的测试，不提交凭证。对于新代理，开启一个 PR，在 `agentes/` 中添加 `.md` 文件。
## 许可证
[MIT](./LICENSE)。使用、修改、分发。无需强制署名，但鼓励署名。
---
> 模块详情： [docs/MCP.md](./docs/MCP.md) ·
> [hefesto-backend/README.md](./hefesto-backend/README.md) ·
> [hefesto-frontend/README.md](./hefesto-frontend/README.md) ·
> [hefesto-bridge-extension/README.md](./hefesto-bridge-extension/README.md) ·
> [agentes/README.md](./agentes/README.md)
