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。

fix(plugins): bound downloads and hand artifacts through host receipts

Dash970e4cdad86c
diff --git a/apps/desktop/src/main/cindy-brain/__tests__/downloadCache.test.ts b/apps/desktop/src/main/cindy-brain/__tests__/downloadCache.test.ts
new file mode 100644
index 0000000000..43bf9dfc4d
--- /dev/null
+++ b/apps/desktop/src/main/cindy-brain/__tests__/downloadCache.test.ts
@@ -0,0 +1,38 @@
+import { expect, it } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { PluginDownloadCache } from '../downloadCache';
+
+it('shares quota across plugins, protects reserved/pinned files, and revokes evicted receipts', async () => {
+ const root = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), 'download-quota-test-')));
+ const cache = new PluginDownloadCache(148000);
+ const a = path.join(root, 'p', 'a'.repeat(64)),
+ b = path.join(root, 'q', 'b'.repeat(64)),
+ c = path.join(root, 'r', 'c'.repeat(64));
+ try {
+ await cache.reserve(root, a, 10000);
+ await expect(cache.reserve(root, b, 10000)).rejects.toThrow('full');
+ await fs.writeFile(path.join(a, 'artifact'), Buffer.alloc(10000));
+ const token = await cache.issue(a, 'owner', 'p', 'approved');
+ cache.release(a);
+ const lease = await cache.acquire(token, 'owner', 'p', 'approved');
+ await cache.reserve(root, b, 4000);
+ await expect(cache.reserve(root, c, 4000)).rejects.toThrow('full');
+ expect(await fs.readFile(lease.path)).toHaveLength(10000);
+ cache.revokeAll();
+ await expect(cache.acquire(token, 'owner', 'p', 'approved')).rejects.toThrow(
+ 'Invalid download receipt',
+ );
+ lease.release();
+ const retainedToken = await cache.issue(a, 'owner', 'p', 'approved');
+ cache.release(b);
+ await fs.writeFile(path.join(b, 'artifact'), Buffer.alloc(80000));
+ await cache.reserve(root, c, 4000);
+ await expect(cache.acquire(retainedToken, 'owner', 'p', 'approved')).rejects.toThrow();
+ await expect(cache.acquire(token, 'owner', 'p', 'approved')).rejects.toThrow();
+ cache.release(c);
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+});
diff --git a/apps/desktop/src/main/cindy-brain/__tests__/downloadSlot.test.ts b/apps/desktop/src/main/cindy-brain/__tests__/downloadSlot.test.ts
index 4f665ea396..cef4247856 100644
--- a/apps/desktop/src/main/cindy-brain/__tests__/downloadSlot.test.ts
+++ b/apps/desktop/src/main/cindy-brain/__tests__/downloadSlot.test.ts
@@ -4,30 +4,156 @@ import os from 'node:os';
import path from 'node:path';
import { PluginDownloadSlot } from '../downloadSlot';
import type { InstalledGhost } from '../../../shared/ghost';
-it('restricts redirects, rejects arbitrary paths and isolates owner delivery', async()=>{
- const root=await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(),'plugin-download-test-')));
- let scope='a';const events:unknown[]=[];
- const ghost={enabled:true,approval:{state:'approved'},manifest:{node:{},network:{hosts:['github.com']}}} as unknown as InstalledGhost;
- let calls=0;
- const slot=new PluginDownloadSlot({root:()=>root,scope:()=>scope,getGhost:()=>ghost,send:(_,e)=>events.push(e),download:async o=>{
- calls++;expect(()=>o.validateUrl!('https://evil.invalid/file')).toThrow();
- expect(()=>o.validateUrl!('http://github.com/file')).toThrow();
- o.onProgress?.({loaded:1,total:2,percent:50,speedBps:1});
- scope='b';return {path:o.targetPath,size:2,sha256:o.sha256,fromCache:false,durationMs:1,resumedFromBytes:0};
- }});
- const req={kind:'start',id:'x',url:'https://github.com/file',sha256:'a'.repeat(64),bytes:2};
- try{
- expect(await slot.handle('p',{...req,targetPath:'/tmp/arbitrary'})).toMatchObject({ok:false});
- expect(calls).toBe(0);
- expect(await slot.handle('p',req)).toMatchObject({ok:false});
- expect(calls).toBe(1);
- expect(events.filter((x:any)=>x.data.phase==='completed')).toHaveLength(0);
- }finally{await fs.rm(root,{recursive:true,force:true});}
+it('restricts redirects, rejects arbitrary paths and isolates owner delivery', async () => {
+ const root = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), 'plugin-download-test-')));
+ let scope = 'a';
+ const events: unknown[] = [];
+ const ghost = {
+ enabled: true,
+ approval: { state: 'approved' },
+ manifest: { node: {}, network: { hosts: ['github.com'] } },
+ } as unknown as InstalledGhost;
+ let calls = 0;
+ const slot = new PluginDownloadSlot({
+ root: (id) => path.join(root, id),
+ scope: () => scope,
+ getGhost: () => ghost,
+ send: (_, e) => events.push(e),
+ download: async (o) => {
+ calls++;
+ expect(() => o.validateUrl!('https://evil.invalid/file')).toThrow();
+ expect(() => o.validateUrl!('http://github.com/file')).toThrow();
+ o.onProgress?.({ loaded: 1, total: 2, percent: 50, speedBps: 1 });
+ scope = 'b';
+ return {
+ path: o.targetPath,
+ size: 2,
+ sha256: o.sha256,
+ fromCache: false,
+ durationMs: 1,
+ resumedFromBytes: 0,
+ };
+ },
+ });
+ const req = {
+ kind: 'start',
+ id: 'x',
+ url: 'https://github.com/file',
+ sha256: 'a'.repeat(64),
+ bytes: 2,
+ };
+ try {
+ expect(await slot.handle('p', { ...req, targetPath: '/tmp/arbitrary' })).toMatchObject({
+ ok: false,
+ });
+ expect(calls).toBe(0);
+ expect(await slot.handle('p', req)).toMatchObject({ ok: false });
+ expect(calls).toBe(1);
+ expect(events.filter((x: any) => x.data.phase === 'completed')).toHaveLength(0);
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
});
-it('cancel reaches only the matching active request',async()=>{
- const root=await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(),'plugin-download-test-')));
- const ghost={enabled:true,approval:{},manifest:{node:{},network:{hosts:['github.com']}}} as unknown as InstalledGhost;
- let started!:()=>void;const ready=new Promise<void>(r=>started=r);
- const slot=new PluginDownloadSlot({root:()=>root,scope:()=> 'a',getGhost:()=>ghost,send:()=>{},download:async o=>new Promise((_,reject)=>{started();o.signal!.addEventListener('abort',()=>reject(Error('aborted')));})});
- try{const work=slot.handle('p',{kind:'start',id:'x',url:'https://github.com/file',sha256:'a'.repeat(64),bytes:2});await ready;await slot.handle('p',{kind:'cancel',id:'x'});expect(await work).toMatchObject({ok:false,message:'下载已取消'});}finally{await fs.rm(root,{recursive:true,force:true});}
+it('cancel reaches only the matching active request', async () => {
+ const root = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), 'plugin-download-test-')));
+ const ghost = {
+ enabled: true,
+ approval: {},
+ manifest: { node: {}, network: { hosts: ['github.com'] } },
+ } as unknown as InstalledGhost;
+ let started!: () => void;
+ const ready = new Promise<void>((r) => (started = r));
+ const slot = new PluginDownloadSlot({
+ root: (id) => path.join(root, id),
+ scope: () => 'a',
+ getGhost: () => ghost,
+ send: () => {},
+ download: async (o) =>
+ new Promise((_, reject) => {
+ started();
+ o.signal!.addEventListener('abort', () => reject(Error('aborted')));
+ }),
+ });
+ try {
+ const work = slot.handle('p', {
+ kind: 'start',
+ id: 'x',
+ url: 'https://github.com/file',
+ sha256: 'a'.repeat(64),
+ bytes: 2,
+ });
+ await ready;
+ await slot.handle('p', { kind: 'cancel', id: 'x' });
+ expect(await work).toMatchObject({ ok: false, message: '下载已取消' });
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+});
+
+it('hands opaque receipts only to the owning Node call and preserves legacy params', async () => {
+ const root = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), 'plugin-receipt-test-')));
+ let scope = 'a';
+ const ghost = {
+ enabled: true,
+ approval: { revision: 'a' },
+ manifest: { node: {}, network: { hosts: ['github.com'] } },
+ } as unknown as InstalledGhost;
+ const slot = new PluginDownloadSlot({
+ root: (id) => path.join(root, id),
+ scope: () => scope,
+ getGhost: () => ghost,
+ send: () => {},
+ download: async (o) => {
+ await fs.writeFile(o.targetPath, 'ok');
+ return {
+ path: o.targetPath,
+ size: 2,
+ sha256: o.sha256,
+ fromCache: false,
+ durationMs: 1,
+ resumedFromBytes: 0,
+ };
+ },
+ });
+ const req = {
+ kind: 'start',
+ id: 'x',
+ url: 'https://github.com/file',
+ sha256: 'a'.repeat(64),
+ bytes: 2,
+ };
+ try {
+ const result = (await slot.handle('p', req)) as { ok: boolean; token: string };
+ expect(result.ok).toBe(true);
+ expect(result).not.toHaveProperty('path');
+ let called = 0;
+ const run = async (payload: any) => {
+ called++;
+ expect(await fs.readFile(payload.params.downloads.archive, 'utf8')).toBe('ok');
+ return { ok: true };
+ };
+ const payload = {
+ type: 'node-request',
+ method: 'unpack',
+ downloadTokens: { archive: result.token },
+ params: {},
+ };
+ expect(await slot.withNodeDownloads('other', payload, run)).toMatchObject({ ok: false });
+ expect(await slot.withNodeDownloads('p', payload, run)).toEqual({ ok: true });
+ expect(called).toBe(1);
+ expect(
+ await slot.withNodeDownloads('p', { ...payload, params: { downloads: {} } }, run),
+ ).toMatchObject({ ok: false });
+ scope = 'b';
+ expect(await slot.withNodeDownloads('p', payload, run)).toMatchObject({ ok: false });
+ scope = 'a';
+ ghost.approval = { ...ghost.approval, revision: 'b' } as InstalledGhost['approval'];
+ expect(await slot.withNodeDownloads('p', payload, run)).toMatchObject({ ok: false });
+ const legacy = { type: 'node-request', params: ['legacy'] };
+ expect(await slot.withNodeDownloads('p', legacy, async (p) => p)).toBe(legacy);
+ await slot.removePlugin('p');
+ await expect(fs.stat(path.join(root, 'p'))).rejects.toMatchObject({ code: 'ENOENT' });
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
});
diff --git a/apps/desktop/src/main/cindy-brain/downloadCache.ts b/apps/desktop/src/main/cindy-brain/downloadCache.ts
new file mode 100644
index 0000000000..54f5f89a12
--- /dev/null
+++ b/apps/desktop/src/main/cindy-brain/downloadCache.ts
@@ -0,0 +1,161 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+interface Receipt {
+ dir: string;
+ scope: string;
+ plugin: string;
+ approval: string;
+ size: number;
+ ino: number;
+ mtimeMs: number;
+}
+
+/** One owner-wide disk budget. Mutations serialize; network and Node execution do not. */
+export class PluginDownloadCache {
+ private tail: Promise<unknown> = Promise.resolve();
+ private reserved = new Map<string, number>();
+ private pins = new Map<string, number>();
+ private receipts = new Map<string, Receipt>();
+ constructor(private limit = 4 * 1024 ** 3) {}
+ revokeAll() {
+ this.receipts.clear();
+ }
+
+ private async locked<T>(work: () => Promise<T>): Promise<T> {
+ const result = this.tail.then(work);
+ this.tail = result.catch(() => {});
+ return result;
+ }
+ private forget(dir: string) {
+ for (const [token, receipt] of this.receipts)
+ if (receipt.dir === dir) this.receipts.delete(token);
+ }
+ async reserve(root: string, dir: string, bytes: number): Promise<void> {
+ return this.locked(async () => {
+ await fs.mkdir(root, { recursive: true });
+ if ((await fs.realpath(root)) !== path.resolve(root)) throw Error('Unsafe cache root');
+ const entries: Array<{ dir: string; bytes: number; time: number }> = [];
+ for (const plugin of await fs.readdir(root, { withFileTypes: true })) {
+ if (!plugin.isDirectory()) throw Error('Unsafe download cache');
+ const pluginRoot = path.join(root, plugin.name);
+ for (const artifact of await fs.readdir(pluginRoot, { withFileTypes: true })) {
+ if (!artifact.isDirectory() || !/^[a-f0-9]{64}$/.test(artifact.name))
+ throw Error('Unsafe download cache');
+ const entryDir = path.join(pluginRoot, artifact.name);
+ let size = 0,
+ time = 0;
+ for (const name of await fs.readdir(entryDir)) {
+ const stat = await fs.lstat(path.join(entryDir, name));
+ if (!stat.isFile()) throw Error('Unsafe download cache');
+ size += stat.size;
+ time = Math.max(time, stat.mtimeMs);
+ }
+ // Charge directory/receipt overhead too: empty failed attempts are not free forever.
+ entries.push({
+ dir: entryDir,
+ bytes: Math.max(size + 65536, this.reserved.get(entryDir) ?? 0),
+ time,
+ });
+ }
+ }
+ // Reserve before dispatch: concurrent queued downloads cannot oversubscribe disk.
+ const planned = Math.max(bytes + 65536, entries.find((e) => e.dir === dir)?.bytes ?? 0);
+ let total = entries.filter((e) => e.dir !== dir).reduce((sum, e) => sum + e.bytes, planned);
+ for (const entry of entries.sort((a, b) => a.time - b.time)) {
+ if (total <= this.limit) break;
+ if (entry.dir === dir || this.reserved.has(entry.dir) || this.pins.has(entry.dir)) continue;
+ await fs.rm(entry.dir, { recursive: true, force: true });
+ this.forget(entry.dir);
+ total -= entry.bytes;
+ }
+ if (total > this.limit) throw Error('Download cache is full');
+ await fs.mkdir(dir, { recursive: true });
+ if ((await fs.realpath(dir)) !== path.resolve(dir)) throw Error('Unsafe cache directory');
+ this.reserved.set(dir, planned);
+ });
+ }
+ release(dir: string) {
+ this.reserved.delete(dir);
+ }
+ async issue(dir: string, scope: string, plugin: string, approval: string): Promise<string> {
+ return this.locked(async () => {
+ const file = path.join(dir, 'artifact');
+ const now = new Date();
+ await fs.utimes(file, now, now);
+ const stat = await fs.lstat(file);
+ if (!stat.isFile() || (await fs.realpath(file)) !== file) throw Error('Unsafe artifact');
+ // One reusable receipt per resident artifact, not one per cache hit.
+ for (const [token, receipt] of this.receipts) {
+ if (
+ receipt.dir === dir &&
+ receipt.scope === scope &&
+ receipt.plugin === plugin &&
+ receipt.approval === approval
+ ) {
+ Object.assign(receipt, { size: stat.size, ino: stat.ino, mtimeMs: stat.mtimeMs });
+ return token;
+ }
+ }
+ this.forget(dir);
+ const token = randomUUID();
+ this.receipts.set(token, {
+ dir,
+ scope,
+ plugin,
+ approval,
+ size: stat.size,
+ ino: stat.ino,
+ mtimeMs: stat.mtimeMs,
+ });
+ return token;
+ });
+ }
+ async acquire(token: string, scope: string, plugin: string, approval: string) {
+ return this.locked(async () => {
+ const receipt = this.receipts.get(token);
+ if (
+ !receipt ||
+ receipt.scope !== scope ||
+ receipt.plugin !== plugin ||
+ receipt.approval !== approval
+ )
+ throw Error('Invalid download receipt');
+ const file = path.join(receipt.dir, 'artifact');
+ const stat = await fs.lstat(file);
+ if (
+ !stat.isFile() ||
+ stat.size !== receipt.size ||
+ stat.ino !== receipt.ino ||
+ stat.mtimeMs !== receipt.mtimeMs ||
+ (await fs.realpath(file)) !== file
+ )
+ throw Error('Artifact changed');
+ const now = new Date();
+ await fs.utimes(file, now, now);
+ receipt.mtimeMs = (await fs.stat(file)).mtimeMs;
+ if (this.receipts.get(token) !== receipt) throw Error('Download receipt revoked');
+ this.pins.set(receipt.dir, (this.pins.get(receipt.dir) ?? 0) + 1);
+ let released = false;
+ return {
+ path: file,
+ release: () => {
+ if (released) return;
+ released = true;
+ const count = (this.pins.get(receipt.dir) ?? 1) - 1;
+ if (count) this.pins.set(receipt.dir, count);
+ else this.pins.delete(receipt.dir);
+ },
+ };
+ });
+ }
+ async removePlugin(root: string): Promise<void> {
+ return this.locked(async () => {
+ for (const [token, receipt] of this.receipts)
+ if (path.dirname(receipt.dir) === root) this.receipts.delete(token);
+ // Caller has stopped the Node runtime and settled downloads before entering.
+ await fs.rm(root, { recursive: true, force: true });
+ });
+ }
+}
diff --git a/apps/desktop/src/main/cindy-brain/downloadSlot.ts b/apps/desktop/src/main/cindy-brain/downloadSlot.ts
index bad5a4f92e..f119857cef 100644
--- a/apps/desktop/src/main/cindy-brain/downloadSlot.ts
+++ b/apps/desktop/src/main/cindy-brain/downloadSlot.ts
@@ -3,6 +3,7 @@ import fs from 'node:fs/promises';
import path from 'node:path';
import { ghostNetworkHostMatches, type InstalledGhost } from '../../shared/ghost.js';
import type { DownloadOptions, DownloadResult } from '../downloader/index.js';
+import { PluginDownloadCache } from './downloadCache.js';
/** Verified public artifacts, in the requesting plugin's host-managed cache only. */
export interface PluginDownloadDeps {
@@ -13,59 +14,234 @@ export interface PluginDownloadDeps {
download(options: DownloadOptions): Promise<DownloadResult>;
}
export class PluginDownloadSlot {
- private active = new Map<string, { controller: AbortController; promise: Promise<unknown>; fingerprint: string }>();
+ private cache = new PluginDownloadCache();
+ private active = new Map<
+ string,
+ { controller: AbortController; promise: Promise<unknown>; fingerprint: string }
+ >();
constructor(private deps: PluginDownloadDeps) {}
- abortAll() { for (const item of this.active.values()) item.controller.abort(); }
- async handle(id: string, value: unknown, callerActive: () => boolean = () => true): Promise<unknown> {
+ abortAll() {
+ this.cache.revokeAll();
+ for (const item of this.active.values()) item.controller.abort();
+ }
+ async removePlugin(id: string, root = this.deps.root(id), scope = this.deps.scope()) {
+ const work = [...this.active].filter(([key]) => {
+ const parts = JSON.parse(key);
+ return parts[0] === scope && parts[1] === id;
+ });
+ for (const [, item] of work) item.controller.abort();
+ await Promise.allSettled(work.map(([, item]) => item.promise));
+ await this.cache.removePlugin(root);
+ }
+ async withNodeDownloads(
+ id: string,
+ payload: Record<string, unknown>,
+ run: (payload: unknown) => Promise<unknown>,
+ ) {
+ if (payload.downloadTokens === undefined) return run(payload);
+ const releases: Array<() => void> = [];
+ try {
+ const tokens = payload.downloadTokens;
+ if (
+ !tokens ||
+ typeof tokens !== 'object' ||
+ Array.isArray(tokens) ||
+ Object.keys(tokens).length > 32
+ )
+ throw Error('Invalid download receipts');
+ if (
+ payload.params !== undefined &&
+ (!payload.params ||
+ typeof payload.params !== 'object' ||
+ Array.isArray(payload.params) ||
+ Object.hasOwn(payload.params, 'downloads'))
+ )
+ throw Error('Invalid download params');
+ const scope = this.deps.scope(),
+ ghost = this.deps.getGhost(id);
+ if (!ghost?.enabled || !ghost.manifest.node) throw Error('Plugin unavailable');
+ const approval = JSON.stringify(ghost.approval);
+ const downloads: Record<string, string> = {};
+ for (const [name, token] of Object.entries(tokens)) {
+ if (
+ !/^[a-zA-Z][a-zA-Z0-9_]{0,127}$/.test(name) ||
+ ['constructor', 'prototype', '__proto__'].includes(name) ||
+ typeof token !== 'string'
+ )
+ throw Error('Invalid download receipt');
+ const lease = await this.cache.acquire(token, scope, id, approval);
+ releases.push(lease.release);
+ downloads[name] = lease.path;
+ }
+ if (
+ this.deps.scope() !== scope ||
+ !this.deps.getGhost(id)?.enabled ||
+ JSON.stringify(this.deps.getGhost(id)?.approval) !== approval
+ )
+ throw Error('Plugin changed');
+ const { downloadTokens: _tokens, ...request } = payload;
+ return await run({
+ ...request,
+ params: { ...((payload.params as object) ?? {}), downloads },
+ });
+ } catch {
+ return { ok: false, message: '下载凭据已失效,请重新获取文件后重试' };
+ } finally {
+ for (const release of releases) release();
+ }
+ }
+ async handle(
+ id: string,
+ value: unknown,
+ callerActive: () => boolean = () => true,
+ ): Promise<unknown> {
try {
if (!value || typeof value !== 'object') throw Error('Invalid download request');
const p = value as Record<string, unknown>;
- if (typeof p.id !== 'string' || !/^[\w-]{1,100}$/.test(p.id)) throw Error('Invalid download id');
- const scope = this.deps.scope(), key = JSON.stringify([scope,id,p.id]);
- if (p.kind === 'cancel') { this.active.get(key)?.controller.abort(); return { ok: true }; }
- if (p.kind !== 'start' || Object.keys(p).some(k=>!['type','kind','id','url','sha256','bytes'].includes(k))) throw Error('Invalid download request');
- if (typeof p.url !== 'string' || p.url.length > 8192 || typeof p.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(p.sha256) || !Number.isSafeInteger(p.bytes) || (p.bytes as number)<1 || (p.bytes as number)>2**31) throw Error('URL, SHA-256 and exact size (up to 2 GiB) are required');
+ if (typeof p.id !== 'string' || !/^[\w-]{1,100}$/.test(p.id))
+ throw Error('Invalid download id');
+ const scope = this.deps.scope(),
+ key = JSON.stringify([scope, id, p.id]);
+ if (p.kind === 'cancel') {
+ this.active.get(key)?.controller.abort();
+ return { ok: true };
+ }
+ if (
+ p.kind !== 'start' ||
+ Object.keys(p).some((k) => !['type', 'kind', 'id', 'url', 'sha256', 'bytes'].includes(k))
+ )
+ throw Error('Invalid download request');
+ if (
+ typeof p.url !== 'string' ||
+ p.url.length > 8192 ||
+ typeof p.sha256 !== 'string' ||
+ !/^[a-f0-9]{64}$/.test(p.sha256) ||
+ !Number.isSafeInteger(p.bytes) ||
+ (p.bytes as number) < 1 ||
+ (p.bytes as number) > 2 ** 31
+ )
+ throw Error('URL, SHA-256 and exact size (up to 2 GiB) are required');
const ghost = this.deps.getGhost(id);
- if (!ghost?.enabled || !ghost.manifest.node || !ghost.manifest.network?.hosts.length) throw Error('Download requires node and network.hosts declarations');
+ if (!ghost?.enabled || !ghost.manifest.node || !ghost.manifest.network?.hosts.length)
+ throw Error('Download requires node and network.hosts declarations');
const approval = JSON.stringify(ghost.approval);
- const current = () => callerActive() && this.deps.scope() === scope && this.deps.getGhost(id)?.enabled === true && JSON.stringify(this.deps.getGhost(id)?.approval) === approval;
+ const current = () =>
+ callerActive() &&
+ this.deps.scope() === scope &&
+ this.deps.getGhost(id)?.enabled === true &&
+ JSON.stringify(this.deps.getGhost(id)?.approval) === approval;
const validateUrl = (raw: string) => {
if (!current()) throw Error('Download owner or plugin changed');
const u = new URL(raw);
- if (u.protocol !== 'https:' || u.port || u.username || u.password || !ghost.manifest.network!.hosts.some(h=>ghostNetworkHostMatches(h,u.hostname))) throw Error('Download URL is outside declared HTTPS hosts');
+ if (
+ raw.length > 8192 ||
+ /[\u0000-\u0020\u007f]/.test(raw) ||
+ u.protocol !== 'https:' ||
+ u.port ||
+ u.username ||
+ u.password ||
+ !ghost.manifest.network!.hosts.some((h) => ghostNetworkHostMatches(h, u.hostname))
+ )
+ throw Error('Download URL is outside declared HTTPS hosts');
};
validateUrl(p.url);
- const fingerprint = JSON.stringify([p.url,p.sha256,p.bytes]);
+ const fingerprint = JSON.stringify([p.url, p.sha256, p.bytes]);
const existing = this.active.get(key);
- if (existing) { if(existing.fingerprint!==fingerprint) throw Error('Download id already in use'); return existing.promise; }
+ if (existing) {
+ if (existing.fingerprint !== fingerprint) throw Error('Download id already in use');
+ return existing.promise;
+ }
if (this.active.size >= 8) throw Error('Too many active downloads');
const controller = new AbortController();
- const emit = (data: Record<string, unknown>) => { if(current()) this.deps.send(id,{type:'event',name:'download-progress',data:{id:p.id,...data}}); };
- const promise = (async()=>{
+ const emit = (data: Record<string, unknown>) => {
+ if (current())
+ this.deps.send(id, {
+ type: 'event',
+ name: 'download-progress',
+ data: { id: p.id, ...data },
+ });
+ };
+ const promise = (async () => {
// Distinct operations cannot share the first caller's signal or progress callback.
- const root = this.deps.root(id), dir = path.join(root,createHash('sha256').update(JSON.stringify([scope,p.id,fingerprint])).digest('hex'));
- await fs.mkdir(dir,{recursive:true});
- if(await fs.realpath(dir)!==path.resolve(dir)) throw Error('Download cache must not contain symbolic links');
- const targetPath = path.join(dir,'artifact');
- for(const file of [targetPath,targetPath+'.part',targetPath+'.meta.json']) {
- try { if(!(await fs.lstat(file)).isFile()) throw Error('Unsafe download cache entry'); } catch(e) { if((e as NodeJS.ErrnoException).code!=='ENOENT') throw e; }
- }
- if(!current() || controller.signal.aborted) throw Error('Download cancelled');
- emit({phase:'queued',loaded:0,total:p.bytes,speedBps:0});
- const watch = setInterval(()=>{if(!current())controller.abort();},250);
+ const root = this.deps.root(id),
+ dir = path.join(
+ root,
+ createHash('sha256')
+ .update(JSON.stringify([scope, p.id, fingerprint]))
+ .digest('hex'),
+ );
+ await this.cache.reserve(path.dirname(root), dir, p.bytes as number);
try {
- const result=await this.deps.download({url:p.url as string,targetPath,sha256:p.sha256 as string,expectedSize:p.bytes as number,maxBytes:p.bytes as number,validateUrl,signal:controller.signal,
- logger:{debug(){},info(){},warn(){},error(){}},
- onProgress:e=>emit({phase:'downloading',...e}),onVerifying:()=>emit({phase:'verifying',loaded:p.bytes,total:p.bytes,speedBps:0}),
- onRetry:e=>emit({phase:'retrying',attempt:e.attempt,delayMs:e.delayMs}),
- });
- if(!current() || controller.signal.aborted) throw Error('Download cancelled');
- emit({phase:'completed',loaded:result.size,total:result.size,speedBps:0,fromCache:result.fromCache});
- return {ok:true,path:result.path,bytes:result.size,sha256:result.sha256,fromCache:result.fromCache};
- } finally { clearInterval(watch); }
- })().catch(()=>{emit({phase:controller.signal.aborted?'cancelled':'failed'});return {ok:false,message:controller.signal.aborted?'下载已取消':'下载失败,请重试(网络、权限或文件校验未通过)'};}).finally(()=>this.active.delete(key));
- this.active.set(key,{controller,promise,fingerprint});
+ if ((await fs.realpath(dir)) !== path.resolve(dir))
+ throw Error('Download cache must not contain symbolic links');
+ const targetPath = path.join(dir, 'artifact');
+ for (const file of [targetPath, targetPath + '.part', targetPath + '.meta.json']) {
+ try {
+ if (!(await fs.lstat(file)).isFile()) throw Error('Unsafe download cache entry');
+ } catch (e) {
+ if ((e as NodeJS.ErrnoException).code !== 'ENOENT') throw e;
+ }
+ }
+ if (!current() || controller.signal.aborted) throw Error('Download cancelled');
+ emit({ phase: 'queued', loaded: 0, total: p.bytes, speedBps: 0 });
+ const watch = setInterval(() => {
+ if (!current()) controller.abort();
+ }, 250);
+ try {
+ const result = await this.deps.download({
+ streaming: true,
+ url: p.url as string,
+ targetPath,
+ sha256: p.sha256 as string,
+ expectedSize: p.bytes as number,
+ maxBytes: p.bytes as number,
+ validateUrl,
+ signal: controller.signal,
+ logger: { debug() {}, info() {}, warn() {}, error() {} },
+ onProgress: (e) => emit({ phase: 'downloading', ...e }),
+ onVerifying: () =>
+ emit({ phase: 'verifying', loaded: p.bytes, total: p.bytes, speedBps: 0 }),
+ onRetry: (e) => emit({ phase: 'retrying', attempt: e.attempt, delayMs: e.delayMs }),
+ });
+ if (!current() || controller.signal.aborted) throw Error('Download cancelled');
+ if (result.size !== p.bytes) throw Error('Downloaded size mismatch');
+ const token = await this.cache.issue(dir, scope, id, approval);
+ if (!current() || controller.signal.aborted) throw Error('Plugin changed');
+ emit({
+ phase: 'completed',
+ loaded: result.size,
+ total: result.size,
+ speedBps: 0,
+ fromCache: result.fromCache,
+ });
+ return {
+ ok: true,
+ token,
+ bytes: result.size,
+ sha256: result.sha256,
+ fromCache: result.fromCache,
+ };
+ } finally {
+ clearInterval(watch);
+ }
+ } finally {
+ this.cache.release(dir);
+ }
+ })()
+ .catch(() => {
+ emit({ phase: controller.signal.aborted ? 'cancelled' : 'failed' });
+ return {
+ ok: false,
+ message: controller.signal.aborted
+ ? '下载已取消'
+ : '下载失败,请重试(网络、权限或文件校验未通过)',
+ };
+ })
+ .finally(() => this.active.delete(key));
+ this.active.set(key, { controller, promise, fingerprint });
return promise;
- } catch(e) { return {ok:false,message:(e as Error).message}; }
+ } catch (e) {
+ return { ok: false, message: (e as Error).message };
+ }
}
}
diff --git a/apps/desktop/src/main/cindy-brain/forge.ts b/apps/desktop/src/main/cindy-brain/forge.ts
index 10cddcd277..a37c93ce40 100644
--- a/apps/desktop/src/main/cindy-brain/forge.ts
+++ b/apps/desktop/src/main/cindy-brain/forge.ts
@@ -3951,6 +3951,26 @@ Node 请求及其子进程一并结束,晚到的授权或子进程启动会被
或不启用开关都保持既有独立 RPC 生命周期,不自动弹授权卡、不回收后台进程;
设置页等无 tool-call 的入口不能伪造或复用调用编号。
+#### 下载公开大文件与进度
+
+声明 node 和 network.hosts 后可用 cindy.downloads.start({id,url,sha256,bytes});
+只接受声明的 HTTPS 主机(每次重定向复核),不发送 Cookie、凭证或自定义请求头。
+SHA-256 和精确字节数必填,单文件最多 2 GiB。返回 {ok:true,token,bytes,sha256,fromCache},
+没有宿主路径。取消用 cindy.downloads.cancel({id})。
+订阅 onHostMessage 的 download-progress 事件:data 含 id、phase、loaded、total、speedBps;
+phase 为 queued/downloading/verifying/retrying/completed/failed/cancelled,retrying 另含 attempt、delayMs。
+无 loaded/total 时显示不确定进度,下载成功不等于解包成功。
+
+将 token 放入 cindy.node.request 的 downloadTokens,例如 {archive: token};params 必须是对象且
+不能自带 downloads。Host 校验同账号、同插件、批准身份与文件身份后,仅向 Node 注入
+params.downloads.archive。Node 在本次 RPC 结束前读取或复制文件,不得把宿主路径回传面板或写进日志。
+旧请求不带 downloadTokens 时保持原有 params 语义。旧宿主无 downloads 时提示升级。
+
+下载队列与宿主更新隔离,传输逐块写盘并支持校验、重试与续传。每账号所有插件的缓存
+合计最多 4 GiB(含在途预留及每项 64 KiB 管理空间);不淘汰正在下载或被 Node RPC 借用的文件,满额且无可回收项时失败。
+缓存可被回收,重启后 token 失效,重新 start 可复用经校验的文件。卸载插件回收其下载缓存;
+停用、账号切换或批准身份改变会拒绝旧凭据,不增加用户授权步骤。
+
#### Node Worker 的持久化凭证绑定
本地 IMAP/SMTP 等协议确实需要 Worker 使用凭证明文时,在
diff --git a/apps/desktop/src/main/cindy-brain/index.ts b/apps/desktop/src/main/cindy-brain/index.ts
index 5d0867c6fb..da4225a2ab 100644
--- a/apps/desktop/src/main/cindy-brain/index.ts
+++ b/apps/desktop/src/main/cindy-brain/index.ts
@@ -1,5 +1,5 @@
import { PluginDownloadSlot } from './downloadSlot.js';
-import { download as downloadPluginArtifact } from '../downloader/index.js';
+import { createDownloader } from '../downloader/index.js';
import { registerGhostCardRemoteProvider, persistGhostCardWithRemoteChange } from './cardRemoteResource.js';
import { openDeviceAuthorizationCard, openPluginAuthorizationCard } from '../plugin-oauth/deviceCard.js';
import { t as authorizationText } from '../i18n.js';
@@ -2677,7 +2677,7 @@ export function getGhostIOSSimulatorSlot(): GhostIOSSimulatorSlot {
let cindySlotSingleton: GhostCindySlot | null = null;
const pluginDownloads = new PluginDownloadSlot({
getGhost: findAvailableGhost, root: id => ownerScopedUserDataPath('plugin-downloads', id),
- scope: activeOwnerScopeKey, send: sendToGhostLogic, download: downloadPluginArtifact,
+ scope: activeOwnerScopeKey, send: sendToGhostLogic, download: createDownloader(),
});
let networkSlotSingleton: GhostNetworkSlot | null = null;
let notifySlotSingleton: GhostNotifySlot | null = null;
@@ -6482,8 +6482,11 @@ async function uninstallGhostAndCleanupLocked(
getGhostAgentSlot().clearGhost(id);
getGhostErrandSlot().clearGhost(id);
getGhostSubscriptionGateway().dropGhost(id);
+ const downloadRoot = ownerScopedUserDataPath('plugin-downloads', id);
+ const downloadScope = activeOwnerScopeKey();
const result = await manager.uninstall(id, { notify: false });
if ('rejection' in result) throwUninstallError(result.rejection);
+ await pluginDownloads.removePlugin(id, downloadRoot, downloadScope).catch(err => log.warn('plugin download cache cleanup failed', { id, error: String(err) }));
removeGhostSecrets(id);
removeGhostKvBestEffort(
createGhostKvStore({
@@ -7171,7 +7174,7 @@ export function registerGhostIpc(): void {
// node-request 只在 main.js → contextBridge → 主机方向开放。子进程反向
// JSON-RPC 请求恒被 broker 拒绝,因此 Node 不能绕过 main.js 控制 Cindy。
if (type === 'node-request') {
- return getGhostNodeRuntimeBroker().handleRequest(id, payload);
+ return pluginDownloads.withNodeDownloads(id, payload as Record<string, unknown>, request => getGhostNodeRuntimeBroker().handleRequest(id, request));
}
// pick-request = 系统级选文件夹(pick 槽):用户亲手选中即授权,取消即拒;
// 限速/单发/结果分档在 pickSlot。
diff --git a/apps/desktop/src/main/downloader/__tests__/scheduler.test.ts b/apps/desktop/src/main/downloader/__tests__/scheduler.test.ts
index 0dcb78ee4b..578a68f6c4 100644
--- a/apps/desktop/src/main/downloader/__tests__/scheduler.test.ts
+++ b/apps/desktop/src/main/downloader/__tests__/scheduler.test.ts
@@ -15,6 +15,7 @@ vi.mock('../../logger', () => ({
}));
import { Scheduler } from '../scheduler';
+import { createDownloader, download } from '../index';
const HASH_A = 'a'.repeat(64);
const HASH_B = 'b'.repeat(64);
@@ -30,9 +31,32 @@ describe('downloader scheduler queued cancellation', () => {
mocks.withRetry.mockImplementation(async (run: () => Promise<unknown>) => run());
});
+ it('bulk consumer queues cannot block the host download queue', async () => {
+ let release!: () => void;
+ const gate = new Promise<void>((r) => {
+ release = r;
+ });
+ mocks.executeOnce.mockImplementation(async (ctx: { opts: { url: string; sha256: string } }) => {
+ if (ctx.opts.url.includes('bulk')) await gate;
+ return { size: 1, sha256: ctx.opts.sha256 };
+ });
+ const bulk = createDownloader();
+ const pending = bulk(options('https://bulk.invalid', '/tmp/cindy-bulk', HASH_A));
+ try {
+ await expect(
+ download(options('https://host.invalid', '/tmp/cindy-host', HASH_B)),
+ ).resolves.toMatchObject({ sha256: HASH_B });
+ } finally {
+ release();
+ }
+ await pending;
+ });
+
it('rejects an aborted queued task immediately instead of waiting behind an active download', async () => {
let releaseFirst!: () => void;
- const firstGate = new Promise<void>((resolve) => { releaseFirst = resolve; });
+ const firstGate = new Promise<void>((resolve) => {
+ releaseFirst = resolve;
+ });
let executeCount = 0;
mocks.executeOnce.mockImplementation(async (ctx: { opts: { sha256: string } }) => {
executeCount += 1;
diff --git a/apps/desktop/src/main/downloader/__tests__/streaming.test.ts b/apps/desktop/src/main/downloader/__tests__/streaming.test.ts
new file mode 100644
index 0000000000..f7742b9846
--- /dev/null
+++ b/apps/desktop/src/main/downloader/__tests__/streaming.test.ts
@@ -0,0 +1,173 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { afterEach, expect, it, vi } from 'vitest';
+const mocks = vi.hoisted(() => ({ fetch: vi.fn() }));
+vi.mock('electron', () => ({ net: { fetch: mocks.fetch } }));
+import { executeStreaming } from '../streaming';
+import { writeMeta } from '../resume';
+
+afterEach(() => vi.restoreAllMocks());
+
+it('cancellation while waiting for data cannot publish a completed artifact', async () =>
+ fixture(async (_, opts) => {
+ const abort = new AbortController();
+ mocks.fetch.mockReset().mockImplementation(
+ async (_url, init) =>
+ new Response(
+ new ReadableStream({
+ start(c) {
+ init.signal.addEventListener('abort', () => c.error(new Error('aborted')), {
+ once: true,
+ });
+ },
+ }),
+ ),
+ );
+ const work = execute({ ...opts, signal: abort.signal });
+ const rejected = expect(work).rejects.toMatchObject({ code: 'ABORTED' });
+ await vi.waitFor(() => expect(mocks.fetch).toHaveBeenCalledTimes(1));
+ abort.abort();
+ await rejected;
+ await expect(fs.stat(opts.targetPath)).rejects.toMatchObject({ code: 'ENOENT' });
+ }));
+async function fixture(run: (root: string, opts: any) => Promise<void>) {
+ const root = await fs.mkdtemp(path.join(os.tmpdir(), 'download-stream-test-'));
+ const body = Buffer.from('abcdef');
+ try {
+ await run(root, {
+ url: 'https://example.invalid/file',
+ targetPath: path.join(root, 'artifact'),
+ expectedSize: 6,
+ maxBytes: 6,
+ sha256: createHash('sha256').update(body).digest('hex'),
+ });
+ } finally {
+ await fs.rm(root, { recursive: true, force: true });
+ }
+}
+const execute = (opts: any) => executeStreaming({ opts, logger: {}, resumedFromBytes: 0 });
+
+it('validates each redirect and never sends credentials', async () =>
+ fixture(async (_, opts) => {
+ mocks.fetch
+ .mockReset()
+ .mockResolvedValueOnce(
+ new Response(null, { status: 302, headers: { location: 'https://cdn.invalid/file' } }),
+ )
+ .mockResolvedValueOnce(new Response('abcdef'));
+ const urls: string[] = [];
+ await expect(
+ execute({ ...opts, validateUrl: (u: string) => urls.push(u) }),
+ ).resolves.toMatchObject({ size: 6 });
+ expect(urls).toEqual([opts.url, 'https://cdn.invalid/file']);
+ for (const [, request] of mocks.fetch.mock.calls)
+ expect(request).toMatchObject({ credentials: 'omit', redirect: 'manual' });
+ }));
+
+it('rejects a forbidden redirect before fetching it', async () =>
+ fixture(async (_, opts) => {
+ mocks.fetch
+ .mockReset()
+ .mockResolvedValue(
+ new Response(null, { status: 302, headers: { location: 'http://127.0.0.1/private' } }),
+ );
+ await expect(
+ execute({
+ ...opts,
+ validateUrl: (u: string) => {
+ if (u !== opts.url) throw Error('denied');
+ },
+ }),
+ ).rejects.toThrow();
+ expect(mocks.fetch).toHaveBeenCalledTimes(1);
+ }));
+
+it('cleans both sidecars on oversized and short bodies', async () =>
+ fixture(async (_, opts) => {
+ for (const body of ['abc', 'abcdefg']) {
+ mocks.fetch.mockReset().mockResolvedValue(new Response(body));
+ await expect(execute(opts)).rejects.toMatchObject({ code: 'CHECKSUM' });
+ await expect(fs.stat(opts.targetPath + '.part')).rejects.toMatchObject({ code: 'ENOENT' });
+ await expect(fs.stat(opts.targetPath + '.meta.json')).rejects.toMatchObject({
+ code: 'ENOENT',
+ });
+ }
+ }));
+
+it('resumes a verified prefix and hashes it exactly once', async () =>
+ fixture(async (_, opts) => {
+ await fs.writeFile(opts.targetPath + '.part', 'abc');
+ writeMeta(opts.targetPath, {
+ url: opts.url,
+ expectedSize: 6,
+ expectedSha256: opts.sha256,
+ downloadedBytes: 3,
+ etag: 'v1',
+ lastModified: null,
+ createdAt: '',
+ updatedAt: '',
+ });
+ mocks.fetch.mockReset().mockResolvedValue(
+ new Response('def', {
+ status: 206,
+ headers: { 'content-range': 'bytes 3-5/6', 'content-length': '3' },
+ }),
+ );
+ await expect(execute(opts)).resolves.toMatchObject({ size: 6 });
+ expect(mocks.fetch.mock.calls[0][1].headers).toMatchObject({
+ Range: 'bytes=3-',
+ 'If-Range': 'v1',
+ });
+ expect(await fs.readFile(opts.targetPath, 'utf8')).toBe('abcdef');
+ }));
+
+it('does not pull another chunk while disk write is pending', async () =>
+ fixture(async (_, opts) => {
+ let pulls = 0,
+ release!: () => void,
+ started!: () => void;
+ const waiting = new Promise<void>((r) => (started = r)),
+ gate = new Promise<void>((r) => (release = r));
+ const open = fs.open.bind(fs);
+ vi.spyOn(fs, 'open').mockImplementation(async (...args: Parameters<typeof fs.open>) => {
+ const handle = await open(...args),
+ write = handle.writeFile.bind(handle);
+ let first = true;
+ vi.spyOn(handle, 'writeFile').mockImplementation(
+ async (...data: Parameters<typeof handle.writeFile>) => {
+ if (first) {
+ first = false;
+ started();
+ await gate;
+ }
+ return write(...data);
+ },
+ );
+ return handle;
+ });
+ mocks.fetch.mockReset().mockResolvedValue(
+ new Response(
+ new ReadableStream(
+ {
+ pull(c) {
+ pulls++;
+ if (pulls === 1) c.enqueue(Buffer.from('abc'));
+ else if (pulls === 2) c.enqueue(Buffer.from('def'));
+ else c.close();
+ },
+ },
+ { highWaterMark: 0 },
+ ),
+ ),
+ );
+ const work = execute(opts);
+ await waiting;
+ try {
+ expect(pulls).toBe(1);
+ } finally {
+ release();
+ }
+ await expect(work).resolves.toMatchObject({ size: 6 });
+ }));
diff --git a/apps/desktop/src/main/downloader/index.ts b/apps/desktop/src/main/downloader/index.ts
index 8bc8772b98..c460ea2714 100644
--- a/apps/desktop/src/main/downloader/index.ts
+++ b/apps/desktop/src/main/downloader/index.ts
@@ -40,6 +40,15 @@ function validate(opts: DownloadOptions): void {
}
}
+/** A consumer-owned queue; bulk plugin downloads never queue ahead of app updates. */
+export function createDownloader() {
+ const scheduler = new Scheduler({ maxConcurrent: 1 });
+ return (opts: DownloadOptions): Promise<DownloadResult> => {
+ validate(opts);
+ return scheduler.enqueue({ ...opts, sha256: opts.sha256.toLowerCase() });
+ };
+}
+
/**
* Download a file with single-flight dedupe, resume, retry, and SHA256 verify.
*
diff --git a/apps/desktop/src/main/downloader/streaming.ts b/apps/desktop/src/main/downloader/streaming.ts
new file mode 100644
index 0000000000..553d76355e
--- /dev/null
+++ b/apps/desktop/src/main/downloader/streaming.ts
@@ -0,0 +1,194 @@
+import { net } from 'electron';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import type { TransportContext, TransportResult } from './transport';
+import { DownloadError } from './types';
+import { computeHash, createStreamingHasher } from './integrity';
+import {
+ decideResumeOffset,
+ deleteMeta,
+ deletePart,
+ partPath,
+ readMeta,
+ writeMeta,
+} from './resume';
+import { ProgressTracker } from './progress';
+
+/** Pull one chunk only after the previous disk write and hash have completed. */
+export async function executeStreaming(ctx: TransportContext): Promise<TransportResult> {
+ const { opts } = ctx;
+ const controller = new AbortController();
+ const abort = () => controller.abort();
+ opts.signal?.addEventListener('abort', abort, { once: true });
+ if (opts.signal?.aborted) abort();
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ let timedOut = false;
+ const arm = (ms: number) => {
+ clearTimeout(timer);
+ timer = setTimeout(() => {
+ timedOut = true;
+ controller.abort();
+ }, ms);
+ };
+ let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+ let file: fs.FileHandle | undefined;
+ try {
+ try {
+ const stat = await fs.stat(opts.targetPath);
+ if (
+ (opts.expectedSize === undefined || stat.size === opts.expectedSize) &&
+ (await computeHash(opts.targetPath)) === opts.sha256
+ ) {
+ return { size: stat.size, sha256: opts.sha256 };
+ }
+ } catch {
+ /* no verified cache */
+ }
+ await fs.rm(opts.targetPath, { force: true });
+ await fs.mkdir(path.dirname(opts.targetPath), { recursive: true });
+ const offset = decideResumeOffset(opts.targetPath, opts.url, opts.expectedSize, opts.sha256);
+ if (offset === null) {
+ deletePart(opts.targetPath);
+ deleteMeta(opts.targetPath);
+ }
+ const previous = readMeta(opts.targetPath);
+ let url = opts.url;
+ let response: Response;
+ for (let hop = 0; ; hop++) {
+ if (controller.signal.aborted) throw new DownloadError('ABORTED', 'Download cancelled');
+ opts.validateUrl?.(url);
+ arm(opts.timeout?.connectMs ?? 10_000);
+ response = await net.fetch(url, {
+ redirect: 'manual',
+ credentials: 'omit',
+ cache: 'no-store',
+ signal: controller.signal,
+ headers:
+ offset === null
+ ? {}
+ : {
+ Range: `bytes=${offset}-`,
+ ...(previous?.etag || previous?.lastModified
+ ? { 'If-Range': previous.etag || previous.lastModified! }
+ : {}),
+ },
+ });
+ if (![301, 302, 303, 307, 308].includes(response.status)) break;
+ await response.body?.cancel();
+ const location = response.headers.get('location');
+ if (!location || hop >= 9) throw new DownloadError('INVALID_ARG', 'Invalid redirect');
+ url = new URL(location, url).href;
+ }
+ if (!response.ok || !response.body) {
+ await response.body?.cancel();
+ if (response.status === 416) {
+ deletePart(opts.targetPath);
+ deleteMeta(opts.targetPath);
+ }
+ throw new DownloadError(
+ response.status >= 500 || response.status === 416 ? 'NETWORK' : 'HTTP_4XX',
+ 'Download HTTP failure',
+ );
+ }
+ reader = response.body.getReader();
+ const resumed = offset !== null && response.status === 206;
+ if (
+ response.status === 206 &&
+ (!resumed || !response.headers.get('content-range')?.startsWith(`bytes ${offset}-`))
+ ) {
+ deletePart(opts.targetPath);
+ deleteMeta(opts.targetPath);
+ throw new DownloadError('CHECKSUM', 'Invalid resume response');
+ }
+ const initial = resumed ? offset : 0;
+ const length = response.headers.get('content-length');
+ if (
+ length !== null &&
+ opts.expectedSize !== undefined &&
+ Number(length) + initial !== opts.expectedSize
+ ) {
+ deletePart(opts.targetPath);
+ deleteMeta(opts.targetPath);
+ throw new DownloadError('CHECKSUM', 'Content length mismatch');
+ }
+ const hasher = createStreamingHasher(resumed ? partPath(opts.targetPath) : null);
+ file = await fs.open(partPath(opts.targetPath), resumed ? 'a' : 'w', 0o600);
+ const tracker = new ProgressTracker({
+ initialLoaded: initial,
+ total: opts.expectedSize ?? null,
+ onProgress: opts.onProgress,
+ });
+ ctx.resumedFromBytes = initial;
+ if (resumed) opts.onResume?.({ fromBytes: initial, totalBytes: opts.expectedSize ?? null });
+ const meta = {
+ url: opts.url,
+ expectedSize: opts.expectedSize ?? null,
+ expectedSha256: opts.sha256,
+ downloadedBytes: initial,
+ etag:
+ (response.headers.get('etag')?.length ?? 0) <= 1024 ? response.headers.get('etag') : null,
+ lastModified:
+ (response.headers.get('last-modified')?.length ?? 0) <= 256
+ ? response.headers.get('last-modified')
+ : null,
+ createdAt: new Date().toISOString(),
+ updatedAt: new Date().toISOString(),
+ };
+ writeMeta(opts.targetPath, meta);
+ let lastMeta = Date.now();
+ for (;;) {
+ arm(opts.timeout?.idleMs ?? 30_000);
+ const { done, value } = await reader.read();
+ clearTimeout(timer);
+ if (controller.signal.aborted) throw new DownloadError('ABORTED', 'Download cancelled');
+ if (done) break;
+ if (opts.maxBytes !== undefined && tracker.getLoaded() + value.length > opts.maxBytes) {
+ throw new DownloadError('CHECKSUM', 'Download exceeds declared size');
+ }
+ await file.writeFile(value);
+ await hasher.update(Buffer.from(value.buffer, value.byteOffset, value.byteLength));
+ tracker.advance(value.length);
+ meta.downloadedBytes = tracker.getLoaded();
+ if (Date.now() - lastMeta > 2000) {
+ writeMeta(opts.targetPath, meta);
+ lastMeta = Date.now();
+ }
+ }
+ opts.onVerifying?.();
+ const sha256 = await hasher.digest();
+ if (
+ sha256 !== opts.sha256 ||
+ (opts.expectedSize !== undefined && tracker.getLoaded() !== opts.expectedSize)
+ ) {
+ throw new DownloadError('CHECKSUM', 'Downloaded artifact mismatch');
+ }
+ await file.close();
+ file = undefined;
+ if (controller.signal.aborted) throw new DownloadError('ABORTED', 'Download cancelled');
+ await fs.rename(partPath(opts.targetPath), opts.targetPath);
+ deleteMeta(opts.targetPath);
+ tracker.flush();
+ return { size: tracker.getLoaded(), sha256 };
+ } catch (error) {
+ await file?.close().catch(() => {});
+ file = undefined;
+ if (error instanceof DownloadError && error.code === 'CHECKSUM') {
+ deletePart(opts.targetPath);
+ deleteMeta(opts.targetPath);
+ }
+ if (opts.signal?.aborted) throw new DownloadError('ABORTED', 'Download cancelled');
+ if (timedOut) throw new DownloadError('NETWORK', 'Download timed out');
+ if (error instanceof DownloadError) throw error;
+ const cause = error instanceof Error ? error : new Error(String(error));
+ const diskFailure = ['ENOSPC', 'EACCES', 'EPERM', 'EIO', 'EROFS'].includes(
+ (cause as NodeJS.ErrnoException).code ?? '',
+ );
+ throw new DownloadError(diskFailure ? 'DISK' : 'NETWORK', 'Download failed', cause);
+ } finally {
+ clearTimeout(timer);
+ opts.signal?.removeEventListener('abort', abort);
+ await reader?.cancel().catch(() => {});
+ reader?.releaseLock();
+ await file?.close().catch(() => {});
+ }
+}
diff --git a/apps/desktop/src/main/downloader/transport.ts b/apps/desktop/src/main/downloader/transport.ts
index 00bef113b6..b712b87031 100644
--- a/apps/desktop/src/main/downloader/transport.ts
+++ b/apps/desktop/src/main/downloader/transport.ts
@@ -33,6 +33,7 @@ import {
} from './resume';
import { createStreamingHasher, computeHash } from './integrity';
import { ProgressTracker } from './progress';
+import { executeStreaming } from './streaming';
const DEFAULT_TIMEOUT: TimeoutConfig = { connectMs: 10_000, idleMs: 30_000 };
const META_WRITE_INTERVAL_MS = 2000;
@@ -81,6 +82,7 @@ function parseContentLength(
}
export async function executeOnce(ctx: TransportContext): Promise<TransportResult> {
+ if (ctx.opts.streaming) return executeStreaming(ctx);
const { opts, logger } = ctx;
const timeout: TimeoutConfig = { ...DEFAULT_TIMEOUT, ...(opts.timeout ?? {}) };
diff --git a/apps/desktop/src/main/downloader/types.ts b/apps/desktop/src/main/downloader/types.ts
index 23e49145e6..73f783dbe0 100644
--- a/apps/desktop/src/main/downloader/types.ts
+++ b/apps/desktop/src/main/downloader/types.ts
@@ -8,6 +8,8 @@
*/
export interface DownloadOptions {
+ /** Use the pull-based transport for large public artifacts. */
+ streaming?: boolean;
/** Absolute HTTP(S) URL to fetch. */
url: string;
/** Absolute target file path on disk. The downloader writes `${targetPath}.part`
diff --git a/apps/desktop/src/shared/ghost.ts b/apps/desktop/src/shared/ghost.ts
index afe3f378a5..d4a9f86e26 100644
--- a/apps/desktop/src/shared/ghost.ts
+++ b/apps/desktop/src/shared/ghost.ts
@@ -6362,9 +6362,36 @@ export type GhostPipeAgentErrandResult =
*/
export const GHOST_NODE_REQUEST_MAX_TOTAL_MS = 15 * 60_000;
+/** Public artifact download; results deliberately exclude host filesystem paths. */
+export type GhostPipeDownloadRequest =
+ | { type: 'download-request'; kind: 'start'; id: string; url: string; sha256: string; bytes: number }
+ | { type: 'download-request'; kind: 'cancel'; id: string };
+
+export type GhostPipeDownloadResult =
+ | { ok: true; token: string; bytes: number; sha256: string; fromCache: boolean }
+ | { ok: true }
+ | { ok: false; message: string };
+
+export interface GhostPipeDownloadProgress {
+ type: 'event';
+ name: 'download-progress';
+ data: {
+ id: string;
+ phase: 'queued' | 'downloading' | 'verifying' | 'retrying' | 'completed' | 'failed' | 'cancelled';
+ loaded?: number;
+ total?: number | null;
+ speedBps?: number;
+ attempt?: number;
+ delayMs?: number;
+ fromCache?: boolean;
+ };
+}
+
/** 上行:main.js 通过主机中继调用随包 Node 工作进程。 */
export interface GhostPipeNodeRequest {
type: 'node-request';
+ /** Host resolves same-plugin download receipts into params.downloads for this RPC only. */
+ downloadTokens?: Record<string, string>;
/** OAuth 注入的本插件账号 id;缺省使用对应 OAuth 槽的默认账号。 */
authAccount?: string;
/** Live tool-call identity; only cancelWithCall opts in to the new lifecycle. */
diff --git a/docs/dev-rules/plugin-download-api.md b/docs/dev-rules/plugin-download-api.md
index 2a82f7aefa..1b48e90a91 100644
--- a/docs/dev-rules/plugin-download-api.md
+++ b/docs/dev-rules/plugin-download-api.md
@@ -2,13 +2,19 @@
逻辑页使用 `cindy.downloads.start({id,url,sha256,bytes})`,取消使用
`cindy.downloads.cancel({id})`。返回结构为
-`{ok:true,path,bytes,sha256,fromCache}` 或 `{ok:false,message}`。
+`{ok:true,token,bytes,sha256,fromCache}` 或 `{ok:false,message}`。
插件必须声明 node 与 network.hosts;仅允许已声明 HTTPS 主机,重定向每跳重新检查。
本接口用于匿名公开文件,不携带 Cookie、账号凭证或自定义请求头;带授权请求继续使用 fetch 槽。
SHA-256 与精确字节数必填,单文件最大 2 GiB。目标由宿主管理,不接受本机目标路径。
-成功路径可传给本插件 Node 进程读取。缓存由账号、插件、请求身份隔离;id 相同且内容相同可复用缓存。
-文件按需保留以支持重试/续传,插件不应生成随机 id 来反复下载同一内容。
+面板不获得宿主路径。通过 `node.request({downloadTokens:{archive:token},params:{...}})`
+交接给同插件 Node,Host 校验账号、插件、批准身份和文件身份后注入 `params.downloads.archive`。
+携带凭据时 params 必须为对象且不得自带 downloads;旧请求不受影响。
+路径仅在本次 RPC 生命周期内有效,Node 须在返回前完成读取或复制,不得回传或记录路径。
+缓存由账号、插件、请求身份隔离;id 相同且内容相同可复用经校验的文件。
+每账号总预算 4 GiB(含在途预留及每项 64 KiB 管理空间),按最近使用回收;下载中和 Node 借用中的文件不淘汰。
+缓存满且没有可回收空间时失败。卸载回收该插件缓存;重启后凭据失效,可重新 start 取凭据。
+下载使用独立队列和逐块写盘,不占用宿主更新队列,支持重试/续传。
通过 onHostMessage 订阅:
`{type:'event',name:'download-progress',data:{id,phase,loaded,total,speedBps}}`。