# 文本框任务域全文（llms-full）

> 一次拉取：任务 API 参考 + 全部 Task Skills。

---

# 文本框任务域 API 参考（Agent）

> 前缀一律 `/api/v1`。成功直接返回业务 JSON；错误为 `{ "code", "message" }`。

## 通用

| 项 | 约定 |
|----|------|
| 成功 | 直接业务 JSON |
| 错误 | `{ "code", "message" }` |
| 认证 | `Authorization: Bearer <jwt>` |
| 分页 | query `page`/`page_size` → `{ items, total, page, page_size }` |
| 任务 id | 路径中为 Sonyflake **字符串** |

### 任务 status（smallint）

| 值 | 含义 |
|----|------|
| 0 | 草稿（如悬赏待托管） |
| 1 | 招募中 / 待接单 |
| 2 | 已选标 |
| 3 | 进行中（已托管） |
| 4 | 待评价（全部验收通过） |
| 5 | 已完成 |
| 6 | 已关闭 |

## 1. 列表查看

### `GET /tasks`（公开）

Query: `page`, `page_size`, `category_id`, `status`, `type_id`（仅 1/2）, `budget_min`, `budget_max`, `keyword`。

行为: 排除 `source=employ`；进行中（status=1）优先，再 `created_at DESC`。

响应 `items[]` 含: `id`(string), `title`, `slug`, `description`, `budget`, `bounty`, `status`, `views`, `delivery_count`, `slot_count`, `category_id`, `created_at`，可选 `bounty_status` / `delivery_deadline` / `source`。

### `GET /tasks/{id}`（可选登录）

详情；带有效 Token 时可能含 `is_favorited`。雇佣任务同样走此路径（`source=employ`）。

### `GET /tasks/my` | `/tasks/my-bids` | `/tasks/my-accepted`（需登录）

我发布的 / 我投标的 / 我中标的。

### `GET /employ`（需登录）

雇佣列表。Query: `role=employer|worker|invited`, `status?`, `page`, `page_size`。

## 2. 创建 / 发布

### `POST /tasks`（需登录，常 201）

```json
{
  "title": "required",
  "category_id": 1,
  "budget": 100,
  "mode": "bid",
  "description": "optional",
  "delivery_deadline": "YYYY-MM-DD",
  "provider_count": 1,
  "skill_ids": [],
  "attachment_uuids": [],
  "pay_type": 1,
  "payment_method": "balance",
  "bounty_mode": "equal",
  "bounty_awards": [{ "winner_count": 1, "amount_per_person": 50 }]
}
```

- `mode`: `bid`（默认，招标）| `bounty`（悬赏）
- 悬赏须 `payment_method`（现仅 `balance`），金额 > 0
- `bounty_mode=custom` 时总金额 = Σ(winner_count × amount_per_person)

### `POST /employ`（需登录，常 201）

```json
{
  "provider_user_uuid": "required",
  "title": "required",
  "description": "required",
  "budget": 100,
  "delivery_deadline": "YYYY-MM-DD",
  "accept_deadline": "YYYY-MM-DD",
  "pay_type": 1
}
```

创建后须先托管，对方方可接单。

## 3. 接单

### `POST /tasks/{id}/bid`（需登录）

```json
{
  "price": 80,
  "description": "方案",
  "delivery_time": 7,
  "writer_intro": "optional",
  "pay_type": 1,
  "attachment_uuids": []
}
```

- 招标: `price` > 0
- 悬赏投稿: `price` 可为 0，`description` 必填
- `delivery_time` 必填 ≥1，最多一位小数

### `POST /employ/{taskId}/accept`（需登录）

仅 `bounty_status=1`（已托管）可接。拒单: `POST /employ/{taskId}/reject`。雇主取消: `POST /employ/{taskId}/cancel`。

## 4. 确认

### 选标 `POST /tasks/{id}/bids/{bidId}/select`（需登录，雇主）

可选 Body: `{ "award_sort_order": 1 }`（悬赏自定义奖项）。

拒标: `POST /tasks/{id}/bids/{bidId}/reject`。

### 交付验收

- 列表/提交: `GET|POST /tasks/{id}/bids/{bidId}/deliveries`
- 通过: `POST /tasks/{id}/bids/{bidId}/deliveries/{deliveryId}/accept`
- 驳回: `POST .../reject` Body `{ "feedback": "required" }`

提交交付 Body 例: `{ "section_index": 1, "content": "...", "attachment_uuids": [] }`。

## 5. 评价

### `POST /tasks/{id}/rate`（需登录）

前置: 任务 `status=4`；仅雇主与中标威客可互评。

```json
{
  "to_uid": 123,
  "comment": "optional",
  "speed_score": 5,
  "quality_score": 5,
  "attitude_score": 5
}
```

分数范围 1–5。双方评完后任务可变为 status=5。

## 相关 Skills

- [/ai/skills/task-list/SKILL.md](/ai/skills/task-list/SKILL.md)
- [/ai/skills/task-publish/SKILL.md](/ai/skills/task-publish/SKILL.md)
- [/ai/skills/task-accept/SKILL.md](/ai/skills/task-accept/SKILL.md)
- [/ai/skills/task-confirm/SKILL.md](/ai/skills/task-confirm/SKILL.md)
- [/ai/skills/task-rate/SKILL.md](/ai/skills/task-rate/SKILL.md)


---

---
name: task-list
description: >-
  查看文本框公开任务列表、任务详情、我的任务/投标/中标，以及雇佣列表。
  Use when the user asks to list, search, browse, or inspect tasks.
---

# task-list

## When to use

- 浏览任务大厅、按分类/关键词筛选
- 查看单个任务或雇佣详情
- 查看「我发布的 / 我投标的 / 我中标的 / 雇佣列表」

## Prerequisites

- 公开列表与详情：无需登录（详情可选登录）
- `/tasks/my*`、`/employ`：需要 `Authorization: Bearer <jwt>`

## Endpoints

Base: `/api/v1`

| Method | Path | Auth | Notes |
|--------|------|------|-------|
| GET | `/tasks` | 无 | 排除 `source=employ` |
| GET | `/tasks/{id}` | 可选 | id = Sonyflake string |
| GET | `/tasks/my` | JWT | Query: status?, page, page_size |
| GET | `/tasks/my-bids` | JWT | |
| GET | `/tasks/my-accepted` | JWT | |
| GET | `/employ` | JWT | Query: role=employer\|worker\|invited |

### `GET /tasks` query

`page`, `page_size`, `category_id`, `status`, `type_id` (1|2), `budget_min`, `budget_max`, `keyword`

### Response shape

`{ "items": [...], "total", "page", "page_size" }`

`items[]` 关键字段: `id`(string), `title`, `slug`, `description`, `budget`, `bounty`, `status`, `views`, `delivery_count`, `slot_count`, `category_id`, `created_at`, optional `bounty_status`, `delivery_deadline`, `source`.

## Workflow

1. 大厅浏览 → `GET /tasks?...`
2. 点进详情 → `GET /tasks/{id}`
3. 雇佣相关列表勿用 `/tasks`，改用 `GET /employ?role=...`

## Errors

- 404 `任务不存在`
- 401 未登录（my* / employ）

## Availability

- `GET /tasks` 公开列表可用
- 详情与「我的」类接口以实际响应字段为准
- 部分列表若返回空页或未实现错误，勿臆造数据，如实告知用户


---

---
name: task-publish
description: >-
  创建并发布招标/悬赏任务，或发起指定服务商的雇佣。
  Use when creating, publishing, or posting a task or hire request.
---

# task-publish

## When to use

- 雇主发布招标（bid）或悬赏（bounty）任务
- 雇主向指定服务商发起雇佣（employ）

## Prerequisites

- JWT 登录
- 悬赏发布需余额托管（`payment_method=balance`）
- 雇佣创建后须引导用户完成托管，对方才能接单

## Endpoints

Base: `/api/v1`

### `POST /tasks`（需登录，常 201）

```json
{
  "title": "标题",
  "category_id": 1,
  "budget": 100,
  "mode": "bid",
  "description": "需求说明",
  "delivery_deadline": "2026-12-31",
  "provider_count": 1,
  "skill_ids": [],
  "attachment_uuids": [],
  "pay_type": 1,
  "payment_method": "balance",
  "bounty_mode": "equal",
  "bounty_awards": []
}
```

| 字段 | 必填 | 说明 |
|------|------|------|
| title | 是 | |
| category_id | 是 | |
| budget | 是 | >0 元 |
| mode | 否 | `bid`(默认) \| `bounty` |
| payment_method | 悬赏必填 | 现仅 `balance` |
| bounty_mode | 否 | `equal` \| `custom` |
| bounty_awards | custom 时 | `{winner_count, amount_per_person}[]` |
| pay_type | 否 | 招标 1–4 |

### `POST /employ`（需登录，常 201）

```json
{
  "provider_user_uuid": "服务商 user uuid",
  "title": "标题",
  "description": "说明",
  "budget": 100,
  "delivery_deadline": "2026-12-31",
  "accept_deadline": "2026-12-01",
  "pay_type": 1
}
```

## Workflow

1. （可选）`GET /categories`、`GET /skill-categories` 取分类与技能
2. 大厅任务 → `POST /tasks`
3. 指定威客 → `POST /employ` → 再完成托管后再等待接单
4. 用返回的任务 id（Sonyflake 字符串）继续后续操作

## Errors

- 400 参数错误 / 悬赏金额无效 / mode 非法
- 401 未登录
- 服务暂不可用或未实现时，以响应 `message` 为准

## Availability

- 发布字段以上表为准；若服务端对部分可选字段尚未接受，勿强行臆造扩展字段重试
- `POST /employ` 若返回未实现类错误，如实告知用户，勿编造成功结果


---

---
name: task-accept
description: >-
  服务商对招标/悬赏任务投标或投稿，以及对雇佣邀请接单/拒单。
  Use when bidding, submitting a bounty entry, or accepting/rejecting a hire.
---

# task-accept

## When to use

- 服务商对公开任务投标（招标）或投稿（悬赏）
- 被邀请服务商接受或拒绝雇佣

## Prerequisites

- JWT；不能投自己的任务
- 任务须处于可投标状态（通常 `status=1`）
- 雇佣接单：仅当 `bounty_status=1`（雇主已托管）

## Endpoints

Base: `/api/v1`

### `POST /tasks/{id}/bid`（需登录）

```json
{
  "price": 80,
  "description": "方案或投稿说明",
  "delivery_time": 7,
  "writer_intro": "可选简介",
  "pay_type": 1,
  "attachment_uuids": []
}
```

| 规则 | 说明 |
|------|------|
| 招标 | `price` > 0 |
| 悬赏 | `price` 可为 0；`description` 必填 |
| delivery_time | 必填 ≥1，最多一位小数 |

### 雇佣

| Method | Path | 说明 |
|--------|------|------|
| POST | `/employ/{taskId}/accept` | 接单 → bid=selected，任务 status=2 |
| POST | `/employ/{taskId}/reject` | 拒单；已托管则退款给雇主，任务关闭 |
| POST | `/employ/{taskId}/cancel` | **雇主**取消（未托管等条件） |

`taskId` 为任务 Sonyflake 字符串。

## Workflow

1. `GET /tasks/{id}` 确认 status / type / source
2. 大厅任务 → `POST /tasks/{id}/bid`
3. `source=employ` → 确认已托管后 `POST /employ/{taskId}/accept`

## Errors

- 400 不能对自己的任务投标 / 当前不接受投标 / 未托管不可接单
- 401 未登录
- 404 任务不存在

## Availability

- 投标与雇佣接单/拒单/取消若返回未实现或业务错误，以 HTTP 响应为准，勿无限重试


---

---
name: task-confirm
description: >-
  雇主选标，以及对阶段交付进行验收通过或驳回。
  Use when selecting a winning bid or confirming/rejecting a delivery.
---

# task-confirm

## When to use

- 雇主从投标中选中服务商（选标）
- 雇主验收某阶段交付（通过 / 驳回并给修改建议）

## Prerequisites

- JWT；操作者须为任务雇主（验收场景）
- 选标前任务状态须允许选标
- 验收对象为已提交的 delivery

## Endpoints

Base: `/api/v1`

### 选标

| Method | Path | Body |
|--------|------|------|
| POST | `/tasks/{id}/bids/{bidId}/select` | 可选 `{ "award_sort_order": 1 }` |
| POST | `/tasks/{id}/bids/{bidId}/reject` | 拒标 |

悬赏自定义奖项选稿时，`award_sort_order` 为 1-based 奖项序号。

### 交付与验收

| Method | Path | Body |
|--------|------|------|
| GET | `/tasks/{id}/bids/{bidId}/deliveries` | — |
| POST | `/tasks/{id}/bids/{bidId}/deliveries` | `{ "section_index", "content", "attachment_uuids"? }`（威客提交） |
| POST | `/tasks/{id}/bids/{bidId}/deliveries/{deliveryId}/accept` | —（雇主确认通过） |
| POST | `/tasks/{id}/bids/{bidId}/deliveries/{deliveryId}/reject` | `{ "feedback": "必填" }` |

`section_index` 为 1-based 阶段序号。

## Workflow

1. 查看投标/交付 → 列表或详情接口
2. 选标 → `.../select` → 通常还需托管
3. 威客交付 → 雇主 `.../accept` 或 `.../reject`
4. 全部阶段验收通过后任务进入待评价（status=4）→ 使用 `task-rate`

## Errors

- 400 当前状态不允许选标 / feedback 必填
- 401 / 403 未登录或非雇主
- 404 任务或交付不存在

## Availability

- 选标、交付提交与验收若返回未实现或业务错误，以实际响应为准；勿假设资金已结算


---

---
name: task-rate
description: >-
  在任务全部阶段验收通过后，雇主与中标威客互评（速度/质量/态度 1–5 星）。
  Use when rating or reviewing a completed task after status=4.
---

# task-rate

## When to use

- 全部交付验收通过后给对方评价
- 用户说「评价任务 / 打分 / 互评」

## Prerequisites

- JWT
- 任务 `status=4`（待评价）
- 仅雇主或中标威客可评；不能评自己
- 同一对评价对象只能评一次

## Endpoints

Base: `/api/v1`

### `POST /tasks/{id}/rate`（需登录）

```json
{
  "to_uid": 123456,
  "comment": "可选评语",
  "speed_score": 5,
  "quality_score": 5,
  "attitude_score": 5
}
```

| 字段 | 必填 | 说明 |
|------|------|------|
| to_uid | 是 | 被评人内部 user id（雇主或中标威客） |
| speed_score | 是 | 1–5 |
| quality_score | 是 | 1–5 |
| attitude_score | 是 | 1–5 |
| comment | 否 | 文本 |

成功例: `{ "message": "评价成功", "task_status": 5 }`（双方都评完时可能更新为 5）。

## Workflow

1. `GET /tasks/{id}` 确认 `status=4` 与对方身份
2. 组装 `to_uid` 与三维度分数
3. `POST /tasks/{id}/rate`
4. 若仍 status=4，提示等待对方评价

## Errors

- 400 仅全部验收后可评价 / 已评价过 / 不能对自己评价 / 分数越界
- 403 非雇主且非中标威客
- 401 未登录
- 404 任务不存在

## Availability

- 评价接口若返回未实现或业务错误，以 HTTP 响应为准，勿伪造评价成功

