内容
# 项目流
一个用于人工智能辅助开发的工作流管理系统，类似于Jira或Azure DevOps。支持基于API的交互和模型上下文协议，以实现与AI代理的无缝集成。
## 功能特点
- 分层任务管理（Epic、故事、子任务）
- **🚀 新增：自然语言聊天界面** - 使用对话式命令与ProjectFlow交互
- 用于程序化访问的REST API
- 支持AI代理的模型上下文协议（MCP）
- 面向人类用户的网页界面
- 灵活的存储：文件系统（JSON）或PostgreSQL数据库
- 清洁、现代的UI，具备无障碍功能
- 容器化部署
## 技术栈
- **后端**：Go 1.24
- **存储**：文件系统（JSON）或PostgreSQL数据库
- **前端**：HTML模板、CSS、JavaScript
- **容器化**：Docker/Podman
- **协议**：HTTP REST API + 模型上下文协议
## 快速入门
### 前提条件
- Go 1.24 或更高版本
- Docker/Podman（用于容器化部署）
### 本地运行
1. 克隆仓库：
```bash
git clone https://github.com/aykay76/projectflow.git
cd projectflow
```
2. 运行应用程序：
```bash
go run cmd/server/main.go
```
3. 打开浏览器，导航到 `http://localhost:16191`
## 💬 自然语言聊天界面
ProjectFlow现拥有一个由AI驱动的聊天界面，允许您使用自然语言命令管理任务和项目。只需在标题栏点击聊天按钮（💬），或使用键盘快捷键 `⌘+/` （Mac）或 `Ctrl+/` （Windows/Linux）即可开始。
### 快速示例
```
创建高优先级任务以修复登录错误
列出PF项目中的所有任务
将任务PF-123标记为已完成
显示我的逾期任务
创建一个名为“网站改版”的新项目
```
### 开始使用聊天
1. **打开聊天界面**：点击标题栏中的 💬 按钮，或按 `⌘+/`
2. **输入您的请求**：使用自然语言描述您想要执行的操作
3. **获取即时结果**：AI将解释您的请求并执行操作
有关详细的聊天命令和示例，请参阅 [聊天界面指南](docs/chat-interface-guide.md)。
### LLM 配置
聊天界面支持多个LLM提供商：
- **🚀 Ollama**：使用本地LLM模型以确保隐私和离线能力
- **OpenAI GPT**：使用OpenAI的GPT模型进行自然语言理解
- **Groq**：基于云的快速LLM推理
- **Anthropic Claude**：利用Anthropic的Claude AI进行对话交互
#### 使用Ollama（本地LLM）快速设置
为了使用隐私且无API成本的最快设置：
```bash
# 安装Ollama
brew install ollama # macOS
# 或 curl -fsSL https://ollama.com/install.sh | sh # Linux
# 启动Ollama并安装模型
ollama serve &
ollama pull llama3.2
# 配置ProjectFlow
export LLM_PROVIDER=ollama
export LLM_OLLAMA_MODEL=llama3.2
./projectflow
```
有关详细设置说明，请参阅 [Ollama快速入门指南](docs/ollama-quick-start.md)。
#### 基于云的LLM提供商
对于基于云的LLM，请配置您的API密钥：
```bash
# 对于OpenAI
export LLM_PROVIDER=openai
export LLM_API_KEY=your-openai-key
export LLM_MODEL=gpt-4
# 对于Groq
export LLM_PROVIDER=groq
export LLM_API_KEY=your-groq-key
export LLM_MODEL=llama-3.1-8b-instant
```
## 环境变量
**服务器配置：**
- `PORT`：服务器端口（默认：16191）
- `SHUTDOWN_TIMEOUT`：温和关闭超时，单位为秒（默认：30）
- `LOG_LEVEL`：日志级别 - DEBUG、INFO、WARN、ERROR（默认：INFO）
- `LOG_FORMAT`：日志格式 - json 或 text（默认：text）
**存储配置：**
- `STORAGE_TYPE`：存储后端 - file 或 postgres（默认：file）
**文件存储：**
- `DATA_DIR`：数据存储目录（默认：./data）
**PostgreSQL存储：**
- `DB_HOST`：数据库主机（默认：localhost）
- `DB_PORT`：数据库端口（默认：5432）
- `DB_NAME`：数据库名称（默认：projectflow）
- `DB_USER`：数据库用户（默认：projectflow）
- `DB_PASSWORD`：数据库密码（postgres必填）
- `DB_SSL_MODE`：SSL模式 - disable、require、verify-ca、verify-full、prefer、allow（默认：prefer）
**LLM配置（聊天界面）：**
- `LLM_PROVIDER`：LLM提供商 - ollama、groq、openai、disabled（默认：disabled）
- `LLM_API_KEY`：云LLM提供商的API密钥（groq、openai必填）
- `LLM_BASE_URL`：LLM提供商的自定义基URL（可选）
- `LLM_MODEL`：使用的模型名称（默认根据提供商不同）
- `LLM_TIMEOUT`：请求超时，单位为秒（默认：60）
- `LLM_MAX_TOKENS`：每响应最大令牌数（默认：1000）
**Ollama特定（本地LLM）：**
- `LLM_OLLAMA_HOST`：Ollama服务器URL（默认：http://localhost:11434）
- `LLM_OLLAMA_MODEL`：Ollama模型名称（默认：llama3.2）
有关PostgreSQL设置的详细信息，请参阅 [PostgreSQL存储文档](docs/postgresql-storage.md)。
### 使用Docker
1. 构建镜像：
```bash
podman build -t projectflow .
```
2. 运行容器：
```bash
podman run -p 16191:16191 -v $(pwd)/data:/app/data projectflow
```
## API文档
### 聊天API
- `POST /api/chat` - 向聊天界面发送自然语言消息
- `GET /api/chat/history` - 获取对话历史
### LLM API
- `GET /api/llm/info` - 获取LLM提供商信息和状态
- `GET /api/llm/health` - 检查LLM提供商健康状况
- `POST /api/llm/chat` - 向LLM发送直接消息（绕过ProjectFlow翻译）
#### 聊天请求/响应
**发送消息：**
```json
POST /api/chat
{
"message": "创建高优先级任务以修复登录错误",
"conversation_id": "可选uuid"
}
```
**响应：**
```json
{
"response": "我创建了任务PF-123：'修复登录错误'，优先级为高。",
"actions_taken": ["create_task"],
"task_ids": ["PF-123"],
"conversation_id": "uuid",
"confidence": 0.95,
"intent": "create_task"
}
```
**获取历史记录：**
```json
GET /api/chat/history?conversation_id=uuid
{
"id": "uuid",
"messages": [
{
"id": "msg-uuid",
"role": "user",
"content": "创建任务...",
"timestamp": "2025-06-22T15:17:44.334579Z"
}
],
"created": "2025-06-22T15:17:44.334574Z",
"updated": "2025-06-22T15:17:44.334574Z"
}
```
#### LLM API示例
**获取LLM信息：**
```json
GET /api/llm/info
{
"enabled": true,
"provider": "ollama",
"model": "llama3.2",
"status": "healthy",
"timestamp": "2025-06-23T08:56:47.927Z",
"metadata": {
"host": "http://localhost:11434",
"version": "0.1.17"
}
}
```
**检查LLM健康状况：**
```json
GET /api/llm/health
{
"healthy": true,
"status": "healthy",
"provider": "ollama",
"timestamp": "2025-06-23T08:56:47.927Z",
"duration_ms": 45,
"suggestions": []
}
```
**直接LLM聊天：**
```json
POST /api/llm/chat
{
"messages": [
{"role": "user", "content": "你好！"}
],
"max_tokens": 1000,
"temperature": 0.7
}
响应：
{
"response": {
"choices": [
{
"message": {
"role": "assistant",
"content": "你好！今天我能帮你什么？"
},
"finish_reason": "stop"
}
]
},
"provider": "ollama",
"model": "llama3.2"
}
```
### 任务API
- `GET /api/tasks` - 列出所有任务
- `POST /api/tasks` - 创建新任务
- `GET /api/tasks/{id}` - 按ID获取任务
- `PUT /api/tasks/{id}` - 更新任务
- `DELETE /api/tasks/{id}` - 删除任务
- `GET /api/hierarchy` - 获取任务的层次结构
### 任务结构
```json
{
"id": "string",
"title": "string",
"description": "string",
"status": "string",
"priority": "string",
"parent_id": "string",
"children": ["string"],
"created_at": "timestamp",
"updated_at": "timestamp"
}
```
### 层次结构
`/api/hierarchy`端点以嵌套结构返回任务：
```json
[
{
"task": {
"id": "string",
"title": "string",
"description": "string",
"status": "string",
"priority": "string",
"type": "string",
"parent_id": "string",
"children": ["string"],
"created_at": "timestamp",
"updated_at": "timestamp"
},
"child_tasks": [
{
"task": { /* 嵌套任务 */ },
"child_tasks": [ /* 递归嵌套 */ ]
}
]
}
]
```
## 开发
### 项目结构
```
├── cmd/server/ # 应用程序入口点
├── internal/
│ ├── handlers/ # HTTP处理程序
│ ├── models/ # 数据模型
│ └── storage/ # 存储实现
├── pkg/api/ # 公共API定义
├── web/
│ ├── templates/ # HTML模板
│ └── static/ # CSS、JS、图片
├── data/ # 本地数据存储
└── Dockerfile # 容器定义
```
### 运行测试
```bash
go test ./...
```
### 构建
```bash
go build -o bin/projectflow cmd/server/main.go
```
## 模型上下文协议（MCP）
ProjectFlow包含一个模型上下文协议（MCP）服务器，使AI代理能够以编程方式与任务交互。这允许AI助手创建、读取、更新和删除任务作为其工作流的一部分。
### MCP服务器设置
1. **启动MCP服务器：**
```bash
go run cmd/mcp-server/main.go
```
默认情况下，MCP服务器运行在端口3001。
2. **配置MCP客户端：**
使用提供的`mcp-config.json`文件或手动配置：
```json
{
"mcpServers": {
"projectflow": {
"command": "go",
"args": ["run", "cmd/mcp-server/main.go"],
"cwd": "/path/to/projectflow"
}
}
}
```
### 可用的MCP工具
MCP服务器提供这些工具用于任务管理：
- **`list_tasks`** - 列出所有任务，可选过滤
- **`create_task`** - 创建新任务
- **`get_task`** - 按ID获取特定任务
- **`update_task`** - 更新现有任务
- **`delete_task`** - 删除任务
- **`get_task_hierarchy`** - 获取任务的层次结构
### 可用的MCP资源
MCP服务器公开这些资源：
- **`tasks://all`** - 所有任务列表
- **`tasks://hierarchy`** - 任务层次结构
- **`tasks://summary`** - 项目总结和统计数据
### 示例用法
```bash
# 启动两个服务器
go run cmd/server/main.go & # HTTP服务器在:16191
go run cmd/mcp-server/main.go & # MCP服务器在:3001
# 与MCP兼容的AI客户端
# AI现在可以编程方式创建、管理和查询任务
```
### 与AI代理集成
AI代理可以使用MCP接口：
- 创建和管理开发任务
- 跟踪项目进度
- 生成报告和摘要
- 自动化工作流过程
- 与其他开发工具集成
有关MCP文档的详细信息，请参阅 [docs/mcp.md](docs/mcp.md)。
## ProjectFlow与VS Code集成
ProjectFlow可以无缝集成到您的VS Code项目中，允许您在Git中存储和管理任务与代码。这使得强大的AI辅助开发工作流成为可能，编码代理可以直接在项目上下文中创建、更新和跟踪开发任务。
### 设置`.vscode/mcp.json`
在项目根目录添加`.vscode/mcp.json`文件以配置ProjectFlow作为MCP服务器：
```json
{
"mcpServers": {
"projectflow": {
"command": "go",
"args": ["run", "/path/to/projectflow/cmd/mcp-server/main.go"],
"cwd": "/path/to/projectflow",
"env": {
"STORAGE_DIR": "./.projectflow/data"
}
}
}
}
```
### 项目特定任务存储
当与您的项目集成时，ProjectFlow将在您项目内的`.projectflow/data/`目录中存储任务：
```
your-project/
├── .vscode/
│ └── mcp.json # MCP配置
├── .projectflow/
│ └── data/
│ └── tasks/ # 项目特定任务
│ ├── epic-1.json # 您的开发Epic
│ ├── story-1.json # 用户故事
│ └── task-1.json # 开发任务
├── src/ # 您的应用程序代码
├── README.md
└── .gitignore
```
### 集成的好处
1. **统一版本控制**：任务与代码一起版本控制
2. **上下文感知AI**：编码代理了解代码和任务上下文
3. **团队协作**：通过Git共享任务管理
4. **分支特定任务**：不同分支可以有不同的任务状态
5. **自动化工作流**：AI代理可以从代码分析创建任务
6. **链接任务到提交或拉取请求**：关联任务与代码更改
### 示例工作流
1. **在您的项目中初始化ProjectFlow：**
```bash
mkdir -p .projectflow/data/projects
echo ".projectflow/data/projects/*/*.json" >> .gitignore # 可选：排除项目和任务文件
```
2. **配置VS Code MCP：**
```json
{
"mcpServers": {
"projectflow": {
"command": "go",
"args": ["run", "/path/to/projectflow/cmd/mcp-server/main.go"],
"env": {
"STORAGE_DIR": "./.projectflow/data"
}
}
}
}
```
3. **与AI编码代理一起使用：**
- AI代理可以根据代码分析创建任务
- 跟踪代码更改的开发进度
- 从代码中的TODO注释生成任务
- 将任务链接到特定的提交或拉取请求
### 开发工作流集成
ProjectFlow MCP集成支持强大的开发工作流：
- **自动任务创建**：AI代理分析代码并创建相关任务
- **进度跟踪**：链接任务到提交和拉取请求
- **代码审查任务**：为特定的代码更改生成审查任务
- **错误跟踪**：创建和跟踪代码分析中的错误
- **功能规划**：将功能规划为分层任务（Epic → 故事 → 任务）
### 前端访问
虽然主要接口是通过MCP和AI代理，但您仍然可以访问Web前端：
1. 启动指向项目数据的ProjectFlow服务器：
```bash
STORAGE_DIR=./.projectflow/data go run /path/to/projectflow/cmd/server/main.go
```
2. 打开 `http://localhost:16191` 以查看和管理任务
### Git集成最佳实践
- **提交任务更改**：包括任务更新提交
- **分支特定任务**：使用不同分支的不同任务状态
- **团队同步**：拉取任务更新时与团队同步
- **任务清理**：定期存档已完成的任务
## 文档
### 用户文档
- **[用户指南](docs/user-guide.md)** - 终端用户综合指南
- **[聊天界面指南](docs/chat-interface-guide.md)** - 自然语言命令和示例
- **[FAQ](docs/faq.md)** - 常见问题和答案
### 管理员文档
- **[部署指南](docs/deployment-guide.md)** - 生产部署选项
- **[LLM设置指南](docs/llm-setup-guide.md)** - 配置AI提供商
- **[PostgreSQL存储](docs/postgresql-storage.md)** - 数据库设置和配置
- **[故障排除指南](docs/troubleshooting.md)** - 常见问题和解决方案
### 开发者文档
- **[开发者指南](docs/developer-guide.md)** - 扩展和自定义ProjectFlow
- **[MCP文档](docs/mcp.md)** - 模型上下文协议集成
- **[配置指南](docs/configuration.md)** - 环境变量和设置
- **[应用内帮助系统](docs/in-app-help.md)** - 前端帮助实现
## 贡献
1. **Fork仓库**
2. **创建功能分支**
3. **进行更改并添加适当的测试**
4. **提交拉取请求**
查看我们的 [开发者指南](docs/developer-guide.md)以获取详细的贡献指南。
## 许可证
MIT License - 参见 [LICENSE](LICENSE) 文件中的详细信息。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器