Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
#!/usr/bin/env node
/**
* update.mjs — 下载 @anthropic-ai/claude-code 各平台可执行文件
*
* 用法:
* node tools/claude/update.mjs # 拉最新版
* node tools/claude/update.mjs 2.1.100 # 指定版本
*
* 流程(不指定版本):
* 1. 拉取 npm registry 的 latest 元数据
* 2. 与本地缓存 latest.json 对比 version
* 3. 版本相同:仅刷新本地 JSON 缓存,退出
* 4. 版本不同:下载到 tools/claude/updates/{version}/{platform}/
* 全部成功后再写入缓存 JSON(失败下一次会自动重试)
*
* 流程(指定版本):
* 直接下载到 tools/claude/updates/{version}/{platform}/
* 已存在的文件会跳过(用 --force 覆盖),不写缓存 JSON
*
* 供应链加固:每次真正下载(非跳过)后,用官方 per-version manifest.json 里该平台的 checksum
* 对下载的二进制做 sha256 校验,不符 / 拿不到可信 hash 一律删文件并 exit 1(fail-closed),绝不落地。
*/
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
import { fetchJsonWithTimeout, downloadToFileWithTimeout, createDownloadProgressLogger } from '../shared/fetch-with-timeout.mjs';
import { verifyFileSha256OrRemove, normalizeExpectedSha256 } from '../shared/verify-sha256.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const PROJECT_ROOT = path.resolve(__dirname, '../..');
const NPM_URL = 'https://registry.npmjs.org/@anthropic-ai/claude-code/latest';
// 官方 per-version 发布清单(与二进制同一 downloads.claude.ai 端点、同源 TLS)。
// 结构:{ version, platforms: { <platformKey>: { binary, checksum(裸二进制 sha256 hex), size } } }。
// 这是官方 installer 自身用来校验的清单,作为 dev/CI 下载校验的可信 sha256 来源。
const MANIFEST_URL = (version) => `https://downloads.claude.ai/claude-code-releases/${version}/manifest.json`;
const CACHE_FILE = path.join(__dirname, 'latest.json');
const UPDATES_DIR = path.join(__dirname, 'updates');
const BIN_DIR = path.join(PROJECT_ROOT, 'apps', 'claude-code-bin');
const PLATFORMS = [
{ key: 'darwin-arm64', file: 'claude' },
{ key: 'darwin-x64', file: 'claude' },
// Verified 2026-06-17 by HEAD request against downloads.claude.ai for the
// latest npm version: linux-x64 uses the same plain `claude` binary name.
{ key: 'linux-x64', file: 'claude' },
// Verified 2026-07-24 against the official release manifest
// (claude-code-releases/<version>/manifest.json): linux-arm64 (glibc) is
// published with the same plain `claude` binary name and a checksum entry.
{ key: 'linux-arm64', file: 'claude' },
{ key: 'win32-x64', file: 'claude.exe' },
];
// ── Helpers ────────────────────────────────────────────────────────────────
async function fetchLatestMeta() {
return fetchJsonWithTimeout(NPM_URL);
}
async function fetchMetaForVersion(version) {
return fetchJsonWithTimeout(`https://registry.npmjs.org/@anthropic-ai/claude-code/${version}`);
}
/** 拉取该版本的官方发布清单;非 2xx / 超时 / 解析失败均抛错(由调用方 fail-closed 处理)。 */
async function fetchReleaseManifest(version) {
return fetchJsonWithTimeout(MANIFEST_URL(version));
}
/** 从清单取某平台的可信二进制 sha256(归一化为小写 hex);缺失 / 格式非法返回 null。 */
function checksumForPlatform(manifest, platformKey) {
return normalizeExpectedSha256(manifest?.platforms?.[platformKey]?.checksum);
}
/**
* 生成一个"按需拉清单 + 取平台 checksum"的 resolver:清单只在第一次真正需要时拉一次并缓存,
* 让"全平台已就位、无需下载"的快捷路径不必联网拉清单(离线从 updates 缓存 promote 仍可用)。
*/
function makeChecksumResolver(version) {
let manifestPromise = null;
return async (platformKey) => {
if (!manifestPromise) manifestPromise = fetchReleaseManifest(version);
return checksumForPlatform(await manifestPromise, platformKey);
};
}
function readCachedVersion() {
if (!fs.existsSync(CACHE_FILE)) return null;
try {
const json = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
return json.version || null;
} catch {
return null;
}
}
async function saveCache(meta) {
const version = meta.version;
if (!version) throw new Error('Cannot pin Claude runtime assets without a version');
const manifest = await fetchReleaseManifest(version);
const runtimeAssets = Object.fromEntries(PLATFORMS.map(({ key, file }) => {
const entry = manifest?.platforms?.[key];
const sha256 = normalizeExpectedSha256(entry?.checksum);
if (!sha256) throw new Error(`Cannot pin Claude ${version} ${key}: manifest checksum is missing`);
return [key, {
url: `https://downloads.claude.ai/claude-code-releases/${version}/${key}/${file}`,
sha256,
...(typeof entry?.size === 'number' && entry.size > 0 ? { size: entry.size } : {}),
}];
}));
fs.writeFileSync(CACHE_FILE, JSON.stringify({ ...meta, runtimeAssets }, null, 2) + '\n');
}
function formatMB(bytes) {
return (bytes / 1024 / 1024).toFixed(1) + ' MB';
}
const LFS_POINTER_HEADER = 'version https://git-lfs.github.com/spec/v1';
/**
* 缓存文件是否可用——存在、≥1KB、且不是 Git LFS pointer。
* 只判 existsSync 会把旧 checkout 残留的 LFS pointer / 截断文件当成有效缓存,
* 导致 ensure 反复复制坏文件且无法自修复(见 PR review)。
*/
function isUsableCache(filePath) {
try {
if (fs.statSync(filePath).size < 1024) return false;
const fd = fs.openSync(filePath, 'r');
try {
const buf = Buffer.alloc(64);
const n = fs.readSync(fd, buf, 0, buf.length, 0);
if (buf.subarray(0, n).toString('utf8').startsWith(LFS_POINTER_HEADER)) return false;
} finally {
fs.closeSync(fd);
}
return true;
} catch {
return false;
}
}
/** 指定版本下,目标平台的 updates/<version>/<platform>/<file> 是否都已是可用缓存。 */
function targetsExist(version, targets) {
return targets.every(({ key, file }) => isUsableCache(path.join(UPDATES_DIR, version, key, file)));
}
// throughputGuard:龟速掐断(吞吐低于下限即放弃)只允许 install 链路(ensurePlatform)开启——
// 那条链有 CDN 兜底,尽早放弃上游才有意义;update CLI 直连上游无兜底(CDN 不会有比
// release 更新的版本),掐断只会把"慢但能成"变成失败,故默认关闭。
async function downloadBinary(version, platformKey, fileName, { force = false, throughputGuard = false, resolveExpectedSha256 = null } = {}) {
const url = `https://downloads.claude.ai/claude-code-releases/${version}/${platformKey}/${fileName}`;
const destDir = path.join(UPDATES_DIR, version, platformKey);
const destPath = path.join(destDir, fileName);
fs.mkdirSync(destDir, { recursive: true });
if (!force && isUsableCache(destPath)) {
if (resolveExpectedSha256) {
const cachedHash = await resolveExpectedSha256(platformKey);
if (!cachedHash) {
throw new Error(`[${platformKey}] trusted sha256 not available for claude ${platformKey} v${version}: cannot verify cached binary (fail-closed)`);
}
verifyFileSha256OrRemove(destPath, cachedHash, `claude ${platformKey} binary v${version} (cached)`);
const size = fs.statSync(destPath).size;
console.log(` [${platformKey}] skip (cached, sha256 ok, ${formatMB(size)})`);
return;
}
const size = fs.statSync(destPath).size;
console.log(` [${platformKey}] skip (already exists, ${formatMB(size)})`);
return;
}
// 供应链加固:下载前先取可信 sha256;resolver 缺失或 hash 拿不到即 fail-closed,不浪费数百 MB 下载。
if (!resolveExpectedSha256) {
throw new Error(`[${platformKey}] no sha256 resolver — cannot download without trusted checksum source`);
}
const expectedSha256 = await resolveExpectedSha256(platformKey);
if (!expectedSha256) {
throw new Error(`[${platformKey}] trusted sha256 not available for claude ${platformKey} v${version}: manifest missing this platform. Refusing download (fail-closed).`);
}
console.log(` [${platformKey}] ${url}`);
const progress = createDownloadProgressLogger(platformKey);
try {
await downloadToFileWithTimeout(url, destPath, {}, {
onProgress: progress.onProgress,
minThroughputBytesPerSec: throughputGuard ? undefined : 0, // undefined → env/默认值生效
});
} finally {
progress.finish();
}
// 校验下载的二进制;不符 / 无可信 hash → 删除文件并抛错(fail-closed,绝不落地未验证二进制)。
verifyFileSha256OrRemove(destPath, expectedSha256, `claude ${platformKey} binary v${version}`);
console.log(` [${platformKey}] sha256 ok`);
// darwin 二进制需要可执行权限(Windows 不需要)
if (!fileName.endsWith('.exe')) {
try { fs.chmodSync(destPath, 0o755); } catch { /* ignore */ }
}
const size = fs.statSync(destPath).size;
console.log(` → ${destPath} (${formatMB(size)})`);
}
/**
* 把单个平台的 updates/<version>/<platform>/<binary> 拷到 apps/claude-code-bin/<platform>/。
* 源文件缺失会 warn 跳过;目标被占用(app 运行中)也 warn 跳过。
*/
function promoteOnePlatform(version, key, file) {
const srcPath = path.join(UPDATES_DIR, version, key, file);
const destDir = path.join(BIN_DIR, key);
const destPath = path.join(destDir, file);
if (!fs.existsSync(srcPath)) {
console.warn(` [${key}] WARN: source missing, skipping (${srcPath})`);
return;
}
fs.mkdirSync(destDir, { recursive: true });
try {
fs.copyFileSync(srcPath, destPath);
} catch (err) {
if (err.code === 'EBUSY' || err.code === 'ETXTBSY') {
console.warn(` [${key}] WARN: target locked (probably running). Close the app and re-run, or copy manually:`);
console.warn(` cp "${srcPath}" "${destPath}"`);
return;
}
throw err;
}
if (!file.endsWith('.exe')) {
try { fs.chmodSync(destPath, 0o755); } catch { /* ignore */ }
}
// 写版本标记,供 scripts/ensure-agent-binaries.mjs 判断是否需要随 pin 升级刷新
try { fs.writeFileSync(path.join(destDir, '.version'), version + '\n'); } catch { /* ignore */ }
const size = fs.statSync(destPath).size;
console.log(` [${key}] → ${destPath} (${formatMB(size)})`);
}
/**
* 把 updates/<version>/<platform>/<binary> 同步到 apps/claude-code-bin/<platform>/<binary>。
* 只有当源文件存在时才覆盖目标——某平台缺失会 warn 跳过。
*/
function promoteToVendorBin(version, platforms = PLATFORMS) {
console.log('');
console.log(`==> Promoting to apps/claude-code-bin/ ...`);
for (const { key, file } of platforms) {
promoteOnePlatform(version, key, file);
}
}
// ── Programmatic API(供 scripts/ensure-agent-binaries.mjs 复用) ─────────────
/** 读 latest.json 里 pin 的版本号(按需下载以此为准,不取 upstream latest)。 */
export function readPinnedVersion() {
return readCachedVersion();
}
/**
* 确保单个平台的二进制就位:下载到 updates/ 并 promote 到 apps/claude-code-bin/<platformKey>/。
* 已存在合法文件时 downloadBinary 会自动跳过(除非 force)。
*/
export async function ensurePlatform({ version, platformKey, force = false }) {
const entry = PLATFORMS.find((p) => p.key === platformKey);
if (!entry) throw new Error(`Unknown platform key for claude: ${platformKey}`);
// install 链路(ensure-agent-binaries)有 CDN 兜底,开启吞吐守卫尽早切换
await downloadBinary(version, platformKey, entry.file, {
force,
throughputGuard: true,
resolveExpectedSha256: makeChecksumResolver(version),
});
promoteOnePlatform(version, platformKey, entry.file);
}
// ── Args ───────────────────────────────────────────────────────────────────
function parseArgs(argv) {
const args = { version: null, force: false, platform: null };
for (const a of argv) {
if (a === '--force' || a === '-f') args.force = true;
else if (a.startsWith('--platform=')) args.platform = a.slice('--platform='.length);
else if (a.startsWith('--version=')) args.version = a.slice('--version='.length);
else if (!a.startsWith('-')) args.version = a;
}
return args;
}
function resolvePlatforms(platformKey) {
if (!platformKey) return PLATFORMS;
const entry = PLATFORMS.find((p) => p.key === platformKey);
if (!entry) throw new Error(`Unknown --platform=${platformKey} (known: ${PLATFORMS.map((p) => p.key).join(', ')})`);
return [entry];
}
// ── Main ───────────────────────────────────────────────────────────────────
async function main() {
const { version: requestedVersion, force, platform } = parseArgs(process.argv.slice(2));
const targets = resolvePlatforms(platform);
if (requestedVersion) {
console.log(`==> Pinning claude-code to ${requestedVersion} (specified)...`);
const resolveExpectedSha256 = makeChecksumResolver(requestedVersion);
for (const { key, file } of targets) {
await downloadBinary(requestedVersion, key, file, { force, resolveExpectedSha256 });
}
promoteToVendorBin(requestedVersion, targets);
// 指定版本 == bump pin:写回 latest.json,使其成为唯一真相源(install / ensure 据此对齐)。
await saveCache(await fetchMetaForVersion(requestedVersion));
console.log('');
console.log('=== Done ===');
console.log(`Version: ${requestedVersion}`);
console.log(`Output: ${path.join(UPDATES_DIR, requestedVersion)}`);
console.log(`Bin: ${BIN_DIR}`);
return;
}
console.log('==> Fetching latest version from npm registry...');
const meta = await fetchLatestMeta();
const latestVersion = meta.version;
if (!latestVersion) throw new Error('No "version" field in npm metadata');
const cachedVersion = readCachedVersion();
console.log(` Latest: ${latestVersion}`);
console.log(` Cached: ${cachedVersion ?? '(none)'}`);
// 仅当目标平台的 updates 文件齐备时才走快捷路径——否则(如 clean checkout:latest.json 已是最新
// 但 updates/<ver>/<plat> 缺失)必须 fall through 去真正下载,不能只 promote 出一个空 bin 就报成功。
if (cachedVersion === latestVersion && !force && targetsExist(latestVersion, targets)) {
await saveCache(meta); // 刷新缓存(保持 JSON 新鲜)
promoteToVendorBin(latestVersion, targets); // 即使没下载,也确保 bin 与 updates 一致
console.log('==> Already up to date.');
return;
}
console.log(`==> New version detected (${cachedVersion ?? 'none'} → ${latestVersion}), downloading...`);
const resolveExpectedSha256 = makeChecksumResolver(latestVersion);
for (const { key, file } of targets) {
await downloadBinary(latestVersion, key, file, { force, resolveExpectedSha256 });
}
// 所有平台下载成功后再更新缓存,中途失败下一次会自动重试
await saveCache(meta);
promoteToVendorBin(latestVersion, targets);
console.log('');
console.log('=== Done ===');
console.log(`Version: ${latestVersion}`);
console.log(`Output: ${path.join(UPDATES_DIR, latestVersion)}`);
console.log(`Bin: ${BIN_DIR}`);
}
const isMain = import.meta.url === pathToFileURL(process.argv[1] ?? '').href;
if (isMain) {
main().catch((err) => {
console.error(err);
process.exit(1);
});
}