ADD file via upload
This commit is contained in:
parent
23295411b7
commit
97d6dbdf6f
|
|
@ -0,0 +1,212 @@
|
|||
# 会话状态与待处理问题接口指南
|
||||
|
||||
## 概述
|
||||
|
||||
本指南描述两个透明转发接口，用于查询 opencode serve 中指定工作目录的会话状态和待处理问题。
|
||||
|
||||
---
|
||||
|
||||
## 接口列表
|
||||
|
||||
### 1. 获取会话状态
|
||||
|
||||
```
|
||||
GET /api/v1/sessions/status?context_dir={context_dir}
|
||||
```
|
||||
|
||||
**功能**：查询指定目录下的会话状态（如 busy/idle）
|
||||
|
||||
**请求参数**：
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `context_dir` | string | 是 | 相对路径，格式 `{org}/{repo}/{sub}`，如 `test-workspace-org-dev/wjdcsgzqgongzuoqu/ui` |
|
||||
|
||||
**路径拼接逻辑**：
|
||||
|
||||
```
|
||||
完整路径 = WORKSPACE_ROOT + "/" + WORKSPACE_SUBDIR + "/" + context_dir
|
||||
|
||||
示例：
|
||||
context_dir = "test-workspace-org-dev/wjdcsgzqgongzuoqu/ui"
|
||||
完整路径 = "/app/opencode_workspace/superDS/test-workspace-org-dev/wjdcsgzqgongzuoqu/ui"
|
||||
```
|
||||
|
||||
**响应示例**：
|
||||
|
||||
```json
|
||||
{
|
||||
"ses_174a39718ffefSTO0iGL2x53z2": {
|
||||
"type": "busy"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| 顶层 key | opencode serve 的 session ID（`ses_xxx` 格式） |
|
||||
| `type` | 会话状态，`busy` 表示繁忙，`idle` 表示空闲 |
|
||||
|
||||
---
|
||||
|
||||
### 2. 获取待处理问题列表
|
||||
|
||||
```
|
||||
GET /api/v1/sessions/questions?context_dir={context_dir}
|
||||
```
|
||||
|
||||
**功能**：查询指定目录下所有会话中待处理的 question.asked 问题
|
||||
|
||||
**请求参数**：
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `context_dir` | string | 是 | 相对路径，格式 `{org}/{repo}/{sub}` |
|
||||
|
||||
**响应示例**：
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": "que_e8b5c7bcf001DX2OaE30cayS12",
|
||||
"sessionID": "ses_174a39718ffefSTO0iGL2x53z2",
|
||||
"questions": [
|
||||
{
|
||||
"question": "你今天想让我帮你做什么？",
|
||||
"header": "任务目标",
|
||||
"options": [
|
||||
{
|
||||
"label": "修复 Bug",
|
||||
"description": "修复代码中的错误或问题"
|
||||
},
|
||||
{
|
||||
"label": "添加新功能",
|
||||
"description": "为项目添加新的功能或特性"
|
||||
}
|
||||
],
|
||||
"multiple": false
|
||||
},
|
||||
{
|
||||
"question": "这个任务的优先级是？",
|
||||
"header": "优先级",
|
||||
"options": [
|
||||
{ "label": "高", "description": "需要立即处理" },
|
||||
{ "label": "中", "description": "尽快处理但不是紧急" },
|
||||
{ "label": "低", "description": "有空时处理即可" }
|
||||
],
|
||||
"multiple": false
|
||||
}
|
||||
],
|
||||
"tool": {
|
||||
"messageID": "msg_e8b5c6915001kFzcZgCmE5Ualq",
|
||||
"callID": "call_bb0d4610f7084cd493164a15"
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**响应字段说明**：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `id` | 问题请求 ID（`que_xxx` 格式），用于回复或拒绝 |
|
||||
| `sessionID` | 关联的 opencode serve 会话 ID |
|
||||
| `questions` | 问题数组，每个问题包含： |
|
||||
| `questions[].question` | 问题文本 |
|
||||
| `questions[].header` | 问题分组标题 |
|
||||
| `questions[].options` | 选项数组 |
|
||||
| `questions[].options[].label` | 选项显示文本 |
|
||||
| `questions[].options[].description` | 选项描述 |
|
||||
| `questions[].multiple` | 是否多选 |
|
||||
| `tool` | 调用上下文信息 |
|
||||
|
||||
---
|
||||
|
||||
## 前端调用示例
|
||||
|
||||
```javascript
|
||||
async function getSessionStatus(contextDir) {
|
||||
const response = await fetch(
|
||||
`/api/v1/sessions/status?context_dir=${encodeURIComponent(contextDir)}`
|
||||
);
|
||||
return response.json();
|
||||
}
|
||||
|
||||
async function getPendingQuestions(contextDir) {
|
||||
const response = await fetch(
|
||||
`/api/v1/sessions/questions?context_dir=${encodeURIComponent(contextDir)}`
|
||||
);
|
||||
return response.json();
|
||||
}
|
||||
|
||||
// 使用示例
|
||||
const org = 'test-workspace-org-dev';
|
||||
const repo = 'wjdcsgzqgongzuoqu';
|
||||
const sub = 'ui';
|
||||
const contextDir = `${org}/${repo}/${sub}`;
|
||||
|
||||
// 查询会话状态
|
||||
const status = await getSessionStatus(contextDir);
|
||||
console.log('会话状态:', status);
|
||||
|
||||
// 查询待处理问题
|
||||
const questions = await getPendingQuestions(contextDir);
|
||||
console.log('待处理问题:', questions);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 后端处理流程
|
||||
|
||||
```
|
||||
前端请求 → /api/v1/sessions/status?context_dir=org/repo/ui
|
||||
│
|
||||
├─ 1. 路径拼接：WORKSPACE_ROOT/superDS/org/repo/ui
|
||||
│
|
||||
├─ 2. URL 编码完整路径
|
||||
│
|
||||
└─ 3. 转发 GET {OPENCODE_SERVE_URL}/session/status?directory={encoded_path}
|
||||
└─ opencode serve 返回会话状态
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 使用场景
|
||||
|
||||
### 场景 1：检查会话状态
|
||||
|
||||
在发起新请求前检查目标目录是否有活跃会话：
|
||||
|
||||
```javascript
|
||||
const status = await getSessionStatus('my-org/my-repo/ui');
|
||||
const sessionIds = Object.keys(status);
|
||||
|
||||
if (sessionIds.length > 0 && status[sessionIds[0]].type === 'busy') {
|
||||
console.log('当前目录有会话正在处理中');
|
||||
}
|
||||
```
|
||||
|
||||
### 场景 2：获取待处理问题并展示
|
||||
|
||||
```javascript
|
||||
const questions = await getPendingQuestions('my-org/my-repo/ui');
|
||||
|
||||
questions.forEach(q => {
|
||||
console.log(`问题 ID: ${q.id}`);
|
||||
q.questions.forEach((question, idx) => {
|
||||
console.log(`问题${idx + 1}: ${question.question}`);
|
||||
question.options.forEach(opt => {
|
||||
console.log(` - ${opt.label}: ${opt.description}`);
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
- `context_dir` 参数必须是相对路径，不能以 `/` 开头
|
||||
- 后端会自动拼接 `WORKSPACE_ROOT` 和 `WORKSPACE_SUBDIR` 环境变量
|
||||
- 返回的 `sessionID` 和 `id`（问题 ID）用于后续的消息发送和问题回复操作
|
||||
- 接口不进行 session 校验，仅做路径拼接和透明转发
|
||||
Loading…
Reference in New Issue