aps-agent/server/provider-sdk/index.ts

/**
 * Provider 契约（架构设计第 6 节）：业务系统接入平台的唯一形状。
 *
 * Provider 是能力适配器，不是业务系统，也不承载模型上下文。三个方法：
 *   describe()  声明自己有哪些能力
 *   invoke()    执行一次能力调用
 *   health()    健康状态
 * 能力怎么描述见 docs/spec/capability-description.md，错误分类见 ./errors.js。
 */
import type { ExecutionReceipt } from '@aps/contracts';

import type { ErrorKind } from './errors.js';

export type { ErrorKind } from './errors.js';
export { ERROR_KINDS, isErrorKind, ProviderError } from './errors.js';

/** 能力声明（架构设计 6）：read 不改状态；draft 只写隔离草稿；write 必须绑定唯一目标与幂等键 */
export interface Capability {
  /** 形如 aps.schedule.preview */
  id: string;
  /** 界面标题（可省，缺省用 description） */
  title?: string;
  /** 给模型看的一句话用途（40 字以内） */
  description: string;
  effect: 'read' | 'draft' | 'write';
  mode: 'sync' | 'async';
  /** 何时不用：同族能力的边界写在这里 */
  whenNotToUse?: string;
  /** 业务黑话与同义词 */
  synonyms?: string[];
  inputSchema: Record<string, unknown>;
  outputSchema: Record<string, unknown>;
  idempotency: 'none' | 'key' | 'natural';
  /** 这个能力可能返回的错误分类 */
  errors: ErrorKind[];
}

export interface ProviderManifest {
  id: string;
  displayName: string;
  version: string;
  /** 兼容的平台协议版本（当前 1） */
  platformVersion: number;
  /**
   * 调用这个系统要不要平台用户先绑定本系统账号（A4.1）。
   * 缺省 true：真实系统默认要绑定；只有无账号概念的自建/联调 Provider 才写 false。
   */
  requiresIdentity?: boolean;
  capabilities: Capability[];
}

/** 平台用户在该系统里的身份（A4.1）：只有账号标识，没有任何凭据 */
export interface ExecutionIdentity {
  accountId: string;
  displayName: string;
}

/** 一次性执行授权（A4.3）：Provider 用它在这次调用里取凭据，过期即失效 */
export interface CredentialHandle {
  grantId: string;
  read(): Promise<Record<string, string> | undefined>;
}

/**
 * 影响预览（A4.4）：写操作确认卡的正文来源。
 * Provider 知道「要动什么、当前数据版本是多少」，这两个问题平台答不了，所以由它给。
 */
export interface ImpactPreview {
  /** 一句话说清这次写会影响什么（确认卡主文案） */
  impactSummary: string;
  /** 目标数据版本；版本变了这次确认就失效 */
  revision: number;
  /** 关键参数摘要（脱敏后给确认卡看，不是完整参数） */
  paramsPreview?: Record<string, unknown>;
}

/** 一次调用的上下文：Core 注入，Provider 不自己找身份与凭据 */
export interface ExecutionContext {
  executionId: string;
  sessionId: string;
  projectId: string | null;
  /** 平台用户与租户 */
  subject: { userId: string; tenantId: string };
  /** 平台用户在该系统的账号映射结果（A4.1）；未绑定时策略层已经拒绝，这里不会缺 */
  identity?: ExecutionIdentity;
  /** 一次性凭据句柄（A4.3）；没有配凭据的系统不传 */
  credentials?: CredentialHandle;
  /** 幂等键：Provider 侧若支持幂等，应带回执里透传 */
  idempotencyKey?: string;
  /** 截止时间（epoch ms）：超时由 Core 判定，Provider 应尽力遵守 */
  deadlineAt: number;
}

export interface CapabilityCall {
  capabilityId: string;
  params: unknown;
}

export interface HealthStatus {
  status: 'ok' | 'degraded' | 'down';
  detail?: string;
  checkedAt: number;
}

export interface Provider {
  describe(): Promise<ProviderManifest>;
  invoke(context: ExecutionContext, call: CapabilityCall): Promise<ExecutionReceipt>;
  health(): Promise<HealthStatus>;
  /**
   * 可选：写能力的影响预览（A4.4 确认卡）。
   * 不实现时平台用能力描述兜底（只影响确认卡信息量，不影响策略判定）。
   */
  preview?(context: ExecutionContext, call: CapabilityCall): Promise<ImpactPreview>;
}

/** 可选的执行状态查询：异步能力（mode=async）应实现 */
export interface ExecutionStatusProvider {
  status(executionId: string): Promise<ExecutionReceipt>;
}