feat: add fs-backend service

fs-backend/docs/前端连接指南.md

@@ -0,0 +1,188 @@
+# 前后端连接指南
+
+## 前端配置方式
+
+### 1. 环境变量配置（推荐）
+
+前端项目使用 `.env` 文件配置后端地址：
+
+```bash
+# OpenCodeUI/.env
+VITE_API_BASE_URL=http://localhost:8000
+```
+
+### 2. 修改位置
+
+前端项目中的 API 地址配置文件：
+- **文件路径**: `OpenCodeUI/src/constants/api.ts`
+- **配置项**: `API_BASE_URL`
+
+```typescript
+export const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || 'http://127.0.0.1:4096'
+```
+
+## 添加项目创建接口到前端
+
+### 步骤 1: 创建 API 调用函数
+
+在 `OpenCodeUI/src/api/` 目录下创建 `project.ts`:
+
+```typescript
+// OpenCodeUI/src/api/project.ts
+
+import { getApiBaseUrl, getAuthHeader } from './http'
+
+export interface ProjectCreateRequest {
+  project_name: string
+}
+
+export interface ProjectCreateResponse {
+  success: boolean
+  message: string
+  project_path: string
+}
+
+/**
+ * 创建新项目
+ * POST /fs/project/create
+ */
+export async function createProject(
+  params: ProjectCreateRequest
+): Promise<ProjectCreateResponse> {
+  const baseUrl = getApiBaseUrl()
+  const url = `${baseUrl}/fs/project/create`
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...getAuthHeader(),
+    },
+    body: JSON.stringify(params),
+  })
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({ detail: '请求失败' }))
+    throw new Error(error.detail || response.statusText)
+  }
+
+  return response.json()
+}
+```
+
+### 步骤 2: 在 React 组件中使用
+
+```tsx
+// OpenCodeUI/src/components/ProjectCreate.tsx
+
+import React, { useState } from 'react'
+import { createProject } from '@/api/project'
+
+export function ProjectCreate() {
+  const [projectName, setProjectName] = useState('')
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState('')
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setLoading(true)
+    setError('')
+
+    try {
+      const result = await createProject({ project_name: projectName })
+      alert(result.message)
+      setProjectName('')
+    } catch (err) {
+      setError(err instanceof Error ? err.message : '创建失败')
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        type="text"
+        value={projectName}
+        onChange={(e) => setProjectName(e.target.value)}
+        placeholder="输入项目名称"
+      />
+      <button type="submit" disabled={loading}>
+        {loading ? '创建中...' : '创建项目'}
+      </button>
+      {error && <p style={{ color: 'red' }}>{error}</p>}
+    </form>
+  )
+}
+```
+
+## 本地开发联调
+
+### 1. 启动后端服务
+
+```bash
+cd OpenCode-backend
+pip install -r requirements.txt
+uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+### 2. 启动前端开发服务器
+
+```bash
+cd OpenCodeUI
+# 确保 .env 文件中配置了正确的后端地址
+echo "VITE_API_BASE_URL=http://localhost:8000" > .env.local
+npm install
+npm run dev
+```
+
+### 3. 跨域配置（如需要）
+
+后端已配置 CORS，允许所有来源访问。如需限制，修改：
+
+```python
+# OpenCode-backend/app/core/config.py
+class Settings(BaseSettings):
+    CORS_ORIGINS: List[str] = ["http://localhost:5173", "http://127.0.0.1:5173"]
+```
+
+## API 接口列表
+
+| 接口 | 方法 | 地址 | 描述 |
+|------|------|------|------|
+| 创建项目 | POST | `/fs/project/create` | 创建新项目目录 |
+| 健康检查 | GET | `/` | 服务状态检查 |
+
+## 请求示例
+
+### cURL
+
+```bash
+curl -X POST "http://localhost:8000/fs/project/create" \
+  -H "Content-Type: application/json" \
+  -d '{"project_name": "my_project"}'
+```
+
+### 成功响应
+
+```json
+{
+  "success": true,
+  "message": "项目 'my_project' 创建成功",
+  "project_path": "/root/workspace/my_project"
+}
+```
+
+### 错误响应
+
+```json
+{
+  "detail": "项目名称仅允许包含中英文、数字、下划线、横杠"
+}
+```
+
+## 安全说明
+
+1. **路径安全**: 后端已锁定所有文件操作在 `/root/workspace` 目录内
+2. **输入校验**: 项目名经过正则校验，禁止路径逃逸字符
+3. **CORS**: 生产环境建议配置具体的允许来源