feat: add AI学习助手 agent (KG+RAG ideal) and renshenguo feishu bot
- Add AI学习助手 agent creation script with all 39 tools, 3-layer KG+RAG memory - Add renshenguo (人参果) feishu bot integration (app_service + ws_handler) - Register renshenguo WS client in main.py startup - Add RENSHENGUO_APP_ID / RENSHENGUO_APP_SECRET / RENSHENGUO_AGENT_ID config - Reorganize docs from root into docs/ subdirectories - Move startup scripts to scripts/startup/ - Various backend optimizations and tool improvements Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
renjianbo
228
docs/使用平台创建工单的方法.md
Normal file
228
docs/使用平台创建工单的方法.md
Normal file
@@ -0,0 +1,228 @@
|
||||
# 使用平台创建工单的方法
|
||||
|
||||
> 平台：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)
|
||||
Reference in New Issue
Block a user