> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profy.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 任务生命周期、Agent 分发与付费查看

> Profy 任务编排体系说明：用户任务从创建、提交、Agent 分发到结果交付的完整生命周期，包含回调处理与付费查看结果的计费模型。

# 任务调度

Profy 的任务系统是连接用户需求和 AI Agent 能力的核心调度层。用户从市场选择应用、填写参数、提交任务，系统自动分发给 Agent 执行，用户付费后查看完整结果。

## 概述

```mermaid theme={null}
graph LR
    Create["创建任务"] --> Submit["提交执行"]
    Submit --> Agent["Agent 处理"]
    Agent --> Result["生成结果"]
    Result --> Pay["付费查看"]

    style Create fill:#dbeafe,stroke:#3b82f6
    style Submit fill:#fef3c7,stroke:#f59e0b
    style Agent fill:#e8faf0,stroke:#10b981
    style Pay fill:#fee2e2,stroke:#ef4444
```

## 任务生命周期

```mermaid theme={null}
stateDiagram-v2
    [*] --> Created: 创建任务
    Created --> Submitted: 提交参数
    Submitted --> Processing: Agent 开始执行
    Processing --> Completed: 执行完成
    Completed --> Paid: 用户付费
    Processing --> Failed: 执行失败

    Paid --> [*]
    Failed --> Submitted: 重新提交
```

### 状态说明

| 状态      | 标识           | 说明                |
| ------- | ------------ | ----------------- |
| **已创建** | `created`    | 任务已创建，等待用户填写参数    |
| **已提交** | `submitted`  | 参数已提交，等待 Agent 调度 |
| **执行中** | `processing` | Agent 正在处理任务      |
| **已完成** | `completed`  | Agent 执行完成，结果预览可见 |
| **已支付** | `paid`       | 用户已付费，完整结果可见      |
| **失败**  | `failed`     | 执行失败，可重新提交        |

## 核心流程

### 创建任务

用户在市场选择应用后，创建关联该应用的任务。

```json theme={null}
// POST /api/task/create
{
  "appUuid": "app-xxxxx",
  "title": "我的翻译任务"
}
```

### 提交执行

填写应用定义的输入参数后提交任务，系统自动调度 Agent 执行。

```json theme={null}
// POST /api/task/submit
{
  "taskId": "task-xxxxx",
  "params": {
    "text": "Hello, world!",
    "targetLang": "zh"
  }
}
```

提交后，Core API 通过 `agent-invoke` 服务将任务分发到外部 Agent 系统（如 MindSynth/Lingda），并异步等待回调。

### Agent 回调

Agent 执行完成后，通过内部回调通知结果：

```json theme={null}
// POST /internal/task/callback
{
  "taskId": "task-xxxxx",
  "status": "completed",
  "resultPreview": "翻译结果预览...",
  "resultFull": "完整翻译内容...",
  "costCredits": 50
}
```

### 付费查看

用户查看结果预览后，付费解锁完整结果：

```json theme={null}
// POST /api/task/pay
{
  "taskId": "task-xxxxx"
}
```

付费操作从用户积分账户扣除 `costCredits` 金额，扣费成功后 `payStatus` 更新为 `paid`。

## 付费查看模型

```mermaid theme={null}
sequenceDiagram
    participant U as 用户
    participant W as Web
    participant C as Core API

    U->>W: 查看任务列表
    W->>C: POST /api/task/list
    C-->>W: 任务列表（含状态）

    U->>W: 查看已完成任务
    W->>C: POST /api/task/result {taskId}
    C-->>W: resultPreview（免费预览）

    U->>W: 付费查看完整结果
    W->>C: POST /api/task/pay {taskId}
    C->>C: 扣除积分 (costCredits)
    C-->>W: 支付成功

    W->>C: POST /api/task/result {taskId}
    C-->>W: resultFull（完整内容）
    W-->>U: 展示完整结果
```

**设计要点：**

* 结果分为 `resultPreview`（免费预览）和 `resultFull`（付费内容）
* 未付费时只返回预览，付费后返回完整结果
* 积分扣费通过 `requestId` 保证幂等性

## 任务管理

| 方法   | 路径                 | 说明             |
| ---- | ------------------ | -------------- |
| POST | `/api/task/list`   | 分页任务列表（支持筛选状态） |
| POST | `/api/task/rename` | 重命名任务          |
| POST | `/api/task/pin`    | 置顶/取消置顶        |
| POST | `/api/task/delete` | 删除任务           |
| POST | `/api/task/result` | 查看任务结果         |

## API 接口汇总

| 方法   | 路径                 | 说明     | 认证 |
| ---- | ------------------ | ------ | -- |
| POST | `/api/task/create` | 创建任务   | 需要 |
| POST | `/api/task/submit` | 提交任务执行 | 需要 |
| POST | `/api/task/list`   | 任务列表   | 需要 |
| POST | `/api/task/result` | 查看结果   | 需要 |
| POST | `/api/task/pay`    | 付费解锁   | 需要 |
| POST | `/api/task/rename` | 重命名    | 需要 |
| POST | `/api/task/pin`    | 置顶     | 需要 |
| POST | `/api/task/delete` | 删除     | 需要 |

## 文件系统

任务可关联文件（输入附件或输出结果），文件通过 S3 对象存储管理：

| 方法     | 路径                             | 说明   |
| ------ | ------------------------------ | ---- |
| POST   | `/api/file/upload`             | 上传文件 |
| GET    | `/api/file/download/:fileUuid` | 下载文件 |
| DELETE | `/api/file/:fileUuid`          | 删除文件 |

每个文件拥有唯一 `fileUuid`，通过 `fileInfos` 表记录元信息（文件名、大小、MIME 类型、关联任务）。

## 相关链接

<CardGroup cols={2}>
  <Card title="应用市场" icon="store" href="/zh/documentation/marketplace">
    从市场发现应用，发起任务
  </Card>

  <Card title="金融支付" icon="credit-card" href="/zh/documentation/finance">
    任务付费的积分扣费机制
  </Card>
</CardGroup>