Skip to content

API Reference

Jump to bottom
thend edited this page Nov 30, 2025 · 2 revisions

API 参考

CCMage 提供完整的 RESTful API 接口，用于项目管理、进程控制和 AI 集成。

📋 API 约定

基础 URL

http://localhost:9999/api

响应格式

所有 API 统一返回 JSON 格式：

成功响应：

{
  "success": true,
  "data": { ... }
}

错误响应：

{
  "success": false,
  "error": "错误类型",
  "message": "详细错误信息"
}

HTTP 状态码

  • 200 - 成功
  • 400 - 请求错误（参数错误、验证失败）
  • 404 - 资源不存在
  • 500 - 服务器内部错误

📁 项目管理 API

获取所有项目

GET /api/projects

响应：

{
  "success": true,
  "data": {
    "projects": {
      "my-app": {
        "path": "my-app",
        "tech": ["React", "Node.js"],
        "status": "active",
        "port": 3000,
        "description": "我的应用"
      }
    },
    "external": { ... }
  }
}

获取项目状态

GET /api/projects/:name/status

响应：

{
  "success": true,
  "data": {
    "git": {
      "branch": "main",
      "hasUncommitted": true,
      "uncommittedCount": 3
    },
    "dependencies": {
      "installed": true
    },
    "running": false,
    "port": 3000,
    "tech": ["React", "Node.js"]
  }
}

批量获取项目状态

POST /api/projects/status/batch
Content-Type: application/json

{
  "projectNames": ["project1", "project2", "project3"]
}

更新项目配置

PUT /api/projects
Content-Type: application/json

{
  "projects": { ... },
  "external": { ... }
}

执行项目操作

POST /api/projects/:name/action
Content-Type: application/json

{
  "action": "open-directory" | "open-vscode" | "install-deps" | "git-status"
}

支持的操作：

  • open-directory - 在文件管理器中打开
  • open-vscode - 在 VS Code 中打开
  • install-deps - 安装依赖
  • git-status - 查看 Git 状态

🚀 进程管理 API

启动项目服务

POST /api/projects/:name/start
Content-Type: application/json

{
  "command": "npm run dev"  // 可选，默认自动检测
}

停止项目服务

POST /api/projects/:name/stop

获取运行状态

GET /api/projects/:name/running

响应：

{
  "success": true,
  "data": {
    "running": true,
    "pid": 12345
  }
}

获取实时日志（SSE）

GET /api/projects/:name/logs/stream

响应格式：Server-Sent Events

event: log
data: {"type":"stdout","content":"Server started on port 3000\n"}

event: log
data: {"type":"stderr","content":"Warning: deprecated API\n"}

🤖 AI 助手 API

创建 AI 会话

POST /api/projects/:name/ai
Content-Type: application/json

{
  "prompt": "帮我添加一个登录功能",
  "engine": "claude-code" | "codex"  // 可选
}

响应：

{
  "success": true,
  "data": {
    "sessionId": "uuid-session-id"
  }
}

获取 AI 输出流（SSE）

GET /api/projects/:name/ai/stream/:sessionId

响应格式：Server-Sent Events

event: message
data: {"type":"assistant","content":"我来帮你实现登录功能..."}

event: message
data: {"type":"tool","name":"write_file","args":{...}}

event: message
data: {"type":"result","success":true}

event: complete
data: {"sessionId":"...","timestamp":"..."}

终止 AI 会话

POST /api/projects/:name/ai/terminate/:sessionId

获取历史记录

GET /api/projects/:name/ai/history

响应：

{
  "success": true,
  "data": [
    {
      "sessionId": "uuid-1",
      "timestamp": "2025-11-27T10:00:00Z",
      "logs": [ ... ]
    }
  ]
}

📋 Todo 管理 API

获取项目 Todos

GET /api/projects/:name/todos?status=pending&priority=high&type=bug

查询参数：

  • status: pending | in_progress | completed | cancelled
  • priority: low | medium | high | urgent
  • type: task | bug | feature | improvement

响应：

{
  "success": true,
  "data": [
    {
      "id": 1,
      "project_name": "my-project",
      "title": "修复登录 Bug",
      "description": "用户反馈登录时偶尔失败",
      "status": "in_progress",
      "priority": "high",
      "type": "bug",
      "due_date": "2025-12-01",
      "estimated_hours": 4,
      "actual_hours": 2.5,
      "labels": ["urgent", "bug"],
      "created_at": "2025-11-27T10:00:00Z",
      "updated_at": "2025-11-27T15:30:00Z"
    }
  ]
}

创建 Todo

POST /api/projects/:name/todos
Content-Type: application/json

{
  "title": "实现用户注册功能",
  "description": "支持邮箱和手机号注册",
  "priority": "high",
  "type": "feature",
  "due_date": "2025-12-10",
  "estimated_hours": 8,
  "labels": ["feature", "urgent"]
}

更新 Todo

PUT /api/todos/:id
Content-Type: application/json

{
  "status": "completed",
  "actual_hours": 7.5
}

删除 Todo

DELETE /api/todos/:id

批量排序 Todos

PUT /api/projects/:name/todos/reorder
Content-Type: application/json

{
  "todoIds": [3, 1, 5, 2, 4]
}

🎯 里程碑管理 API

获取项目里程碑

GET /api/projects/:name/milestones

创建里程碑

POST /api/projects/:name/milestones
Content-Type: application/json

{
  "title": "v1.0 发布",
  "description": "第一个正式版本",
  "start_date": "2025-11-01",
  "due_date": "2025-12-31",
  "progress": 60
}

更新里程碑

PUT /api/milestones/:id
Content-Type: application/json

{
  "progress": 75
}

删除里程碑

DELETE /api/milestones/:id

🏷️ 标签管理 API

获取所有标签

GET /api/labels

创建标签

POST /api/labels
Content-Type: application/json

{
  "name": "urgent",
  "color": "#ff0000"
}

删除标签

DELETE /api/labels/:id

⏱️ 时间追踪 API

创建时间记录

POST /api/projects/:name/time-entries
Content-Type: application/json

{
  "todo_id": 1,
  "description": "修复登录 Bug",
  "duration": 2.5,
  "started_at": "2025-11-27T14:00:00Z",
  "ended_at": "2025-11-27T16:30:00Z"
}

获取项目时间记录

GET /api/projects/:name/time-entries

获取任务时间记录

GET /api/todos/:id/time-entries

📊 统计和日志 API

获取项目统计

GET /api/projects/:name/stats

响应：

{
  "success": true,
  "data": {
    "name": "my-project",
    "total_todos": 25,
    "completed_todos": 15,
    "in_progress_todos": 5,
    "pending_todos": 5,
    "total_milestones": 3,
    "completed_milestones": 1,
    "total_hours": 127.5
  }
}

获取活动日志

GET /api/projects/:name/activity?limit=50

查询参数：

  • limit: 返回记录数量（默认 50）

🔐 错误处理

常见错误

项目不存在：

{
  "success": false,
  "error": "NOT_FOUND",
  "message": "项目 'xxx' 不存在"
}

参数验证失败：

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "标题不能为空"
}

进程已在运行：

{
  "success": false,
  "error": "ALREADY_RUNNING",
  "message": "项目服务已在运行"
}

API Key 未配置：

{
  "success": false,
  "error": "CONFIG_ERROR",
  "message": "未配置 ANTHROPIC_API_KEY"
}

💡 使用示例

JavaScript/TypeScript

// 获取项目状态
const response = await fetch('/api/projects/my-app/status');
const { success, data } = await response.json();

// 启动项目
await fetch('/api/projects/my-app/start', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ command: 'npm run dev' })
});

// 监听日志流（SSE）
const eventSource = new EventSource('/api/projects/my-app/logs/stream');
eventSource.onmessage = (event) => {
  const log = JSON.parse(event.data);
  console.log(log.content);
};

Python

import requests
import json

# 获取项目状态
response = requests.get('http://localhost:9999/api/projects/my-app/status')
data = response.json()

# 创建 Todo
response = requests.post(
    'http://localhost:9999/api/projects/my-app/todos',
    json={
        'title': '实现登录功能',
        'priority': 'high',
        'type': 'feature'
    }
)

cURL

# 获取所有项目
curl http://localhost:9999/api/projects

# 启动项目
curl -X POST http://localhost:9999/api/projects/my-app/start \
  -H "Content-Type: application/json" \
  -d '{"command":"npm run dev"}'

# 创建 Todo
curl -X POST http://localhost:9999/api/projects/my-app/todos \
  -H "Content-Type: application/json" \
  -d '{"title":"实现登录功能","priority":"high"}'

📚 相关文档

CCMage - AI 辅助开发系统

GitHub 仓库 • 问题反馈 • 社区讨论 • MIT License

Made with ❤️ by CCMage Contributors

© 2025 CCMage Project

📖 CCMage Wiki

🏠 首页

🚀 入门指南

💡 核心功能

📚 开发文档

🆘 帮助支持

版本: v1.2.1 更新: 2025-11-30

Clone this wiki locally