Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

9.7 KB
Raw Blame
import type { GhostManifest, InstalledGhost } from './ghost';
import type { PluginDownloadStatistics, PluginIconMetadata, PluginUsageStatistics } from '@cindy/plugin-protocol';

export type PluginMarketScope = 'public' | 'organization' | 'personal';
export type PluginMarketInstallState =
  | 'not-installed'
  | 'installed'
  | 'update-available'
  | 'conflict';

/** 市场项来源:服务端市场,或用户添加的 Git / 本地自定义市场。 */
export type PluginMarketItemSource = 'server' | 'git-market' | 'local-market';

/** Renderer-safe Plugin 市场列表项;所有字段都来自协议或本地安装事实。 */
export interface PluginMarketItem {
  usageStatistics?: PluginUsageStatistics;
  downloadStatistics?: PluginDownloadStatistics;
  pluginId: string;
  ghostId: string;
  /** Host-verified namespace. Missing is legacy wire; null is root. */
  namespace?: string | null;
  name: string;
  description: string | null;
  author: string | null;
  /** Display identity from verified public publishing; never grants runtime trust. */
  publisherKind?: 'official' | 'personal' | null;
  /** Main verified a public installation's market origin; attribution spans versions. */
  installedAuthor?: string | null;
  scope: PluginMarketScope;
  organizationId: string | null;
  defaultInstall: boolean;
  releaseId: string;
  version: string;
  publishedAt: string;
  icon: PluginIconMetadata | null;
  /**
   * 自定义市场图标的本地身份键。它是 Main 根据当前来源事实计算的本地投影身份,
   * 不包含本地路径或字节;读取失败或事实不确定时也可能携带该键并由 localIcons
   * 返回 missing/retryable。服务端市场与未声明 icon 的自定义插件不携带。
   */
  customIconKey?: string;
  installState: PluginMarketInstallState;
  enabled: boolean | null;
  /** 来源类型;服务端市场项为 'server'。 */
  sourceType: PluginMarketItemSource;
  /** 来源市场名(自定义市场项必填;服务端项为 null)。 */
  sourceMarketName: string | null;
  /**
   * 新版本比已装版本权限变多,后台更新已暂停、等待用户确认。只在 Main 按真实包
   * 判定过后出现;缺省表示未知或无需确认,不能据此推断可以静默更新。
   */
  updateRequiresConsent?: true;
}
/** 市场快照。服务不可用时 renderer 保留本地插件并只展示非阻断提示。 */
export interface PluginMarketSnapshot {
  items: PluginMarketItem[];
  unavailableReason: string | null;
  /** 已添加的自定义市场名(按添加顺序);驱动"自定义"筛选 tab 的可见性。 */
  customSourceNames: string[];
  /** 本轮发现失败的自定义市场名;失败来源不影响其它来源和官方市场。 */
  unavailableCustomSourceNames: string[];
  /**
   * 企业目录单独不可用时的错误码,包含客户端尚未认识的新码。null 或缺失表示本轮没有这个状态;
   * 公开目录和已安装插件照常。
   */
  organizationAccessError?: string | null;
}

/** 服务端清理的一次性汇总提示:按 owner 缓存,consume 前跨多轮对账累加,consume 后即清。 */
export interface PluginRemovalUserNotice {
  count: number;
  /** 累计单条且插件名经安全过滤后非空时为插件名;其余情况为 null,只展示数量。 */
  name: string | null;
}

/** 详情携带安装前展示给用户的 manifest;官方来自 release,自定义来自本地发现。 */
export interface PluginMarketDetail extends PluginMarketItem {
  manifest: GhostManifest;
}

/** Main 生成并接受的自定义市场图标身份键形状;首位 0 为保留值。 */
export const PLUGIN_MARKET_CUSTOM_ICON_KEY_RE = /^[1-9a-f][a-f0-9]{63}$/;
export const PLUGIN_MARKET_CUSTOM_ICON_SOURCE_TOKEN_LENGTH = 16;
export const PLUGIN_MARKET_CUSTOM_ICON_PROJECTION_TOKEN_LENGTH = 16;

export function isPluginMarketCustomIconKey(value: string): boolean {
  return PLUGIN_MARKET_CUSTOM_ICON_KEY_RE.test(value);
}

/** Renderer 只用这个不透明 token 做同来源传输限流,不解析 Main 侧身份事实。 */
export function pluginMarketCustomIconSourceToken(value: string): string | null {
  if (!isPluginMarketCustomIconKey(value)) return null;
  return value.slice(1, 1 + PLUGIN_MARKET_CUSTOM_ICON_SOURCE_TOKEN_LENGTH);
}

/** Main 从图标键恢复快照投影代际,用于读取时重算并核对完整键。 */
export function pluginMarketCustomIconProjectionToken(value: string): string | null {
  if (!isPluginMarketCustomIconKey(value)) return null;
  const start = 1 + PLUGIN_MARKET_CUSTOM_ICON_SOURCE_TOKEN_LENGTH;
  return value.slice(start, start + PLUGIN_MARKET_CUSTOM_ICON_PROJECTION_TOKEN_LENGTH);
}

/** Renderer 请求 Main 按当前自定义市场事实读取一个本地图标。 */
export interface PluginMarketLocalIconRequest {
  pluginId: string;
  expectedIconKey: string;
}

/** Main 的批量图标读取结果;请求身份原样带回,供 Renderer 安全归并。 */
export type PluginMarketLocalIconResult =
  | (PluginMarketLocalIconRequest & { status: 'loaded'; dataUrl: string })
  | (PluginMarketLocalIconRequest & { status: 'missing' | 'retryable' });

export interface PluginMarketInstallOptions {
  /** 用户点击时看到的目标 release;Main 会在下载前重新核对。 */
  expectedReleaseId: string;
  /** 自定义来源详情读取时的完整清单;Main 会在打包前重新核对。 */
  expectedManifest?: GhostManifest;
  /**
   * receipt 模型的并发护栏:receipt 派生 token。读取与落位之间安装状态若变化即拒绝。
   */
  expectedInstalledApproval?: string;
  /** 仅详情页上用户明确点击“替换”时为 true;更新和批量更新不得切换来源。 */
  allowSourceReplacement?: boolean;
}

/** 市场安装成功后返回已落位插件。 */
export interface PluginMarketInstallResult {
  ghost: InstalledGhost;
}

/* ------------------------------------------------------------------------ */
/* 自定义市场源(Git / 本地文件夹)                                           */
/* ------------------------------------------------------------------------ */

/** 用户添加的市场来源。Git 源支持可选引用与稀疏检出;本地源指向文件夹。 */
export type MarketSource =
  | { type: 'git'; url: string; ref?: string; sparsePaths: string[] }
  | { type: 'local'; path: string };

/** 持久化的市场来源配置(sources.v1.json)。 */
export interface MarketSourceConfig {
  /** 市场名,来自 marketplace.json 的 name;全局唯一,作为管理主键。 */
  name: string;
  addedAt: string;
  lastSyncedAt: string | null;
  /** 最近一次同步到的 Git commit SHA;本地源为 null。 */
  lastRevision: string | null;
  source: MarketSource;
}

/** Renderer 管理视图使用的来源摘要。 */
export interface MarketSourceSummary extends MarketSourceConfig {
  /** 最近一次发现到的插件数;发现失败时为 0 并携带 status。 */
  pluginCount: number;
  /** 清单中因内容非法被跳过的插件条目数。 */
  skippedCount: number;
  /** 清单中因权限、文件锁或瞬时 I/O 暂时无法读取的插件条目数。 */
  unreadableCount: number;
  status: 'ok' | 'error';
  /** status === 'error' 时的 IPC 错误码(Renderer 按码本地化)。 */
  errorCode: string | null;
}

/**
 * 来源的规范化指纹。市场名是 marketplace.json 自报的、**可复用**——移除来源 A 后
 * 添加一个同名的来源 B,`customMarketPluginId` 完全相同;账本所有权若只锚在
 * pluginId 上,无关甚至恶意仓库就能借同名市场"更新"A 装出来的插件。所以自定义
 * 安装的账本记录同时记下这个指纹,所有权校验必须两者都对上。
 * 与 sources/store 的 sourcesEqual、sources/index 的 marketCloneSlug 同一套
 * 判定维度(type + 定位 + ref + 稀疏路径)。
 *
 * 序列化必须**无歧义**:用分隔符拼接(`join(',')`、`#ref:sparse`)会产生可构造的
 * 碰撞——`sparsePaths:['a,b','c']` 与 `['a','b,c']`、`ref:'x' + ['p']` 与
 * `ref:'x:p' + []` 都会得到同一 key,两个不同来源被判成同一个,所有权校验随之
 * 失效。JSON 数组序列化对每个元素定界,不存在拼接歧义。
 */
export function marketSourceKey(source: MarketSource): string {
  return source.type === 'local'
    ? JSON.stringify(['local', source.path])
    : JSON.stringify(['git', source.url, source.ref ?? null, source.sparsePaths]);
}

/**
 * 自定义市场插件的合成 pluginId。与服务端 CUID(^c[a-z0-9]{24}$)互不相交,
 * Main 在 detail/install/uninstall 入口据此分流,Renderer 无需感知差异。
 */
export const CUSTOM_MARKET_PLUGIN_ID_PREFIX = 'custom:';

export function customMarketPluginId(marketName: string, ghostId: string): string {
  return `${CUSTOM_MARKET_PLUGIN_ID_PREFIX}${encodeURIComponent(marketName)}/${encodeURIComponent(ghostId)}`;
}

export function parseCustomMarketPluginId(
  pluginId: string,
): { marketName: string; ghostId: string } | null {
  if (!pluginId.startsWith(CUSTOM_MARKET_PLUGIN_ID_PREFIX)) return null;
  const rest = pluginId.slice(CUSTOM_MARKET_PLUGIN_ID_PREFIX.length);
  const slash = rest.indexOf('/');
  if (slash <= 0 || slash === rest.length - 1) return null;
  try {
    return {
      marketName: decodeURIComponent(rest.slice(0, slash)),
      ghostId: decodeURIComponent(rest.slice(slash + 1)),
    };
  } catch {
    return null;
  }
}

/**
 * 自定义市场插件的合成 releaseId。版本变化即产生新 releaseId,
 * 从而复用服务端市场既有的 update-available / expectedReleaseId 机制。
 */
export function customMarketReleaseId(marketName: string, ghostId: string, version: string): string {
  return `custom:${encodeURIComponent(marketName)}:${encodeURIComponent(ghostId)}:${encodeURIComponent(version)}`;
}