跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.shannon.run/llms.txt

Use this file to discover all available pages before exploring further.

​
概览

HITL（人机协同）审核 API 提供了在执行开始前审核、优化和批准 AI 生成的研究计划的端点。这些端点与存储在 Redis 中的审核状态交互，并通过 gRPC Signal 与 Temporal 工作流协调。 使用教程请参见人机协同审核。

​
认证

必需：是 在请求头中包含 API key： 
X-API-Key: sk_test_123456
所有权验证：仅提交任务的用户可以访问其审核状态。

​
获取审核状态

GET http://localhost:8080/api/v1/tasks/{workflow_id}/review

​
说明

返回工作流的当前审核对话状态。用于获取初始研究计划并跟踪审核进度。

​
路径参数

参数类型必需说明
workflow_idstring是工作流 ID（来自任务提交响应）

​
请求头

头必需说明
X-API-Key是API 认证密钥

​
响应

​
200 OK

{
  "status": "reviewing",
  "round": 1,
  "version": 1,
  "current_plan": "根据您的查询，我建议研究...",
  "rounds": [
    {
      "role": "assistant",
      "message": "根据您的查询，我建议研究...",
      "timestamp": "2025-01-15T10:30:00Z"
    }
  ],
  "query": "研究 AI 代理框架的竞争格局"
}
响应头：
头说明
ETag当前版本号（用于 If-Match 并发控制）
响应字段：
字段类型说明
statusstring"reviewing"（等待输入）或 "approved"（计划已接受）
roundinteger当前对话轮次（从 1 开始）
versioninteger乐观并发的单调递增版本
current_planstring最新的可执行计划（当 LLM 意图为 "ready" 时设置）。如果 LLM 仍在提问则可能为空。
roundsarray完整对话历史
rounds[].rolestring"assistant"（LLM）或 "user"（人工反馈）
rounds[].messagestring消息内容
rounds[].timestampstringRFC 3339 时间戳
querystring原始任务查询

​
401 Unauthorized

{ "error": "Unauthorized" }

​
403 Forbidden

{ "error": "Forbidden: not the task owner" }

​
404 Not Found

{ "error": "Review session not found or expired" }

​
示例

curl -s http://localhost:8080/api/v1/tasks/task-abc123/review \
  -H "X-API-Key: $API_KEY" | jq

​
提交反馈

POST http://localhost:8080/api/v1/tasks/{workflow_id}/review

​
说明

发送反馈以优化研究计划。网关将反馈转发给 LLM 服务，后者生成包含用户输入的更新计划。对话轮次和版本号递增。 分布式 Redis 锁防止并发反馈请求在 LLM 调用期间竞争。

​
路径参数

参数类型必需说明
workflow_idstring是工作流 ID

​
请求头

头必需说明
X-API-Key是API 认证密钥
Content-Type是application/json
If-Match否乐观并发的版本号。如提供，当前版本不匹配时返回 409。

​
请求体参数

参数类型必需说明
actionstring是必须为 "feedback"
messagestring是反馈文本（最大 10 KB）

​
请求体

{
  "action": "feedback",
  "message": "更多关注开源框架，并加入价格对比"
}

​
响应

​
200 OK

{
  "status": "reviewing",
  "plan": {
    "message": "我已更新研究计划，聚焦于...",
    "round": 2,
    "version": 2,
    "intent": "ready"
  }
}
响应头：
头说明
ETag更新后的版本号
响应字段：
字段类型说明
statusstring反馈响应始终为 "reviewing"
plan.messagestringLLM 更新后的计划
plan.roundinteger当前轮次
plan.versioninteger更新后的版本（用于下次 If-Match）
plan.intentstring"feedback"（LLM 在提问）或 "ready"（已提出可执行计划）

​
400 Bad Request

{ "error": "message is required for feedback" }

{ "error": "message exceeds maximum length (10KB)" }

​
404 Not Found

{ "error": "Review session not found or expired" }

​
409 Conflict

版本不匹配： 
{ "error": "Conflict: state has been modified" }
另一个反馈请求正在进行中： 
{ "error": "Another feedback request is in progress. Please wait." }
超过最大轮次： 
{ "error": "Maximum review rounds reached. Please approve the plan." }

​
502 Bad Gateway

{ "error": "Failed to generate updated plan" }

​
示例

curl -X POST http://localhost:8080/api/v1/tasks/task-abc123/review \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "If-Match: 1" \
  -d '{
    "action": "feedback",
    "message": "增加定价章节，并将 LangGraph 加入对比"
  }'

​
批准计划

POST http://localhost:8080/api/v1/tasks/{workflow_id}/review

​
说明

批准当前研究计划，解除工作流阻塞以继续执行。网关向等待中的工作流发送 Temporal Signal，将确认的计划和审核对话注入任务上下文。

​
路径参数

参数类型必需说明
workflow_idstring是工作流 ID

​
请求头

头必需说明
X-API-Key是API 认证密钥
Content-Type是application/json
If-Match否乐观并发的版本号

​
请求体参数

参数类型必需说明
actionstring是必须为 "approve"

​
请求体

{
  "action": "approve"
}

​
响应

​
200 OK

{
  "status": "approved",
  "message": "Research started"
}

​
400 Bad Request

无可批准的计划： 
{ "error": "No research plan to approve. Please provide feedback to generate a plan first." }

​
409 Conflict

版本不匹配： 
{ "error": "Conflict: plan has been updated. Please review the latest version." }
反馈正在进行中： 
{ "error": "A feedback request is in progress. Please wait and try again." }

​
502 Bad Gateway

{ "error": "Failed to approve review" }

​
示例

curl -X POST http://localhost:8080/api/v1/tasks/task-abc123/review \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "If-Match: 2" \
  -d '{"action": "approve"}'

​
行为说明

  • Redis TTL：审核状态在 Redis 中的 TTL 等于审核超时加 5 分钟缓冲（默认：20 分钟）。过期后审核会话不再可访问。
  • 最大轮次：最多 10 轮反馈。最后一轮 LLM 被指示生成明确计划。超过此限制后仅接受批准。
  • 所有权：仅提交任务的用户可以访问其审核状态（通过 Redis 中的 owner_user_id 强制执行）。
  • 并发：反馈和批准都会获取分布式 Redis 锁。如果反馈请求正在进行中（持有锁），批准将立即返回 409。
  • SSE 事件：审核过程发出 RESEARCH_PLAN_READY、REVIEW_USER_FEEDBACK、RESEARCH_PLAN_UPDATED 和 RESEARCH_PLAN_APPROVED 事件到 Redis 事件流。这些事件出现在 SSE 流中并持久化到会话历史。
  • Token 追踪：审核期间（反馈轮次）的 LLM token 使用量通过 RecordTokenUsage gRPC 记录，确保准确的成本核算。