工单
记录需求、明确责任，并持续补充处理进展。
工单协作
发布时允许只有附件；文字最多 50,000 字符，每次最多 10 个附件、总计最多 50MB。先上传附件，再把返回的 id 放入 attachmentIds。
状态为 OPEN（待处理）、IN_PROGRESS（处理中）、DONE（已完成）。assigneeId 使用成员接口返回的用户 ID，省略表示未分配；assign 时省略可清空负责人。
只有创建者或管理员可以编辑原始内容。详情返回按时间排序的 events 与附件；附件下载始终携带 Bearer Key。
接口参考
查询工单列表
/api/v1/workspaces/{workspaceId}/tickets
响应 data 字段（列表元素）
- id
- 工单 ID
- content
- 需求原始内容
- status
- OPEN / IN_PROGRESS / DONE / CANCELLED
- creatorId
- 创建者 ID
- assigneeId
- 负责人 ID，可为空
- createdAt
- 创建时间 ISO 8601
- updatedAt
- 更新时间 ISO 8601
- attachments
- 原始内容附件，含 id、name、mimeType、size、downloadUrl
- events
- 仅详情：跟进与操作事件，含 id、kind、actorId、content、createdAt、attachments
curl --request GET "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/tickets" \
--header "Authorization: Bearer $AGENT_API_KEY"成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
查询工单详情
/api/v1/workspaces/{workspaceId}/tickets/{id}
响应 data 字段
- id
- 工单 ID
- content
- 需求原始内容
- status
- OPEN / IN_PROGRESS / DONE / CANCELLED
- creatorId
- 创建者 ID
- assigneeId
- 负责人 ID，可为空
- createdAt
- 创建时间 ISO 8601
- updatedAt
- 更新时间 ISO 8601
- attachments
- 原始内容附件，含 id、name、mimeType、size、downloadUrl
- events
- 仅详情：跟进与操作事件，含 id、kind、actorId、content、createdAt、attachments
curl --request GET "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/tickets/{id}" \
--header "Authorization: Bearer $AGENT_API_KEY"成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
发布工单
/api/v1/workspaces/{workspaceId}/tickets
| 参数 | 类型 | 说明 |
|---|---|---|
| content | string | 沿用业务表单规则 |
| attachmentIds | array | 沿用业务表单规则 |
| assigneeId | string | 沿用业务表单规则 |
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request POST "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/tickets" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{"content":"请跟进首页文案调整"}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
编辑原始内容
/api/v1/workspaces/{workspaceId}/tickets/{id}
| 参数 | 类型 | 说明 |
|---|---|---|
| content | string | 沿用业务表单规则 |
| attachmentIds | array | 沿用业务表单规则 |
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request PATCH "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/tickets/{id}" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{"content":"请跟进首页文案调整"}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
补充跟进
/api/v1/workspaces/{workspaceId}/tickets/{id}/comments
| 参数 | 类型 | 说明 |
|---|---|---|
| content | string | 沿用业务表单规则 |
| attachmentIds | array | 沿用业务表单规则 |
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request POST "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/tickets/{id}/comments" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{"content":"请跟进首页文案调整"}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
转派负责人
/api/v1/workspaces/{workspaceId}/tickets/{id}/assign
| 参数 | 类型 | 说明 |
|---|---|---|
| assigneeId | string | 沿用业务表单规则 |
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request POST "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/tickets/{id}/assign" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
认领工单
/api/v1/workspaces/{workspaceId}/tickets/{id}/claim
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request POST "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/tickets/{id}/claim" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
调整状态
/api/v1/workspaces/{workspaceId}/tickets/{id}/status
| 参数 | 类型 | 说明 |
|---|---|---|
| status* | string | OPEN / IN_PROGRESS / DONE / CANCELLED |
响应 data 字段
- id
- 目标业务记录 ID（有对应记录时返回）
- message
- 处理结果
- tag
- 新增标签时返回 { id, name, archivedAt, createdAt, updatedAt }
curl --request POST "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/tickets/{id}/status" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--header "Content-Type: application/json" \
--data '{"status":"OPEN"}'成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。
上传附件
/api/v1/workspaces/{workspaceId}/tickets/attachments
响应 data 字段
- id
- 附件 ID
- objectKey
- 存储引用
- name
- 文件名
- mimeType
- MIME 类型
- size
- 字节数
- downloadUrl
- 需要 Bearer Key 的相对下载地址
- attachmentKey
- 跟进或收支所用的附件引用
- attachmentName
- 附件名称
- attachmentSize
- 字节数字符串
- attachmentMimeType
- MIME 类型
- media
- 仅交流上传：用于发布时关联的媒体对象
curl --request POST "$XGD_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/tickets/attachments" \
--header "Authorization: Bearer $AGENT_API_KEY" \
--header "Idempotency-Key: $REQUEST_KEY" \
--form "file=@./example.png"成功返回 { data, meta?, requestId }。权限、字段类型与错误处理见本页业务说明及错误与重试。