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

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"]}'

返回示例：

{
  "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 模板：

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

curl 命令：

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

返回值：

{
  "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. 查询工单

# 查看所有开放工单
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. 修改工单

# 修改标题、内容、指派人
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. 关闭工单

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. 添加评论

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 先写入文件

# 错误写法
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。

# 先查有哪些 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

---

批量创建脚本

#!/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