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。

14.3 KB
Raw Blame
/** Public import projection. Source paths, credentials and configuration stay on the owning host. */
export type CompanionImportSourceKind = 'hermes' | 'openclaw';
export type CompanionImportCategory = 'personality' | 'memory' | 'skills' | 'bots' | 'connections' | 'automations';
export type CompanionImportBotPlatform = 'telegram' | 'discord' | 'feishu' | 'wecom' | 'dingtalk';

export interface CompanionImportSource {
  id: string;
  kind: CompanionImportSourceKind;
  name: string;
}

export interface CompanionImportEntry {
  id: string;
  category: CompanionImportCategory;
  name: string;
  description?: string;
  selected: boolean;
  /** Source was paused: importing it must never enable it. */
  enabled?: boolean;
  dependsOn?: string[];
  /** Alternative entries that supply different values for the same variable. */
  exclusiveWith?: string[];
  /** An explicit compatibility problem, never silently discarded configuration. */
  issues?: string[];
  /** `bots` only: messaging platform of the source bot. */
  platform?: CompanionImportBotPlatform;
  /** `bots` only: inferred owner id on that platform; alternatives differ only by owner. */
  owner?: string;
}

export interface CompanionImportPreview {
  id: string;
  source: CompanionImportSource;
  name: string;
  avatarImageBase64?: string;
  entries: CompanionImportEntry[];
  /** Host understands compact immutable preview-index ranges. */
  selectionRanges?: true;
  /** Host accepts bounded selection uploads through the existing import action. */
  selectionChunks?: true;
}

export interface CompanionImportSelection {
  previewId: string;
  /** Stable across retries and remote reconnects. */
  requestId: string;
  name: string;
  avatarImageBase64?: string;
  entryIds: string[];
  /** Inclusive preview-index ranges, only when advertised; mutually exclusive with entryIds. */
  entryRanges?: Array<[number, number]>;
  takeover: boolean;
  /** Save first; connection checks and source handover continue from the teammate chat. */
  deferSetup?: boolean;
}

export type CompanionImportSubmission = CompanionImportSelection | {
  selectionChunk: { id: string; offset: number; total: number; text: string };
};
// Even worst-case JSON escaping stays below the existing 64 KiB action budget.
export const COMPANION_IMPORT_SELECTION_CHUNK_LENGTH = 8 * 1024;
export function* companionImportSubmissions(selection: CompanionImportSelection, chunked = false): Generator<CompanionImportSubmission> {
  if (!chunked) { yield selection; return; }
  const text = JSON.stringify(selection);
  if (text.length <= COMPANION_IMPORT_SELECTION_CHUNK_LENGTH) { yield selection; return; }
  for (let offset = 0; offset < text.length; offset += COMPANION_IMPORT_SELECTION_CHUNK_LENGTH) {
    yield { selectionChunk: { id: selection.requestId, offset, total: text.length, text: text.slice(offset, offset + COMPANION_IMPORT_SELECTION_CHUNK_LENGTH) } };
  }
}

export interface CompanionImportCheck {
  entryId: string;
  status: 'copied' | 'verified' | 'needs-attention' | 'taken-over' | 'paused';
  message?: string;
  /** Fully written parts before an item failure; absent for old receipts. */
  progress?: { saved: number; total: number };
}

export interface CompanionImportResult {
  requestId: string;
  botId: string;
  canonicalSessionId?: string;
  status: 'running' | 'complete' | 'needs-attention';
  checks: CompanionImportCheck[];
  /** The companion and selected content have finished their save pass. */
  saved?: boolean;
  /** Saved definitions/content, independently of later authorization and activation. */
  savedEntryIds?: string[];
}

export interface CompanionImportApi {
  sources(): Promise<CompanionImportSource[]>;
  preview(sourceId: string): Promise<CompanionImportPreview>;
  start(selection: CompanionImportSelection): Promise<CompanionImportResult>;
  status(requestId: string): Promise<CompanionImportResult | undefined>;
}

export const companionImportCategories: CompanionImportCategory[] = ['personality', 'memory', 'skills', 'bots', 'connections', 'automations'];

/** Preserve exact choices while keeping large selections below the existing action budget. */
export function compactCompanionImportSelection(preview: CompanionImportPreview, selected: string[]): Pick<CompanionImportSelection, 'entryIds' | 'entryRanges'> {
  if (!preview.selectionRanges || selected.length < 200) return { entryIds: selected };
  const ids = new Set(selected);
  const ranges: Array<[number, number]> = [];
  preview.entries.forEach((entry, index) => {
    if (!ids.has(entry.id)) return;
    const last = ranges.at(-1);
    if (last && last[1] + 1 === index) last[1] = index;
    else ranges.push([index, index]);
  });
  return JSON.stringify(ranges).length < JSON.stringify(selected).length
    ? { entryIds: [], entryRanges: ranges } : { entryIds: selected };
}

/** An alternative already chosen within this category also satisfies its group checkbox. */
export function areCompanionImportEntriesSelected(entries: CompanionImportEntry[], selected: string[]): boolean {
  const all = new Set(selected);
  const selectedHere = new Set(entries.filter(entry => all.has(entry.id)).map(entry => entry.id));
  return entries.every(entry => selectedHere.has(entry.id) || entry.exclusiveWith?.some(id => selectedHere.has(id)));
}

/** Reuse the existing checkboxes; bulk selection never guesses a credential account. */
export function toggleCompanionImportEntries(entries: CompanionImportEntry[], current: string[], ids: string[], checked: boolean): string[] {
  const requested = new Set(ids);
  if (!checked) return current.filter(id => !requested.has(id));
  const byId = new Map(entries.map(entry => [entry.id, entry]));
  if (ids.length === 1) {
    const conflicts = new Set(byId.get(ids[0]!)?.exclusiveWith ?? []);
    return [...new Set([...current.filter(id => !conflicts.has(id)), ...ids])];
  }
  const selected = new Set(current);
  return [...new Set([...current, ...ids.filter(id => {
    const conflicts = byId.get(id)?.exclusiveWith ?? [];
    return !conflicts.some(other => selected.has(other) || requested.has(other));
  })])];
}

export function companionImportIssueKey(code?: string): string {
  if (code === 'AUTOMATION_DEPENDENCY_NOT_SELECTED') return 'missingSelection';
  if (code === 'NATIVE_AUTH_REFRESH_REQUIRED') return 'authRefresh';
  if (code === 'SOURCE_TOOL_POLICY_NEEDS_MAPPING') return 'toolMapping';
  if (code === 'AUTOMATION_MODEL_NEEDS_MAPPING') return 'modelMapping';
  if (code === 'AUTOMATION_CONTEXT_NEEDS_MAPPING' || code === 'AUTOMATION_WORKDIR_NEEDS_MAPPING') return 'contextMapping';
  if (code?.startsWith('DELIVERY_')) return 'deliveryFailed';
  if (code === 'SOURCE_AUTOMATION_CHANGED' || code === 'SOURCE_CHANGED') return 'sourceChanged';
  if (code?.startsWith('CREDENTIAL_STORAGE_')) return 'credentialFailed';
  if (code === 'AUTOMATION_SCRIPT_MISSING') return 'scriptMissing';
  if (code === 'SOURCE_COMMAND_UNAVAILABLE') return 'sourceCommand';
  if (code?.includes('READ_') || code === 'VERIFICATION_MODEL_UNAVAILABLE') return 'readFailed';
  return 'itemAttention';
}

/** Additive read capability; older hosts continue returning the original projection. */
export const COMPANION_IMPORT_CHUNK_PRIMITIVE = 'companion-import-chunks-v1';
export const COMPANION_IMPORT_CHUNK_LENGTH = 256 * 1024;
export const COMPANION_IMPORT_READ_MAX_LENGTH = 128 * 1024 * 1024;
/**
 * Additive preview capability: the controller renders the `bots` category, and importing a
 * bot stops it in the source agent before the teammate connects it. Controllers without it
 * keep receiving those bots under `connections`, with no source stop.
 */
export const COMPANION_IMPORT_BOTS_PRIMITIVE = 'companion-import-bots-v1';

/** Transport-neutral client: Desktop and Mobile use their existing Remote Resource adapters. */
export function remoteCompanionImportApi(
  read: (id: string) => Promise<unknown>,
  invoke: (sourceId: string, selection: CompanionImportSubmission) => Promise<unknown>,
): CompanionImportApi {
  const readData = async (id: string): Promise<Record<string, unknown>> => {
    const raw = await read(id) as { blocks?: Array<{ primitive?: string; data?: Record<string, unknown> }> };
    const block = raw?.blocks?.find(block => block.primitive === 'companion-import');
    if (!block?.data) throw new Error('IMPORT_UNAVAILABLE');
    return block.data;
  };
  const data = async (id: string): Promise<Record<string, unknown>> => {
    let part = await readData(id);
    if (!part.chunk) return part;
    const pieces: string[] = [];
    let offset = 0;
    let token: string | undefined;
    let total: number | undefined;
    for (;;) {
      const chunk = part.chunk as { id?: unknown; offset?: unknown; total?: unknown; text?: unknown } | undefined;
      if (!chunk || typeof chunk.id !== 'string' || !/^[a-zA-Z0-9-]{1,64}$/.test(chunk.id)
        || chunk.offset !== offset || !Number.isSafeInteger(chunk.total)
        || typeof chunk.total !== 'number' || chunk.total <= 0 || chunk.total > COMPANION_IMPORT_READ_MAX_LENGTH
        || typeof chunk.text !== 'string' || !chunk.text.length || chunk.text.length > COMPANION_IMPORT_CHUNK_LENGTH
        || (token !== undefined && (token !== chunk.id || total !== chunk.total))
        || offset + chunk.text.length > chunk.total) throw new Error('INVALID_IMPORT_RESPONSE');
      token = chunk.id; total = chunk.total;
      pieces.push(chunk.text); offset += chunk.text.length;
      if (offset === total) break;
      if (chunk.text.length !== COMPANION_IMPORT_CHUNK_LENGTH) throw new Error('INVALID_IMPORT_RESPONSE');
      part = await readData(`chunk:${token}:${offset}`);
    }
    const serialized = pieces.join('');
    // Release transport chunks before materializing the full projection. Keeping
    // pieces alive through JSON.parse retains three copies of a large preview
    // (chunks, joined text and objects) on the controlling phone at once.
    pieces.length = 0;
    part = {};
    const result: unknown = JSON.parse(serialized);
    if (!result || typeof result !== 'object' || Array.isArray(result)) throw new Error('INVALID_IMPORT_RESPONSE');
    return result as Record<string, unknown>;
  };
  const status = async (requestId: string) => {
    const result = (await data(`result:${requestId}`)).result as CompanionImportResult | null;
    if (result && (result.requestId !== requestId || !Array.isArray(result.checks)
      || !['running', 'complete', 'needs-attention'].includes(result.status))) throw new Error('INVALID_IMPORT_RESPONSE');
    return result ?? undefined;
  };
  const sources = new Map<string, { id: string; selectionChunks: boolean }>();
  return {
    async sources() {
      const result = (await data('sources')).sources as CompanionImportSource[];
      if (!Array.isArray(result) || result.some(source => !source.id || !source.name || !['hermes', 'openclaw'].includes(source.kind))) throw new Error('INVALID_IMPORT_RESPONSE');
      return result;
    },
    async preview(sourceId) {
      const result = (await data(`preview:${sourceId}`)).preview as CompanionImportPreview;
      if (!result?.id || !Array.isArray(result.entries)
        || result.entries.some(entry => !entry.id || typeof entry.name !== 'string' || !companionImportCategories.includes(entry.category))) throw new Error('INVALID_IMPORT_RESPONSE');
      sources.set(result.id, { id: sourceId, selectionChunks: result.selectionChunks === true });
      return result;
    },
    async start(selection) {
      const sourceId = sources.get(selection.previewId);
      if (!sourceId) throw new Error('PREVIEW_EXPIRED');
      for (const part of companionImportSubmissions(selection, sourceId.selectionChunks)) await invoke(sourceId.id, part);
      const result = await status(selection.requestId);
      if (!result) throw new Error('IMPORT_RECEIPT_MISSING');
      return result;
    },
    status,
  };
}

/** Stable public reason categories, shared by Desktop/Mobile. Never display raw exceptions. */
export function companionImportReasonKey(code?: string): string {
  const keys: Record<string, string> = {
    SOURCE_DATABASE_DRIVER_UNAVAILABLE: 'databaseDriver', SOURCE_DATABASE_UNAVAILABLE: 'databaseUnavailable',
    SOURCE_DATABASE_INVALID: 'databaseUnavailable', SOURCE_DATABASE_TOO_LARGE: 'fileTooLarge',
    MEMORY_DESCRIPTION_TOO_LONG: 'memoryMetadata', MEMORY_TITLE_TOO_LONG: 'memoryMetadata', MEMORY_METADATA_INVALID: 'memoryMetadata',
    MEMORY_CONTENT_TOO_LARGE: 'fileTooLarge', MEMORY_WRITE_FAILED: 'memoryWrite', MEMORY_CHANGED: 'memoryChanged',
    MEMORY_STORAGE_UNAVAILABLE: 'memoryWrite', MEMORY_ATTACHMENT_UNSUPPORTED: 'attachmentUnsupported',
    SOURCE_FILE_TOO_LARGE: 'fileTooLarge', SOURCE_SNAPSHOT_TOO_LARGE: 'fileTooLarge', SOURCE_ITEM_TOO_LARGE: 'fileTooLarge',
    IMPORT_DISK_FULL: 'diskFull', IMPORT_PERMISSION_DENIED: 'permissionDenied',
    IMPORT_SETUP_DEFERRED: 'setupDeferred', SOURCE_TOOL_POLICY_NEEDS_MAPPING: 'toolMapping', AUTOMATION_MODEL_NEEDS_MAPPING: 'modelMapping',
    AUTOMATION_CONTEXT_NEEDS_MAPPING: 'contextMapping', AUTOMATION_WORKDIR_NEEDS_MAPPING: 'contextMapping',
    SOURCE_AUTOMATION_INVALID: 'automationInvalid', AUTOMATION_TRIGGER_NEEDS_ADAPTER: 'automationInvalid',
    AUTOMATION_DATA_READ_FAILED: 'readFailed', AUTOMATION_READ_NOT_VERIFIED: 'readFailed',
    NATIVE_AUTH_REFRESH_REQUIRED: 'authRefresh', AUTOMATION_DEPENDENCY_NOT_SELECTED: 'missingSelection',
    SOURCE_COMMAND_UNAVAILABLE: 'sourceCommand',
    // 导入的 Telegram / Discord 机器人没能直接变成伙伴的消息平台连接(凭证仍保留给自动化投递)。
    IMPORT_IM_BOT_OWNER_MISSING: 'imBotOwnerMissing', IMPORT_IM_BOT_GATEWAY_RUNNING: 'imBotGatewayRunning',
    IMPORT_IM_BOT_IN_USE: 'imBotInUse', IMPORT_IM_BOT_CONNECT_FAILED: 'imBotConnectFailed',
    // 原 Agent 里的机器人没能确认停下,没有接给伙伴。
    IMPORT_IM_BOT_SOURCE_STOP_UNCONFIRMED: 'imBotSourceStopUnconfirmed',
    // 预览后原来位置上的机器人换了,没有停用它。
    IMPORT_IM_BOT_SOURCE_CHANGED: 'imBotSourceChanged',
  };
  return code && keys[code] || 'itemFailed';
}
export function companionImportErrorCode(error: unknown): string | undefined {
  const value = error as { code?: unknown; message?: unknown } | null;
  const pattern = /\b(?:SOURCE|IMPORT|MEMORY|CREDENTIAL|AUTOMATION|PROFILE|PREVIEW|SELECTION)_[A-Z_]+\b/;
  const candidate = typeof value?.code === 'string' && pattern.test(value.code) ? value.code
    : typeof value?.message === 'string' ? value.message.match(pattern)?.[0] : undefined;
  return candidate && /^[A-Z][A-Z_]+$/.test(candidate) ? candidate : undefined;
}