Task-Pie Agent 任务管理技能

Task-Pie 是一个 Agent CLI 任务调度系统，允许你通过 API 创建和管理任务，由后端的 Client 执行任务。

系统概述

• Server: FastAPI 后端，默认端口 8100
• Web Frontend: React SPA 前端界面
• Client: Python 客户端，轮询并执行任务
• 支持的 Agent: Claude Code、OpenCode

核心概念

Project（项目）

项目是任务的容器，关联一个 Git 仓库。

{
  "id": "uuid",
  "name": "项目名称",
  "repo_url": "https://github.com/user/repo.git",
  "branch": "main",
  "work_dir": "~/workspace/project",
  "client_id": "绑定的客户端ID（可选）"
}

Task（任务）

任务是具体的执行单元。

{
  "id": "uuid",
  "name": "任务名称",
  "project_id": "项目ID",
  "prompt": "任务指令",
  "agent_type": "claude_code | opencode",
  "model": "模型名称（可选）",
  "priority": 0,  // 数字越大优先级越高
  "timeout": 3600,  // 超时时间（秒）
  "auto_commit": true,  // 自动 commit
  "auto_push": false,   // 自动 push
  "status": "pending | running | completed | failed"
}

Client（客户端）

客户端执行任务。

{
  "id": "uuid",
  "name": "客户端名称",
  "token": "认证token",
  "status": "online | offline | busy",
  "supported_agents": "支持的agent类型JSON"
}

API 接口

基础 URL

http://localhost:8100/api

项目管理

创建项目

POST /projects
{
  "name": "我的项目",
  "repo_url": "https://github.com/user/repo.git",
  "branch": "main",
  "work_dir": "~/projects/my-project",
  "client_id": "客户端ID（可选）"
}

获取项目列表

GET /projects

获取单个项目

GET /projects/{id}

更新项目

PUT /projects/{id}
{
  "name": "新名称",
  "branch": "develop"
}

删除项目

DELETE /projects/{id}

任务管理

创建任务

POST /tasks
{
  "name": "修复登录bug",
  "project_id": "项目ID",
  "prompt": "请修复登录页面的bug，用户反馈无法登录",
  "agent_type": "opencode",
  "model": "aliyunbailian/glm-5",
  "priority": 5,
  "timeout": 3600,
  "auto_commit": true,
  "auto_push": false
}

获取任务列表

GET /tasks
GET /tasks?status=pending
GET /tasks?project_id=xxx

获取单个任务

GET /tasks/{id}

更新任务

PUT /tasks/{id}
{
  "status": "pending",  // 重试失败的任务
  "priority": 10
}

删除任务

DELETE /tasks/{id}

客户端管理

获取客户端列表

GET /clients

注册客户端

POST /clients
{
  "name": "my-client",
  "supported_agents": "{\"opencode\": [\"aliyunbailian/glm-5\", \"gpt-4\"], \"claude_code\": []}"
}

执行历史

获取执行历史

GET /history
GET /history?task_id=xxx
GET /history?client_id=xxx

任务执行流程

1. 创建项目，配置 Git 仓库
2. 创建任务，指定项目、prompt、agent 类型
3. Client 轮询到任务，拉取代码
4. Agent CLI（如 OpenCode）执行任务
5. 执行完成后自动 commit/push（如果配置）
6. 结果保存到执行历史

常见任务场景

场景 1：创建一个代码修改任务

# 1. 先创建项目
curl -X POST http://localhost:8100/api/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "task-pie",
    "repo_url": "https://github.com/user/task-pie.git",
    "branch": "main"
  }'

# 2. 创建任务
curl -X POST http://localhost:8100/api/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "name": "添加用户登录功能",
    "project_id": "<项目ID>",
    "prompt": "请在 web/src/pages/ 目录下创建 Login.tsx 页面，实现用户登录功能。要求：\n1. 使用 React hooks\n2. 表单验证\n3. 错误提示",
    "agent_type": "opencode",
    "model": "aliyunbailian/glm-5",
    "priority": 5,
    "timeout": 3600,
    "auto_commit": true,
    "auto_push": false
  }'

场景 2：重试失败的任务

# 更新状态为 pending
curl -X PUT http://localhost:8100/api/tasks/{task_id} \
  -H "Content-Type: application/json" \
  -d '{"status": "pending"}'

场景 3：查看执行结果

# 查看执行历史
curl http://localhost:8100/api/history

# 查看特定任务的执行历史
curl http://localhost:8100/api/history?task_id={task_id}

Prompt 编写最佳实践

好的 Prompt 示例

请在 web/src/components/ 目录下创建一个 SearchBar.tsx 组件。

要求：
1. 支持实时搜索，防抖 300ms
2. 支持键盘快捷键 Cmd+K 聚焦
3. 搜索结果下拉展示
4. 使用 Tailwind CSS 样式
5. 导出为默认组件

参考现有组件风格：web/src/components/Button.tsx

避免

• 模糊的指令："优化一下代码"
• 缺少上下文："添加这个功能"
• 过大的范围："重构整个项目"

注意事项

1. 超时时间：默认 60 分钟，复杂任务适当增加
2. 并发限制：同一项目同时只能执行一个任务
3. 优先级：数字越大优先级越高，默认 0
4. 自动提交：建议开启 auto_commit，关闭 auto_push（人工确认后 push）
5. 模型选择：根据任务复杂度选择合适的模型

Webhook 通知（计划中）

未来将支持任务完成后的 Webhook 通知。

错误处理

任务执行失败后：

1. 查看 /history 获取错误日志
2. 修复问题或调整 prompt
3. 更新任务状态为 pending 重试