Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* clientEndpoints — 客户端远程端点清单的共享 schema / 校验 / 严格解析。
*
* 背景:desktop / mobile 的生产端点在构建期内联进包体,发版后无法变更。CDN 上
* 存放一份公开读的清单(仓内正本 `config/endpoint.json` = cn、
* `config/endpoint.global.json` = global,人肉上传各自 region 的 CDN),
* 应用启动第一步、**先于检查更新**从 CDN 拉取;CDN 清单修改后重启应用生效。
* 完整拉取地址 = `<烘焙的 region 化 hotfix base>/endpoint.json`。
*
* 在线清单优先;网络失败后允许本区持久缓存、随包完整清单兜底。
* JSON/schema/非法 URL/区域不匹配与永久 HTTP 配置错误仍阻断,绝不逐字段合并。
* 缓存重新严格解析并按目标区域校验受信任域,来源地址变化即失效。
* 备用入口是构建期信任锚点,不能由下载的清单或缓存指定。
* 更新端点与审核元数据保持完整快照语义,账号区域切换不改变构建更新身份。
* - dev(desktop 未打包 / mobile __DEV__)默认不走 CDN,改读仓内正本文件
* (同一套解析,allowHttp 宽松协议见下);`--endpoints-cdn` /
* EXPO_PUBLIC_ENDPOINTS_CDN=1 可让 dev 走完整 CDN 链路。
*
* 职责边界(仓规则 2):本模块是纯逻辑层,不做任何 IO——fetch / 读文件 / 报错
* 交互由宿主(desktop main / mobile 启动闸门)实现,这里只提供确定性的解析与
* 校验(仓规则 9)。
*
* 校验语义:
* - CLIENT_ENDPOINT_KEYS 中的字段缺失或空白时统一解析为 `''`;不同 region 可以
* 不提供不适用的业务端点,不会因此阻断整个客户端启动;
* - 未知字段忽略(向前兼容:新客户端加字段后,老清单先补字段再发新客户端;
* 新清单多出的字段老客户端不认识但不报错);
* - 协议白名单、禁 URL 凭据、
* 尾斜杠归一;
* - `allowHttp` 宽松模式(仅 dev 本地文件路径允许开启):https-only 字段追加
* 接受 http:、wss 字段追加 ws:,让 endpoint.local.json 能填 localhost;
* packaged / CDN 路径一律不开,打包校验零放松;
* - schemaVersion 缺失、非正整数或大于当前支持版本 → 整份拒绝(breaking change
* 才 bump 版本)。2026-07 追加 cdnBaseUrl 时**没有** bump:新字段随全新的
* hotfix CDN 域名 + `/endpoint.json` 路径发布,老客户端读的是老 CDN 老路径
* (`/config/client-endpoints.json`)看不到新清单;即使把新正本内容双写到
* 老路径,多出的字段也会被老 parser 按"未知字段"忽略——bump 的语义是
* "同一文件的不兼容重释义",纯增字段 + 换发布地址不构成。
* - 2026-07 稍后退役 cdnInternalBaseUrl(内网加速镜像下线,更新链只走
* cdnBaseUrl)同样没有 bump:删必填字段对**新客户端**是纯放松(清单里多出
* 的该字段按未知字段忽略);退役时新路径清单尚无已发布的 packaged 消费者,
* 线上清单已同步删除,无兼容包袱。
* - 2026-07-17 追加可选字符串字段 review(手机版审核模式的送审版本号,见
* CLIENT_ENDPOINT_REVIEW_KEY)同样没有 bump:可选字段、缺失/空串即关闭,
* 老清单不受影响;老客户端按未知字段忽略。
* - 2026-07-17 退役 xdGatewayBaseUrl(同样不 bump,理由同上):XD 网关推理
* 入口一律由 model-access server 随凭据成对下发(desktop
* model-access/effectiveEndpoint.ts),清单不再承载网关端点,杜绝
* 「key 与 endpoint 不同租户」的撕裂组合;mobile 语音的网关地址经桌面端
* device-link 凭据同步获得,不再吃清单默认值。
*/
/** 当前客户端支持的清单 schema 版本;清单里更大的版本号会被整份拒绝。 */
export const CLIENT_ENDPOINTS_SCHEMA_VERSION = 1;
/**
* 清单字段全集 = 客户端可能消费的端点集合。不同 region 可缺省或留空不适用的
* 字段;解析结果仍补齐所有 key,让既有消费方保持稳定的 string 读取接口。
*/
export const CLIENT_ENDPOINT_KEYS = [
// apiBaseUrl(老主 server xdt-api)已于 2026-07-18 退役(不 bump,删必填字段
// 对新客户端是纯放松):四块业务消费方分批迁至独立服务(chat-data 删除 /
// SlackIM→slack-hook / GitHub 反馈→githubApiBaseUrl / Skillhub→
// skillhubApiBaseUrl)。退役时清单体系尚无已发布的 packaged/mobile 消费者,
// 正本(=CDN 上传源)已同步删值,无兼容包袱(同 cdnInternalBaseUrl 先例)。
// 每份清单只描述自身 region 的 auth/业务端点。默认会话读取构建清单;
// 跨区域组织登录会先加载目标 region 清单,再整体切换 token 消费端点。
'authApiBaseUrl',
// desktop 系统浏览器登录的**服务端托管回调**地址(auth-server 路由,精确值需与
// 服务端 redirect_uri allowlist 逐字符一致)。非空 = 走托管回调链路:回调页停在
// 自有域名、授权码由客户端轮询取回,浏览器地址栏不再出现 127.0.0.1 与 code;
// 空 = 回落到 RFC 8252 loopback(现状行为)。这也是本能力的灰度/回滚开关——
// 服务端出问题时清空本字段即可回退,客户端不必发版。
// 不 bump schemaVersion:纯增可选字段,老清单缺失即 '',老客户端按未知字段忽略
// (同 review / cdnBaseUrl 先例,理由见上方版本注释)。
'authDesktopCallbackUrl',
'chatApiBaseUrl',
'deviceLinkApiBaseUrl',
'oauthBrokerApiBaseUrl',
// oss-server(公开资产直传预签名,当前场景:头像上传)。
'ossApiBaseUrl',
'heartbeatUrl',
// Telegram hook is deployed independently from Slack; empty means the
// current environment has not rolled out Telegram yet.
'telegramHookWsUrl',
// X (Twitter) hook, same deployment model as Telegram; empty (or a manifest
// that omits the key entirely) means X has not rolled out yet — the Settings
// card stays hidden, which is the intended gradual-rollout switch.
'xHookWsUrl',
'slackHookWsUrl',
'websiteUrl',
// model-access-server(登录后自动下发 LLM 网关凭据)的 API 基址。
'modelAccessApiBaseUrl',
// voice-server(一期开通免费语音输入的数据面)API 基址。
'voiceApiBaseUrl',
// github-server(用户反馈 → 官方仓 GitHub issue 的薄代理)的 API 基址。
'githubApiBaseUrl',
// 旧 xd-skillhub-server 的 API 基址。已发布客户端继续消费这个字段,值不得
// 改指新服务;新客户端只消费下方 cindySkillHubApiBaseUrl。
'skillhubApiBaseUrl',
// cindy-skill-hub-server 的 API 基址。纯增可选字段,不 bump schemaVersion:
// 老客户端按未知字段忽略,新客户端缺失时明确关闭云端 Skill Hub,不回退旧地址。
'cindySkillHubApiBaseUrl',
// plugin-server(Plugin/Skill 市场、组织管理与发布)的 API 基址。
'pluginApiBaseUrl',
// Independent sharing website. Missing disables preparation; never guess a domain.
'shareBaseUrl',
// 更新/hotfix 链的 CDN base(manifest-*.json / hotfix 包 / agent 二进制)。
'cdnBaseUrl',
// 自建线手机整包发现的 mobile-update-server 基址(`${base}/latest`)。仅
// mobile 自建变体(IS_OTA_SELFHOST)消费,desktop 与 EAS 线不读;清单值
// 优先于烧包的 EXPO_PUBLIC_XDT_OTA_URL,让已发自建包可远程迁域名。
// 注意热更通道的 updates.url 仍烧在原生层(expo-updates 架构),不吃本字段。
'mobileUpdateBaseUrl',
] as const;
export type ClientEndpointKey = (typeof CLIENT_ENDPOINT_KEYS)[number];
/** 解析成功后的端点全集(全 key 存在;清单缺失/空白的字段值为 `''`)。 */
export type ClientEndpointMap = Record<ClientEndpointKey, string>;
/** auth-server 的物理部署区域;与 App 包体的品牌/更新区域是两个独立概念。 */
export type ClientEndpointRegion = 'cn' | 'global';
export type RealmManifestBaseUrls = Readonly<
Record<ClientEndpointRegion, string>
>;
/**
* 可选字符串字段:`review` = 手机版审核模式的**送审版本号**(App 审核期间填
* 送审构建的二进制版本号,如 "1.4.0")。mobile 启动时用它与自身二进制版本号
* **严格相等匹配**,且 iOS StoreKit 未识别为 TestFlight 时才进入审核模式:
* TestFlight 即使版本命中也继续更新;其余命中构建关闭全部 JS 显式更新检查路径(启动
* JS 热更门 / 整包检查 / resume 静默检查)直接进主界面,设置页隐藏「检查更新 /
* 检查整包更新」;desktop 不消费。按版本定向的意义:清单是 region 级共享文件,
* 版本匹配把影响面从"全量用户"收窄到"同版本号的构建"——存量其它版本用户的
* 更新检查与强更通道不受影响。注意命中粒度是**版本号而非送审构建本身**:
* app.json 的 version 为 iOS/Android 各变体共用,若送审版本号与其它平台/变体
* 正在线上跑的版本号相同,这些同版本用户也会进入审核模式(iOS TestFlight 除外);
* 填写前需确认送审版本号未与其它线上线重叠,或接受重叠期影响。
* **可选、缺失或空串即关闭**——线上已发布的清单没有该字段,若设为必填会让新
* 客户端对老清单启动阻断;可选纯增量也是不 bump schemaVersion 的前提(见上方
* 版本注释)。存在但非 string 视为配置错,整份拒绝(配置错要炸出来,不静默猜测)。
* 覆盖边界与运维义务(填写前必须知晓):
* - **管不到 expo-updates 原生层**:CheckOnLaunch 是 build-time 原生配置
* (当前烘焙 ALWAYS),冷启动仍会后台静默 check+下载、下次启动生效——
* 该缺口无法用运行时清单字段封,审核窗口内需同时冻结热更发布;
* - 送审版本过审对外发布后必须及时把该字段清回 ""(或删除),否则线上同
* 版本的非 TestFlight 用户会一直处于审核模式、收不到后续 JS 更新检查与强更提示。
*/
export const CLIENT_ENDPOINT_REVIEW_KEY = 'review';
/** 各字段允许的 URL 协议白名单。 */
const FIELD_PROTOCOLS: Record<ClientEndpointKey, readonly string[]> = {
authApiBaseUrl: ['https:'],
authDesktopCallbackUrl: ['https:'],
chatApiBaseUrl: ['https:'],
deviceLinkApiBaseUrl: ['https:'],
oauthBrokerApiBaseUrl: ['https:'],
ossApiBaseUrl: ['https:'],
heartbeatUrl: ['https:'],
telegramHookWsUrl: ['wss:'],
xHookWsUrl: ['wss:'],
slackHookWsUrl: ['wss:'],
websiteUrl: ['https:'],
modelAccessApiBaseUrl: ['https:'],
voiceApiBaseUrl: ['https:'],
githubApiBaseUrl: ['https:'],
skillhubApiBaseUrl: ['https:'],
cindySkillHubApiBaseUrl: ['https:'],
pluginApiBaseUrl: ['https:'],
shareBaseUrl: ['https:'],
cdnBaseUrl: ['https:'],
mobileUpdateBaseUrl: ['https:'],
};
/** 解析选项;allowHttp 仅供 dev 本地文件路径(endpoint.local.json 等)开启。 */
export interface ParseClientEndpointManifestOptions {
/** true 时 https-only 字段追加接受 http:、wss 字段追加 ws:(localhost 场景)。 */
allowHttp?: boolean;
/** 加载指定区域的清单时必须提供;清单自报区域不一致或缺失会整份拒绝。 */
expectedRegion?: ClientEndpointRegion;
}
// 去尾部斜杠。不用 /\/+$/ 正则——超长 '/' 串上会 O(n²) 回溯(CodeQL js/polynomial-redos)。
function trimTrailingSlashes(s: string): string {
let end = s.length;
while (end > 0 && s.charCodeAt(end - 1) === 0x2f) end -= 1;
return s.slice(0, end);
}
function allowedProtocols(
key: ClientEndpointKey,
allowHttp: boolean,
): readonly string[] {
const base = FIELD_PROTOCOLS[key];
if (!allowHttp) return base;
const relaxed = [...base];
if (base.includes('https:') && !base.includes('http:')) relaxed.push('http:');
if (base.includes('wss:') && !base.includes('ws:')) relaxed.push('ws:');
return relaxed;
}
export type ParseClientEndpointManifestResult =
| {
ok: true;
endpoints: ClientEndpointMap;
reviewVersion: string | null;
/** 可选诊断元数据;缺失时由受信任清单地址确定区域。 */
region: ClientEndpointRegion | null;
}
| { ok: false; reason: string };
/**
* 解析并校验一份清单原文。纯函数,输入任意文本都不会抛出。
* 端点缺失 / 空白时写入 `''` 并继续;非空值仍校验 URL、协议与凭据;
* `review` 可选字符串(送审版本号),缺失 / 空白 = null 即审核模式关闭
* (语义见 CLIENT_ENDPOINT_REVIEW_KEY)。
*/
export function parseClientEndpointManifest(
rawText: string,
options?: ParseClientEndpointManifestOptions,
): ParseClientEndpointManifestResult {
let parsed: unknown;
try {
parsed = JSON.parse(rawText);
} catch {
return { ok: false, reason: 'invalid-json' };
}
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
return { ok: false, reason: 'not-an-object' };
}
const record = parsed as Record<string, unknown>;
const schemaVersion = record.schemaVersion;
if (
typeof schemaVersion !== 'number' ||
!Number.isInteger(schemaVersion) ||
schemaVersion < 1
) {
return { ok: false, reason: 'invalid-schema-version' };
}
if (schemaVersion > CLIENT_ENDPOINTS_SCHEMA_VERSION) {
return { ok: false, reason: `unsupported-schema-version:${schemaVersion}` };
}
const endpoints = {} as ClientEndpointMap;
for (const key of CLIENT_ENDPOINT_KEYS) {
const raw = record[key];
if (raw === undefined || (typeof raw === 'string' && !raw.trim())) {
endpoints[key] = '';
continue;
}
if (typeof raw !== 'string') {
return { ok: false, reason: `invalid-field:${key}` };
}
const normalized = trimTrailingSlashes(raw.trim());
let url: URL;
try {
url = new URL(normalized);
} catch {
return { ok: false, reason: `invalid-field:${key}` };
}
if (
!allowedProtocols(key, options?.allowHttp === true).includes(url.protocol)
) {
return { ok: false, reason: `invalid-protocol:${key}` };
}
if (url.username || url.password) {
return { ok: false, reason: `credentials-in-url:${key}` };
}
endpoints[key] = normalized;
}
const rawReview = record[CLIENT_ENDPOINT_REVIEW_KEY];
if (rawReview !== undefined && typeof rawReview !== 'string') {
return { ok: false, reason: `invalid-field:${CLIENT_ENDPOINT_REVIEW_KEY}` };
}
const reviewVersion =
typeof rawReview === 'string' && rawReview.trim() ? rawReview.trim() : null;
const rawRegion = record.region;
const region =
rawRegion === undefined
? null
: rawRegion === 'cn' || rawRegion === 'global'
? rawRegion
: null;
if (rawRegion !== undefined && region === null) {
return { ok: false, reason: 'invalid-field:region' };
}
if (
options?.expectedRegion !== undefined &&
region !== options.expectedRegion
) {
return {
ok: false,
reason: `region-mismatch:${options.expectedRegion}:${region ?? 'missing'}`,
};
}
return {
ok: true,
endpoints,
reviewVersion,
region,
};
}
export type ResolveClientEndpointsResult =
| Extract<ParseClientEndpointManifestResult, { ok: true }>
| { ok: false; reason: string };
/**
* 解析清单原文 → 完整端点 map(缺失/空白字段补 `''`,无任何本地合并)。
* rawText 为 null(拉取失败/超时)→ ok:false('fetch-failed'),宿主必须阻断并重试。
*/
export function resolveClientEndpointsStrict(
rawText: string | null,
options?: ParseClientEndpointManifestOptions,
): ResolveClientEndpointsResult {
if (rawText === null) {
return { ok: false, reason: 'fetch-failed' };
}
return parseClientEndpointManifest(rawText, options);
}