aiagent/docs/使用平台创建工单的方法.md

# 使用平台创建工单的方法

> 平台：Gitea 1.25.2 · 仓库：admin/aiagent · 地址：http://101.43.95.130:3001

---

## 前置准备

### 账号信息

| 项 | 值 |
|----|-----|
| 地址 | http://101.43.95.130:3001 |
| 用户名 | admin |
| 密码 | 123456 |
| 仓库 | admin/aiagent |
| 分支 | rjb_win_dev |

### 获取 API Token

```bash
curl -s -X POST "http://101.43.95.130:3001/api/v1/users/admin/tokens" \
  -u "admin:123456" \
  -H "Content-Type: application/json" \
  -d '{"name":"claude-code-api","scopes":["write:issue","write:repository","read:repository","read:user"]}'
```

返回示例：

```json
{
  "id": 3,
  "name": "claude-code-api",
  "sha1": "fbc9ee7f96635793f4844187eac5c0e573480721",
  "token_last_eight": "73480721",
  "scopes": ["write:issue", "write:repository", "read:user"]
}
```

**Token**：`fbc9ee7f96635793f4844187eac5c0e573480721`

### Token 管理

- 查看已有 Token：登录 Gitea → 头像 → 设置 → 应用 → 管理 Access Token
- 权限最小化原则：创建工单只需要 `write:issue` + `read:repository`

---

## 工单 CRUD

### 1. 创建工单

**端点**：`POST /api/v1/repos/{owner}/{repo}/issues`

**JSON 模板**：

```json
{
  "title": "[类别] 标题",
  "body": "## 背景\n\n...\n\n## 需求\n\n1. ...\n2. ...\n\n## 涉及模块\n\n- 文件路径\n\n## 优先级\n\n高/中/低",
  "assignee": "admin",
  "milestone": null
}
```

**curl 命令**：

```bash
TOKEN="fbc9ee7f96635793f4844187eac5c0e573480721"

# 方式一：直接传 JSON（仅英文/简单内容）
curl -s -X POST "http://101.43.95.130:3001/api/v1/repos/admin/aiagent/issues" \
  -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"测试工单","body":"内容","assignee":"admin"}'

# 方式二：从文件读取（推荐，支持中文/长文本）
curl -s -X POST "http://101.43.95.130:3001/api/v1/repos/admin/aiagent/issues" \
  -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @/tmp/issue.json
```

**返回值**：

```json
{
  "id": 19,
  "url": "http://101.43.95.130:3001/api/v1/repos/admin/aiagent/issues/1",
  "html_url": "http://101.43.95.130:3001/admin/aiagent/issues/1",
  "number": 1,
  "title": "...",
  "state": "open",
  "assignee": { "login": "admin" },
  "created_at": "2026-05-04T22:44:20+08:00"
}
```

### 2. 查询工单

```bash
# 查看所有开放工单
curl -s "http://101.43.95.130:3001/api/v1/repos/admin/aiagent/issues?state=open" \
  -H "Authorization: token $TOKEN"

# 查看单个工单
curl -s "http://101.43.95.130:3001/api/v1/repos/admin/aiagent/issues/1" \
  -H "Authorization: token $TOKEN"
```

### 3. 修改工单

```bash
# 修改标题、内容、指派人
curl -s -X PATCH "http://101.43.95.130:3001/api/v1/repos/admin/aiagent/issues/1" \
  -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"新标题","body":"新内容","assignee":"admin"}'
```

### 4. 关闭工单

```bash
curl -s -X PATCH "http://101.43.95.130:3001/api/v1/repos/admin/aiagent/issues/1" \
  -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"state":"closed"}'
```

### 5. 添加评论

```bash
curl -s -X POST "http://101.43.95.130:3001/api/v1/repos/admin/aiagent/issues/1/comments" \
  -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body":"已修复，请验证。"}'
```

---

## 工单标题规范

建议使用 `[类别]` 前缀区分工单类型：

| 前缀 | 用途 | 示例 |
|------|------|------|
| `[Bug]` | 缺陷修复 | `[Bug] SSE 流式降级导致重复空消息` |
| `[Phase N]` | 按阶段规划 | `[Phase 4] 降级/回退链` |
| `[监控]` | 监控告警 | `[监控] 系统监控面板` |
| `[DevOps]` | 运维基础设施 | `[DevOps] Docker 生产环境配置` |
| `[UX]` | 用户体验 | `[UX] 工作流画布自动布局` |
| `[高级]` | 差异化功能 | `[高级] 插件系统` |
| `[质量]` | 测试与安全 | `[质量] 单元测试覆盖率提升` |
| `[Agent]` | Agent 能力 | `[Agent] 多模态 Agent` |

---

## 踩坑记录

### 坑1：中文 JSON 编码异常

**现象**：curl 的 `-d` 参数直接写中文 JSON 返回 `json: slice unexpected end of JSON input`

**原因**：shell 对中文和特殊字符的处理不一致

**解决**：改用 `--data-binary @文件路径`，将 JSON 先写入文件

```bash
# 错误写法
curl -d '{"title":"中文标题",...}' ...

# 正确写法
echo '{"title":"中文标题",...}' > /tmp/issue.json
curl --data-binary @/tmp/issue.json ...
```

### 坑2：labels 参数格式

Gitea 的 labels 必须传数字 ID（如 `[1, 2]`），不能传字符串名（如 `["bug"]`）。如果不确定 label ID，先查或不传 labels。

```bash
# 先查有哪些 labels
curl -s "http://101.43.95.130:3001/api/v1/repos/admin/aiagent/labels" \
  -H "Authorization: token $TOKEN"
```

### 坑3：body 中的特殊字符

JSON body 中不要使用：
- 中文双引号 `""` → 改用书名号 `「」` 或省略
- 反引号 `` ` `` → JSON 中需要转义为 `\``
- 未转义的换行 → JSON 中换行用 `\n`

---

## 批量创建脚本

```bash
#!/bin/bash
TOKEN="你的token"
REPO_URL="http://101.43.95.130:3001/api/v1/repos/admin/aiagent/issues"

# 准备多个 JSON 文件
# /tmp/issues/01.json, /tmp/issues/02.json, ...

for f in /tmp/issues/*.json; do
  num=$(basename "$f" .json)
  result=$(curl -s -X POST "$REPO_URL" \
    -H "Authorization: token $TOKEN" \
    -H "Content-Type: application/json" \
    --data-binary @"$f" | grep -o '"number":[0-9]*')
  echo "  $num → $result"
done
```

---

## API 参考

| 操作 | 方法 | 路径 |
|------|------|------|
| 创建 | POST | `/api/v1/repos/{owner}/{repo}/issues` |
| 列表 | GET | `/api/v1/repos/{owner}/{repo}/issues?state=open` |
| 详情 | GET | `/api/v1/repos/{owner}/{repo}/issues/{id}` |
| 修改 | PATCH | `/api/v1/repos/{owner}/{repo}/issues/{id}` |
| 评论 | POST | `/api/v1/repos/{owner}/{repo}/issues/{id}/comments` |

完整 API 文档：[http://101.43.95.130:3001/api/swagger](http://101.43.95.130:3001/api/swagger)