Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
import { i18n } from '@/i18n';
import { mobileDebugLog } from '@/debug/mobileDebugLog';
import { selfHostedRelayAuthorizationFor } from '@/device-link/selfHostedRelayRouting';
/** 自建中转的 401 统一成这个码:只表示中转凭证失效,不可刷新账号 token,也不触发账号退出。 */
export const RELAY_CREDENTIAL_INVALID = 'RELAY_CREDENTIAL_INVALID';
/** 目标是自建中转但本机没有可用凭证:请求不发出。 */
export const RELAY_CREDENTIAL_UNAVAILABLE = 'RELAY_CREDENTIAL_UNAVAILABLE';
export class ApiError extends Error {
constructor(
public readonly code: string,
public readonly status: number,
message: string,
/** The server's structured `error.details`, when it sent an object. */
public readonly details?: Record<string, unknown>,
) {
super(message);
this.name = 'ApiError';
}
}
export interface ApiFetchOptions {
/** 目标服务 base URL(必传:老主 server 2026-07 退役后没有"默认业务 server")。 */
baseUrl: string;
method?: string;
token?: string | null;
body?: unknown;
timeoutMs?: number;
cache?: 'no-store';
/** Reject stale account-scoped work before transport or auth side effects. */
assertCurrent?: () => void;
/** Extra request headers (e.g. Chat Server's X-Chat-Actor); never overrides auth or content type. */
headers?: Record<string, string>;
/** Cancels this request, including body parsing, without terminating account auth. */
signal?: AbortSignal;
}
const DEFAULT_API_TIMEOUT_MS = 20_000;
type AccountUnavailableHandler = () => void | Promise<void>;
let accountUnavailableHandler: AccountUnavailableHandler | null = null;
/**
* Registers the process-wide terminal auth boundary used by low-level API
* helpers (uploads included). The returned disposer only removes its own
* registration, so a remounted AuthProvider cannot be cleared by an old one.
*/
export function registerAccountUnavailableHandler(
handler: AccountUnavailableHandler,
): () => void {
accountUnavailableHandler = handler;
return () => {
if (accountUnavailableHandler === handler) accountUnavailableHandler = null;
};
}
export async function apiFetchRaw<T>(
path: string,
opts: ApiFetchOptions,
): Promise<T> {
opts.assertCurrent?.();
if (opts.signal?.aborted) throw requestAborted();
// 自建中转(docs/self-hosted-relay-plan.md §5.3):按目标地址换成中转凭证,账号 token 不发过去。
const relayAuth = selfHostedRelayAuthorizationFor(opts.baseUrl);
if (relayAuth?.kind === 'blocked') {
throw new ApiError(RELAY_CREDENTIAL_UNAVAILABLE, 0, i18n.t('relay.errors.credentialUnavailable'));
}
const headers: Record<string, string> = { ...opts.headers, 'Content-Type': 'application/json' };
if (relayAuth) headers.Authorization = `CindyRelay ${relayAuth.credential}`;
else if (opts.token) headers.Authorization = `Bearer ${opts.token}`;
if (opts.cache === 'no-store') {
// Also tell native HTTP caches not to reuse or store short-lived responses.
headers['Cache-Control'] = 'no-cache, no-store';
headers.Pragma = 'no-cache';
}
let response: Response;
let data: unknown = null;
let timeoutId: ReturnType<typeof setTimeout> | null = null;
const timeoutMs = opts.timeoutMs ?? DEFAULT_API_TIMEOUT_MS;
const controller = timeoutMs > 0 ? new AbortController() : null;
let cancelRequest: (() => void) | undefined;
try {
const cancellation = opts.signal ? new Promise<never>((_resolve, reject) => {
cancelRequest = () => { controller?.abort(); reject(requestAborted()); };
opts.signal!.addEventListener('abort', cancelRequest, { once: true });
}) : null;
const requestPromise = (async (): Promise<{ response: Response; data: unknown }> => {
const nextResponse = await fetch(opts.baseUrl + path, {
method: opts.method ?? 'GET',
headers,
body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
signal: controller?.signal ?? opts.signal,
...(opts.cache ? { cache: opts.cache } : {}),
});
let nextData: unknown = null;
try {
nextData = await nextResponse.json();
} catch (error) {
if (opts.signal?.aborted) throw requestAborted();
if (nextResponse.status === 204 || nextResponse.status === 205) {
return { response: nextResponse, data: null };
}
// JSON SyntaxError messages/stacks can include response contents.
mobileDebugLog('warn', 'network', 'response read failed', { status: nextResponse.status },
error instanceof SyntaxError ? 'SyntaxError' : error);
if (nextResponse.ok) {
throw new ApiError('INVALID_RESPONSE', nextResponse.status, i18n.t('apiErrors.requestFailed'));
}
nextData = null;
}
return { response: nextResponse, data: nextData };
})();
const pending = [requestPromise];
if (cancellation) pending.push(cancellation);
if (timeoutMs > 0) pending.push(new Promise<never>((_, reject) => {
timeoutId = setTimeout(() => {
void requestPromise.catch(() => undefined);
reject(new ApiError('REQUEST_TIMEOUT', 0, i18n.t('apiErrors.requestTimeout')));
controller?.abort();
}, timeoutMs);
}));
const result = await Promise.race(pending);
response = result.response;
data = result.data;
} catch (err) {
// Explicit cancellation is not a timeout, network failure, or auth boundary.
if (opts.signal?.aborted) throw requestAborted();
if (!(err instanceof ApiError) || err.code === 'REQUEST_TIMEOUT') {
mobileDebugLog('warn', 'network', 'request failed', err);
}
if (err instanceof ApiError) throw err;
if (isAbortError(err)) {
throw new ApiError('REQUEST_TIMEOUT', 0, i18n.t('apiErrors.requestTimeout'));
}
if (err instanceof TypeError) {
// fetch 的网络层失败统一走类型化离线错误:RN 离线抛 "Network request failed"
// (不含 "fetch" 子串,旧分支匹配不到,英文原文会一路透传到 UI);浏览器
// (Web 预览)抛 "Failed to fetch",还可能是 CORS——只在 web 环境附加提示。
const webHint = typeof document !== 'undefined'
? i18n.t('apiErrors.networkUnavailableWebHint')
: '';
throw new ApiError('NETWORK_UNAVAILABLE', 0, i18n.t('apiErrors.networkUnavailable', { webHint }));
}
throw err;
} finally {
if (timeoutId) clearTimeout(timeoutId);
if (cancelRequest) opts.signal?.removeEventListener('abort', cancelRequest);
}
// A late old-account response must not terminate the newly active account.
opts.assertCurrent?.();
if (opts.signal?.aborted) throw requestAborted();
if (!response.ok) {
const error = readError(data);
// 中转(或它前面的代理)回的任何 401 都只说明中转凭证不对:不能被当成账号 token 过期去刷新,
// 更不能凭它自报的 ACCOUNT_UNAVAILABLE 让账号退出。
const code = relayAuth && response.status === 401
? RELAY_CREDENTIAL_INVALID
: error.code ?? `HTTP_${response.status}`;
if (response.status === 401 && code === 'ACCOUNT_UNAVAILABLE') {
try {
await accountUnavailableHandler?.();
} catch {
// Preserve the original typed API error even if local cleanup fails.
}
}
throw new ApiError(code, response.status, error.message ?? i18n.t('apiErrors.requestFailed'), error.details);
}
return data as T;
}
function requestAborted(): Error {
return Object.assign(new Error('Request cancelled'), { name: 'AbortError' });
}
function isAbortError(err: unknown): boolean {
return !!err && typeof err === 'object' && 'name' in err && err.name === 'AbortError';
}
function readError(data: unknown): { code?: string; message?: string; details?: Record<string, unknown> } {
if (!data || typeof data !== 'object') return {};
const payload = data as Record<string, unknown>;
const nested = payload.error;
const record = nested && typeof nested === 'object'
? nested as Record<string, unknown>
: payload;
return {
code: typeof record.code === 'string' ? record.code : undefined,
message: typeof record.message === 'string' ? record.message : undefined,
details: record.details && typeof record.details === 'object' && !Array.isArray(record.details)
? record.details as Record<string, unknown> : undefined,
};
}