# 提交工单 GitHub Issue 创建请求

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

将已核对的草稿排队创建外部 Issue；收到202后需回查工单中的 GitHub 状态。

```text
POST https://api.moi.matrixorigin.cn/v5/admin/feedback-tickets/{id}/github-issue
```

## 调用前准备

准备当前环境可用的 Genesis 管理员 Bearer；普通个人访问令牌、X-API-Key 和工作区 Owner 不能替代。会话模式的写操作另需 CSRF。参见[AI Studio](../../../../../developer/api/ai-studio/index.md)。示例 ID 需换为获准查看的真实工单 ID。

会触发后续对外创建，真实验证须另有明确的外部发布授权。已有 created 返回原结果；pending/creating 拒绝重复，failed 需 retry:true。输入合法性和敏感内容检测在已有结果返回前仍会执行。列表可用标志只由配置决定，实际执行身份、绑定和工具仍需验证。

## 请求参数

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/admin/feedback-tickets/ticket-example/github-issue" \
  -H "Authorization: Bearer $GENESIS_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"kind":"bug","title":"示例问题","body":"已核对的问题描述。","retry":false}'
```

:::::
:::::{tab-item} 参数说明

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `Authorization` | string | Bearer示例是 | Bearer 加当前环境可信管理员令牌；不要同时设置 API Key。 |
| `id` | string | 是 | 路径工单 ID。 |
| `kind` | string | 是 | bug、feature 或 auto，表示创建策略。 |
| `title` | string | 是 | 去前后空白后非空，最多256个 Unicode 码点。 |
| `body` | string | 是 | 移除旧反馈标记、trim并附加当前标记后非空，最终最多65536个 Unicode 码点。 |
| `retry` | boolean | 否 | 默认false；只有失败请求允许显式重试，重新冻结内容并生成新 request_id。 |

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": 0,
  "data": {
    "ticket_id": "ticket-example",
    "kind": "bug",
    "status": "pending",
    "draft_title": "示例问题",
    "draft_body": "已核对的问题描述。\n\n<!-- matrixflow-feedback-ticket:ticket-example -->",
    "request_id": "request-example",
    "requested_by": "admin-example",
    "attempt_count": 0,
    "last_attempt_at": null,
    "issue_number": null,
    "issue_url": null,
    "created_by": "",
    "issue_created_at": null,
    "last_error_code": "",
    "created_at": "2026-11-12T04:00:00Z",
    "updated_at": "2026-11-12T04:00:00Z"
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | integer | 成功为数字 0。 |
| `data` | object | 新排队或已有创建结果。HTTP 为202，不能仅据状态码判断是新请求。 |
| `data.ticket_id` | string | 关联工单 ID。 |
| `data.kind` | string | bug、feature 或 auto；创建策略，不等同最终 GitHub Type。 |
| `data.status` | string | pending、creating、created 或 failed；与工单 status 独立。 |
| `data.draft_title` | string | 已冻结的请求标题。 |
| `data.draft_body` | string | 已冻结且规范化的请求正文。 |
| `data.request_id` | string | 本次创建尝试标识；重试可产生新值。 |
| `data.requested_by` | string | 请求创建的管理员主体。 |
| `data.attempt_count` | integer | 对应异步处理尝试次数。 |
| `data.last_attempt_at` | string / null | 最近尝试时间；未发生时为 null。 |
| `data.issue_number` | integer / null | 创建回执中的 Issue 编号，未创建时为 null。 |
| `data.issue_url` | string / null | 创建回执中的 Issue 地址，未创建时为 null。 |
| `data.created_by` | string | 创建成功时记录的请求者主体，未完成可为空字符串。 |
| `data.issue_created_at` | string / null | 收到创建回执的时间，未完成时为 null。 |
| `data.last_error_code` | string | 安全错误代码；未发生可为空字符串。 |
| `data.created_at` | string | 创建时间，RFC 3339。 |
| `data.updated_at` | string | 更新时间，RFC 3339。 |

嵌套工单、用户、消息、审批事实和 GitHub 请求的全部公开字段见[公共对象](objects.md)。字段可空与可省略分别列明，不把旧 SDK fixture 的 submitter_email 当作当前字段。
:::::
::::::
:::::::

## 错误响应

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{"code":"Unauthorized","msg":"Unauthorized"}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string / integer | 随失败阶段而异；示例为认证层字符串。 |
| `msg` | string | 认证或服务层失败文本，服务层通常本地化。 |
| `message` | string | 参数解析阶段数字错误码的文本；与 msg 区分。 |
| `data` | null | 当前服务层 responseEnvelope 错误保留 null；认证示例可不含此字段。 |
| `details` | object | 文本字段 422 错误可带 field/reason 等，见错误说明。 |

| HTTP / code | 条件与处理 |
| --- | --- |
| 401 / Unauthorized | 认证层拒绝；不要使用普通 PAT 或同时带 X-API-Key。 |
| 403 / ErrForbidden | 未取得可信管理员事实，或当前调用身份与管理员事实不匹配。 |
| 404 / ErrFeedbackTicketNotFound | 目标工单不存在；当前 service 错误返回 code/msg/data:null。 |
| 503 / ErrServiceUnavailable | 已分类的身份、目录、授权依赖不可用或网络超时。 |
| 500 / ErrServer | 内部处理或本地化失败；写请求错误后先回读确认。 |
| 409 / ErrFeedbackGitHubIssueInProgress | 请求仍pending/creating，回查原 request_id，不重复提交。 |
| 409 / ErrFeedbackGitHubIssueRetryRequired | 已失败且未显式 retry。 |
| 409 / ErrFeedbackGitHubIssueSensitiveContent | 提交内容命中敏感检测，修改后重新人工核对。 |
| 503 / ErrFeedbackGitHubIssueCreatorUnavailable | 新请求未配置创建工作区。 |
| 403 / ErrFeedbackGitHubIssueForbidden | 入队准备或执行身份被拒绝。 |
| 422 / ErrFieldRequired 或 ErrFieldTooLong | 最终标题/正文为空或超长；不是通用草稿400。 |

完整错误族与各阶段见[错误和恢复](errors-recovery.md)。
:::::
::::::
:::::::
