142 lines
3.7 KiB
TypeScript
142 lines
3.7 KiB
TypeScript
/**
|
||
* 协议 v1 的 HTTP 表面（JSON Schema 为准，这里是 TS 镜像）。
|
||
*
|
||
* 服务端与客户端之间只认这一套接口；引擎协议（Pi 的 JSONL、Codex 的 app-server）不越过适配层。
|
||
* 端点与规则见 docs/spec/protocol.md。
|
||
*/
|
||
|
||
/** 路径前缀：协议改版就换前缀，不原地改语义 */
|
||
export const PROTOCOL_PREFIX = '/v1' as const;
|
||
|
||
export const ENDPOINTS = {
|
||
health: '/v1/health',
|
||
me: '/v1/me',
|
||
projects: '/v1/projects',
|
||
sessions: '/v1/sessions',
|
||
session: (sessionId: string) => `/v1/sessions/${sessionId}`,
|
||
/** SSE：回放 + 实时事件流 */
|
||
sessionEvents: (sessionId: string) => `/v1/sessions/${sessionId}/events`,
|
||
sessionMessages: (sessionId: string) => `/v1/sessions/${sessionId}/messages`,
|
||
sessionCancel: (sessionId: string) => `/v1/sessions/${sessionId}/cancel`,
|
||
capabilities: '/v1/capabilities',
|
||
execution: (executionId: string) => `/v1/executions/${executionId}`,
|
||
approval: (approvalId: string) => `/v1/approvals/${approvalId}`,
|
||
} as const;
|
||
|
||
/** 能力标识，形如 `aps.schedule.preview` */
|
||
export type CapabilityId = string;
|
||
|
||
export interface HealthResponse {
|
||
status: 'ok';
|
||
version: string;
|
||
protocolVersion: number;
|
||
}
|
||
|
||
export interface MeResponse {
|
||
userId: string;
|
||
tenantId: string;
|
||
displayName: string;
|
||
/** 桌面端与浏览器共用同一身份模型，登录方式不同（见协议文档第 2 节） */
|
||
clientKind: 'desktop' | 'browser';
|
||
}
|
||
|
||
/** 能力条目：按身份过滤后返回；描述七要素见 docs/spec/capability-description.md */
|
||
export interface CapabilitySummary {
|
||
id: CapabilityId;
|
||
providerId: string;
|
||
title: string;
|
||
purpose: string;
|
||
effect: 'read' | 'draft' | 'write';
|
||
inputSchema?: Record<string, unknown>;
|
||
synonyms?: string[];
|
||
}
|
||
|
||
export interface CapabilitiesResponse {
|
||
capabilities: CapabilitySummary[];
|
||
}
|
||
|
||
/** 会话概要（ADR-0003：个人会话只读，写操作必须在项目会话内） */
|
||
export interface SessionSummary {
|
||
sessionId: string;
|
||
projectId: string | null;
|
||
scope: 'personal' | 'project';
|
||
status: 'active' | 'archived';
|
||
title: string;
|
||
createdAt: number;
|
||
}
|
||
|
||
export interface CreateSessionRequest {
|
||
projectId?: string;
|
||
scope: 'personal' | 'project';
|
||
title?: string;
|
||
}
|
||
|
||
export interface CreateSessionResponse {
|
||
session: SessionSummary;
|
||
}
|
||
|
||
export interface SessionListResponse {
|
||
sessions: SessionSummary[];
|
||
}
|
||
|
||
export interface SessionDetailResponse {
|
||
session: SessionSummary;
|
||
/** 最近一段消息；完整历史走事件流回放 */
|
||
messages: ChatMessage[];
|
||
}
|
||
|
||
export interface ChatMessage {
|
||
messageId: string;
|
||
role: 'user' | 'assistant' | 'system';
|
||
ts: number;
|
||
text: string;
|
||
}
|
||
|
||
export interface SendMessageRequest {
|
||
text: string;
|
||
/** 同一写请求重试不重复生效 */
|
||
idempotencyKey: string;
|
||
}
|
||
|
||
export interface SendMessageResponse {
|
||
accepted: true;
|
||
messageId: string;
|
||
runId: string;
|
||
}
|
||
|
||
export interface CancelResponse {
|
||
state: 'cancelling' | 'idle';
|
||
}
|
||
|
||
/** 能力调用的统一回执（架构设计 4.2） */
|
||
export interface ExecutionReceipt {
|
||
executionId: string;
|
||
status: 'accepted' | 'pending-confirmation' | 'succeeded' | 'failed';
|
||
result?: unknown;
|
||
errorKind?: string;
|
||
/** status = pending-confirmation 时给出待确认动作标识 */
|
||
approvalId?: string;
|
||
}
|
||
|
||
export interface ApprovalDecisionRequest {
|
||
decision: 'approve' | 'reject';
|
||
/** 目标数据版本；版本变了确认就失效 */
|
||
revision: number;
|
||
idempotencyKey: string;
|
||
note?: string;
|
||
}
|
||
|
||
export interface ApprovalDecisionResponse {
|
||
approvalId: string;
|
||
decision: 'approved' | 'rejected' | 'expired';
|
||
receipt?: ExecutionReceipt;
|
||
}
|
||
|
||
export interface ErrorEnvelope {
|
||
error: {
|
||
code: string;
|
||
message: string;
|
||
retryable: boolean;
|
||
detail?: unknown;
|
||
};
|
||
} |