docs: 更新 HTTP 错误码、用户积分、占卜运行及用户资料协议文档

2026-04-10 16:45:45 +08:00
parent 1bc8bc6a27
commit 17ef460391
78 changed files with 18680 additions and 25 deletions
@@ -18,9 +18,12 @@ Protocol verification status:
 ## Route overview

 - Submit run: `POST /api/v1/agent/runs`
+- Cancel run: `POST /api/v1/agent/runs/{threadId}/cancel?runId=...`
 - Stream events: `GET /api/v1/agent/runs/{threadId}/events?runId=...`
 - History snapshot: `GET /api/v1/agent/history`
 - Delete session: `DELETE /api/v1/agent/sessions/{threadId}`
+- Upload attachment: `POST /api/v1/agent/attachments`
+- Get attachment signed URL: `GET /api/v1/agent/attachments/signed-url?bucket=...&path=...`
 - Audio transcribe: `POST /api/v1/agent/transcribe`

 ## Run request contract
@@ -81,8 +84,8 @@ Protocol verification status:
 ### `divinationPayload` strict rules

 - `divinationMethod`: enum, allowed values `手动起卦 | 自动起卦`
- `questionType`: non-empty string, recommended Chinese category labels
- `question`: non-empty string
+- `questionType`: non-empty string, max 32 chars, recommended Chinese category labels
+- `question`: non-empty string, max 300 chars
 - `divinationTimeIso`: RFC3339 datetime with timezone offset
 - `yaoLines`: exactly 6 items, order is `初爻 -> 上爻`
 - `yaoLines` item enum: `少阳 | 少阴 | 老阳 | 老阴`
@@ -301,6 +304,82 @@ Rules:
 - Success: `204 No Content`.
 - Idempotent: already deleted or not found also returns `204 No Content`.

+## Run cancel contract
+
+### `POST /api/v1/agent/runs/{threadId}/cancel?runId=...`
+
+- Authorization: current user must own the session.
+- Request: `runId` query parameter required.
+- Success response:
+
+```json
+{
+  "threadId": "uuid",
+  "runId": "run_xxx",
+  "accepted": true
+}
+```
+
+Error codes (see common registry):
+
+- `AGENT_SESSION_NOT_FOUND`
+- `AGENT_FORBIDDEN`
+
+## Attachment upload contract
+
+### `POST /api/v1/agent/attachments`
+
+- Authorization: authenticated user.
+- Request: `multipart/form-data` with fields:
+  - `threadId` (string, required)
+  - `file` (binary, required)
+- Max file size: 5MB
+- Success response:
+
+```json
+{
+  "attachment": {
+    "bucket": "agent-inputs",
+    "path": "agent-inputs/{userId}/{filename}",
+    "mimeType": "image/png",
+    "url": "https://...signed..."
+  }
+}
+```
+
+Error codes (see common registry):
+
+- `AGENT_ATTACHMENT_EMPTY`
+- `AGENT_ATTACHMENT_TOO_LARGE`
+- `AGENT_ATTACHMENT_STORAGE_UNAVAILABLE`
+- `AGENT_SESSION_NOT_FOUND`
+- `AGENT_FORBIDDEN`
+
+## Attachment signed URL contract
+
+### `GET /api/v1/agent/attachments/signed-url?bucket=...&path=...`
+
+- Authorization: authenticated user.
+- Query params:
+  - `bucket` (string, required)
+  - `path` (string, required)
+- Path must be under `agent-inputs/{userId}/` scope.
+- Success response:
+
+```json
+{
+  "bucket": "agent-inputs",
+  "path": "agent-inputs/{userId}/{filename}",
+  "url": "https://...signed..."
+}
+```
+
+Error codes (see common registry):
+
+- `AGENT_ATTACHMENT_BUCKET_INVALID`
+- `AGENT_ATTACHMENT_PATH_SCOPE_INVALID`
+- `AGENT_SIGNED_URL_GENERATION_FAILED`
+
 ## Transcribe contract

 ### `POST /api/v1/agent/transcribe`