diff --git a/会话状态与待处理问题接口指南.md b/会话状态与待处理问题接口指南.md
new file mode 100644
index 0000000..33532dc
--- /dev/null
+++ b/会话状态与待处理问题接口指南.md
@@ -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 校验，仅做路径拼接和透明转发
\ No newline at end of file