Skip to content

DOCS.md

Latest commit

 

History

History
133 lines (99 loc) · 6.92 KB

DOCS.md

File metadata and controls

133 lines (99 loc) · 6.92 KB

Delphi Agent API Docs

DOCS.md 只作为 API / SDK 文档入口。技术架构图请看 ARCHITECHE.MD，项目使用说明请看 README.md。

兼容入口：DOC.md。

API Reference

SDK Reference

API Surface

方法 路径 说明
POST /api/chat/stream 主入口：发送 prompt、执行 command，统一返回 SSE。
GET /api/catalog/models?provider=<provider> 查询模型列表。
GET /api/catalog/skills?namespace=<ns> 查询 namespace 可见 skills。
GET /api/catalog/skills/{name}?namespace=<ns> 查询单个 skill。
GET /api/catalog/prompts 查询 prompt catalog。
GET /api/catalog/resources 查询 resource catalog。
POST /api/catalog/reload?namespace=<ns> 重扫 catalog，并清理 skill cache。
GET /api/audit?namespace=<ns>&from=&to=&limit= 查询审计日志。
GET /api/usage?namespace=<ns>&from=&to= 查询用量统计。
GET /api/usage/today?namespace=<ns> 查询今日用量。

Required Headers

Header 说明
Content-Type: application/json POST 请求必须使用 JSON。
X-Tenant-Id 租户标识，必须等于请求体中的 namespace。
X-User-Id 当前用户标识，用于审计和计量。

Chat Stream Request

POST /api/chat/stream 支持两类请求：

  1. 普通 prompt：command 为空，服务端创建或加载 session，进入 AgentRunRuntime。
  2. 会话命令：command 非空，服务端返回 ack SSE 事件。

关键字段：

字段 说明
namespace 必填，必须与 X-Tenant-Id 一致。
sessionId 可选；为空时创建新 session。
projectKey 可选，用于 session/project workspace 关联。
prompt prompt 文本；steer/continue 等命令按命令语义使用。
provider / modelId 可选；创建新 session 时未传则使用默认模型。
queueMode INTERRUPT、FOLLOWUP、STEER、DROP、REJECT；未传时默认 REJECT。
command abort、steer、compact、fork、navigate、continue。
commandArgs 命令参数，例如 keep、entryId。

Command Consistency

多节点模式下，写命令不再由 controller 直接调用 AgentSessionRuntime：

命令 多节点行为
abort 通过 AgentRunRuntime.abort 查找 active owner；远端 owner 通过 Redis command channel 中止本地 Agent。
steer 通过 active owner 注入当前 run；如果无 active run，退化为本地 session steering。
compact 走 SessionCommandRuntime，active run 存在时拒绝，空闲时获取 Redis session lock 后执行。
fork 同上，返回 forkSessionId。
navigate 同上，避免导航和正在运行的 Agent 并发修改 head。
continue 作为标准 run 进入 AgentRunRuntime，获取 active-run lease、fencing token，并返回正常 run SSE 事件；未指定 queueMode 时默认 reject active run。

会话写入幂等性：

  • 普通 prompt 会携带 runId + fencingToken 进入 AgentSessionRuntime.prompt；continue 会携带同一组 token 进入 AgentSessionRuntime.cont。
  • Mongo entries 使用 sessionId + runId + sequence 唯一索引避免重复追加。
  • SessionDocument.fencingToken 记录最后成功提交的 token；旧 owner 的低 token 写入会被拒绝。

Main SSE Events

类别 事件
Run run_started、queue_updated、run_completed、run_failed、quota_rejected
Message message_start、message_delta、message_end
Tool tool_started、tool_updated、tool_completed
Subagent subagent_started、subagent_completed、subagent_failed
Command ack

SSE Delivery Semantics

实时投递：

  • 单机模式：事件只投递给本机 SseEmitter。
  • cluster 模式：事件先投递本机，再通过 Redis pub/sub 广播到其他节点的本地 emitter。

事件留存：

  • cluster 模式下，RedisSseEventPublisher 会同时把事件写入 delphi:events:session:<namespace>:<sessionId> Redis Stream。
  • 当前 HTTP API 仍以实时 SSE 为主；event stream 用于后续断线补读、诊断和恢复终态事件。
  • 终态事件包括 run_completed、run_failed、quota_rejected；命中当前 runId 的 emitter 会自动 complete。

Cluster Configuration

环境变量 默认值 说明
PI_CLUSTER_ENABLED false 开启 Redis 协调、多节点 active run、分布式队列和跨节点命令。
PI_CLUSTER_NODE_ID 空 节点唯一标识；为空时使用 POD_NAME、HOSTNAME 或 hostname。生产不要写死相同值。
PI_CLUSTER_REDIS_KEY_PREFIX delphi Redis key 前缀。
PI_CLUSTER_RUN_MAX_TTL_MS 1800000 active-run lease TTL。
PI_CLUSTER_LOCK_DEFAULT_TTL_MS 30000 session command lock TTL。
REDIS_HOST / REDIS_PORT localhost / 6379 Redis 连接配置。
PI_WORKSPACE_STORAGE local local 或 snapshot。多节点推荐 snapshot。

Redis 数据结构：

Key / Channel 类型 生命周期语义
<prefix>:run:active:<runId> Hash + TTL 当前 active run 元数据，包含 owner node 和 fencing token。
<prefix>:run:by-session:<namespace>:<sessionId> String + TTL session 到 active run 的短生命周期索引。
<prefix>:session:fencing:<namespace>:<sessionId> Counter session fencing token 单调递增源。
<prefix>:queue:session:<namespace>:<sessionId> Redis Stream queued run，consumer group pending 可恢复。
<prefix>:run:commands:<nodeId> Pub/sub channel abort/steer 发往 owner node。
<prefix>:sse:events Pub/sub channel 跨节点 SSE 实时广播。
<prefix>:events:session:<namespace>:<sessionId> Redis Stream session 事件轨迹，供补读/诊断。
<prefix>:ratelimit:<namespace>:<window> String + TTL cluster 模式下的全局限流窗口。

Crash Semantics

关键不变量：

  • Redis Stream queued run 只有在调度接受后才 XACK + XDEL；如果节点在 ack 前崩溃，pending 记录可由 XAUTOCLAIM 恢复。
  • active run lease 获取和 fencing token 分配在同一个 Lua 脚本中完成。
  • Mongo 会话消息写入以 runId + sequence 幂等；重复执行最多补齐缺失消息，不会重复追加已写消息。
  • snapshot workspace storage 会在 run 成功路径上先持久化 snapshot，再发送 run_completed 并释放 active-run lease；snapshot 持久化失败会让 run 进入 run_failed，且不会自动调度后续 queued run。
  • 会话管理命令在 cluster 模式下需要 session lock；active run 存在时拒绝直接写，避免和 Agent run 并发修改状态。