@ai-workbench/network 0.4.1 → 0.4.3

package/helpers/darwin-x64/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@ai-workbench/net-helper-darwin-x64",
+  "version": "0.4.3",
+  "description": "远程主机网络助手（macOS x64，仅随network主包内嵌分发）",
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yzsnstotz/ai-workbench-network.git"
+  },
+  "private": true
+}

package/lib/activation.js

@@ -2,7 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { isAbsolute } from 'node:path';
 import { createNetwork } from "./network.js";
 import { fail, ok } from "./api.js";
-const fields = ['configFile', 'helperLogFile', 'startupObservationSeconds', 'shutdownObservationSeconds', 'controlResponseMaxBytes', 'downloadMaxRedirects'];
+import { settingsFields as fields, validHelperPolicy, mergedSettings } from "./settings.js";
 function normalized(s) {
     if (!s || typeof s !== 'object' || Object.keys(s).some(k => !fields.includes(k)))
         return;
@@ -13,7 +13,9 @@ function normalized(s) {
             return;
     if (!Number.isSafeInteger(s.controlResponseMaxBytes) || s.controlResponseMaxBytes <= 0 || !Number.isSafeInteger(s.downloadMaxRedirects) || s.downloadMaxRedirects < 0)
         return;
-    return Object.fromEntries(fields.map(k => [k, s[k]]));
+    if (!validHelperPolicy(s))
+        return;
+    return Object.fromEntries(fields.filter(k => s[k] !== undefined).map(k => [k, s[k]]));
 }
 // One stable Cordis service; callers never own, restart or borrow helper processes.
 export function createActivationService(initial, executable, emit = () => { }, factory = createNetwork) {
@@ -104,7 +106,7 @@ export function createActivationService(initial, executable, emit = () => { }, f
     }
     const api = {
         async start() { if (disposed)
-            return; if (Object.keys(initial).length)
+            return; if (initial.configFile || initial.helperLogFile)
             await api.activate(initial, new AbortController().signal);
         else
             emit(structuredClone(network)); },
@@ -114,9 +116,9 @@ export function createActivationService(initial, executable, emit = () => { }, f
         async activate(settings, signal) {
             if (disposed || signal.aborted)
                 return fail('ACTIVATION_CANCELLED', '连接激活等待已取消。', '查询当前激活结果；不要重复提交密钥');
-            const config = normalized(settings);
+            const config = normalized(mergedSettings(initial, settings));
             if (!config)
-                return fail('SETTINGS_REQUIRED', '我需要有效的连接配置。', 'L提供六项具名网络设置');
+                return fail('SETTINGS_REQUIRED', '我需要有效的连接配置。', '管理员核对网络插件具名设置及已导入的连接资料');
             const key = JSON.stringify(config);
             if (selected !== undefined && selected !== key)
                 return fail('ACTIVATION_CONFLICT', '已有连接激活，不能替换身份。', '管理员核对当前开通上下文');

package/lib/api.d.ts

@@ -90,6 +90,12 @@ export interface PluginSettings {
     shutdownObservationSeconds?: number;
     controlResponseMaxBytes?: number;
     downloadMaxRedirects?: number;
+    statusRefreshIntervalSeconds?: number;
+    dialTimeoutSeconds?: number;
+    headerTimeoutSeconds?: number;
+    enrollmentObservationSeconds?: number;
+    httpMaxHeaderBytes?: number;
+    httpMaxResponseHeaderBytes?: number;
 }
 export interface HelperConfig {
     apiVersion: 1;

package/lib/control.js

@@ -1,11 +1,13 @@
 import http from 'node:http';
 import { privateSocket } from "./private.js";
+import { ObservationExpired } from "./observation.js";
 export async function control(socket, method, path, signal, seconds, maxHeaderBytes) {
     await privateSocket(socket);
     signal.throwIfAborted();
     return new Promise((resolve, reject) => {
         const req = http.request({ socketPath: socket, method, path, agent: false, signal, maxHeaderSize: maxHeaderBytes }, res => { req.setTimeout(0); resolve(res); });
-        req.setTimeout(seconds * 1000, () => req.destroy(new Error('CONTROL_OBSERVATION_EXPIRED')));
+        const started = performance.now();
+        req.setTimeout(seconds * 1000, () => req.destroy(new ObservationExpired('CONTROL_OBSERVATION_EXPIRED', 'dialTimeoutSeconds', seconds, started, path === '/v1/status' ? '网络组件状态响应头' : '本机控制响应头', '检查自有组件私有日志、控制socket和当前网络状态；不要重交开通材料')));
         req.on('error', reject);
         req.end();
     });

package/lib/download.js

@@ -4,6 +4,7 @@ import tls from 'node:tls';
 import { isIP } from 'node:net';
 import { Readable } from 'node:stream';
 import { fail, ok } from "./api.js";
+import { ObservationExpired, observationNeed } from "./observation.js";
 function sourceURL(source) { const u = new URL(source); if (u.protocol !== 'https:' || u.username || u.password)
     throw new Error('DOWNLOAD_SOURCE_INVALID'); return u; }
 async function requestViaProxy(target, lease, signal, seconds, maxHeaderBytes) {
@@ -14,7 +15,8 @@ async function requestViaProxy(target, lease, signal, seconds, maxHeaderBytes) {
     const authority = (isIP(hostname) === 6 ? '[' + hostname + ']' : hostname) + ':' + (target.port || '443');
     const tunnel = await new Promise((resolve, reject) => {
         const req = http.request({ hostname: proxy.hostname, port: proxy.port, method: 'CONNECT', path: authority, agent: false, signal, maxHeaderSize: maxHeaderBytes, headers: { 'Proxy-Authorization': 'Basic ' + Buffer.from(lease.credentials.username + ':' + lease.credentials.password).toString('base64') } });
-        req.setTimeout(seconds * 1000, () => req.destroy(new Error('DOWNLOAD_CONNECT_EXPIRED')));
+        const started = performance.now();
+        req.setTimeout(seconds * 1000, () => req.destroy(new ObservationExpired('DOWNLOAD_CONNECT_EXPIRED', 'dialTimeoutSeconds', seconds, started, '主机代理CONNECT响应头', '检查网络组件私有日志、主机SSH状态及代理握手；不重试或改走本机出口')));
         req.on('connect', (response, socket, head) => { req.setTimeout(0); if (response.statusCode !== 200) {
             socket.destroy();
             reject(new Error('HOST_PROXY_REJECTED'));
@@ -31,7 +33,8 @@ async function requestViaProxy(target, lease, signal, seconds, maxHeaderBytes) {
     try {
         return await new Promise((resolve, reject) => {
             const req = https.request(target, { agent, signal, maxHeaderSize: maxHeaderBytes }, response => { req.setTimeout(0); response.once('close', () => agent.destroy()); resolve(response); });
-            req.setTimeout(seconds * 1000, () => req.destroy(new Error('DOWNLOAD_HEADERS_EXPIRED')));
+            const started = performance.now();
+            req.setTimeout(seconds * 1000, () => req.destroy(new ObservationExpired('DOWNLOAD_HEADERS_EXPIRED', 'dialTimeoutSeconds', seconds, started, '经主机下载的TLS握手及HTTP响应头', '检查主机出口、TLS与下载源响应；不重试或静默换源')));
             req.on('error', reject);
             req.end();
         });
@@ -116,6 +119,9 @@ export async function downloadThroughProxy(source, lease, signal, maxRedirects,
     }
     catch (error) {
         await lease.release();
+        const observed = observationNeed(error);
+        if (observed)
+            return { ok: false, error: observed };
         const code = error instanceof Error && ['DOWNLOAD_REDIRECT_LIMIT', 'DOWNLOAD_SOURCE_INVALID'].includes(error.message) ? error.message : 'HOST_DOWNLOAD_FAILED';
         return fail(code, '经主机下载失败，根因未查明', '检查主机出口、下载源和具名重定向上限；无本机直出替代');
     }

package/lib/index.js

@@ -2,15 +2,22 @@ import z from '@deepseek-ai/schemastery';
 import { createActivationService } from "./activation.js";
 import { resolvePackagedHelper } from "./packaged-helper.js";
 export const name = 'ai-workbench-network';
-const positive = () => z.number().min(0.001);
+const positive = () => z.number().min(0.001).max(2147483.647);
+const bytes = () => z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER);
 export const Config = z.object({
     configFile: z.string().description('远程主机连接配置文件（由插件提供；无默认值）'),
     helperLogFile: z.string().description('远程主机连接诊断日志文件（无默认值）'),
-    startupObservationSeconds: positive().description('连接组件启动状态的最长观察时间（秒，无默认值）'),
-    shutdownObservationSeconds: positive().description('连接组件正常退出的等待时间（秒，无默认值）；超时后强制结束并报告'),
-    controlResponseMaxBytes: z.number().step(1).min(1).description('本机连接控制响应的最大字节数（无默认值）'),
-    downloadMaxRedirects: z.number().step(1).min(0).description('通过远程主机下载时允许的最大重定向次数（无默认值）'),
-});
+    startupObservationSeconds: positive().description('启动观察 startupObservationSeconds（秒）：默认未设，沿开通值（现值35）；等待组件ready仅为可观测性；增大等更久，减小可能提前报未知；无关闭值，超时给等待事项、已等时长和排查步骤'),
+    shutdownObservationSeconds: positive().description('退出观察 shutdownObservationSeconds（秒）：默认未设，沿开通值（现值10）；等待自有组件正常退出，仅为可观测性；增大清理等更久，减小可能强制结束并报告；无关闭值，不终止未知进程'),
+    controlResponseMaxBytes: bytes().description('控制响应上限 controlResponseMaxBytes（字节）：默认未设，沿开通值（现值65536）；控制JSON、ready及代理首帧；增大增加内存，减小可能拒绝合法帧；无关闭或无限值，不限制下载正文'),
+    downloadMaxRedirects: z.number().step(1).min(0).max(Number.MAX_SAFE_INTEGER).description('下载重定向上限 downloadMaxRedirects：默认未设，沿开通值（现值3）；增大允许更多HTTPS跳转，减小可能拒绝下载，0关闭跳转；不自动换源'),
+    statusRefreshIntervalSeconds: positive().description('状态刷新间隔 statusRefreshIntervalSeconds（秒）：默认沿已开通配置（现值2）；影响组件状态查询及插件轮询；增大提示更迟，减小增加查询开销；无关闭值，不代表失败重试已修复'),
+    dialTimeoutSeconds: positive().description('拨号观察 dialTimeoutSeconds（秒）：默认沿已开通配置（现值20）；远端TCP/SSH、控制响应头、下载CONNECT/响应头；Node请求采用阶段空闲观察，仅为可观测性，增大等更久，减小可能提前中止；无关闭值，超时说明等待事项、已等时长、下一步检查，不是修复'),
+    headerTimeoutSeconds: z.number().min(1e-9).max(9223372036.854774).description('请求头观察 headerTimeoutSeconds（秒）：默认沿已开通配置（现值10）；本机控制与登录代理请求头；仅为可观测性，增大保留连接更久，减小可能拒绝慢请求头；无关闭值，超时在私有日志说明等待事项、已等时长、下一步检查'),
+    enrollmentObservationSeconds: z.number().min(1e-9).max(9223372036.854774).description('首次入网观察 enrollmentObservationSeconds（秒）：默认沿已开通配置（现值30）；仅观察首次开通结果，不用于删除已有身份；增大等更久，减小可能更早报未知；无关闭值，超时说明等待事项、已等时长、下一步检查，不重交开通材料'),
+    httpMaxHeaderBytes: bytes().description('本机HTTP头上限 httpMaxHeaderBytes（字节）：默认沿已开通配置（现值1048576）；控制/登录代理请求头及控制响应头；增大增加解析内存，减小可能拒绝合法头；无关闭或无限值，不是正文上限'),
+    httpMaxResponseHeaderBytes: bytes().description('下载HTTP响应头上限 httpMaxResponseHeaderBytes（字节）：默认沿已开通配置（现值1048576）；主机代理及下载响应头/CONNECT头；增大增加解析内存，减小可能拒绝合法头；无关闭或无限值，不是正文上限'),
+}).description('运行策略优先级：本插件显式值 > 开通方传入值 > 原私有配置；未设置沿用原值，不注入新数值默认。活动连接改策略须正常重载插件，不重交开通材料。固定正确性约束不可关闭：macOS控制socket路径≤103字节、端口1–65535、计时器/整数可表示范围、私有700/600权限、当前用户与单身份隔离、SHA256及加密随机凭据强度。');
 export function register(ctx, api) {
     ctx.provide('aiWorkbenchNetwork', api);
     ctx.effect(() => { void api.start(); return () => api.dispose(); });

package/lib/network.js

@@ -5,6 +5,8 @@ import { privateFile, verifyExecutable } from "./private.js";
 import { control, jsonResponse, firstFrame } from "./control.js";
 import { fail, ok } from "./api.js";
 import { downloadThroughProxy } from "./download.js";
+import { effectiveConfig, helperPolicyArgs, validHelperPolicy } from "./settings.js";
+import { ObservationExpired, observationNeed } from "./observation.js";
 const seconds = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0.001 && v * 1000 <= 2147483647;
 const integer = (v) => Number.isSafeInteger(v) && Number(v) > 0;
 const quote = (s) => "'" + s.replaceAll("'", "'\\''") + "'";
@@ -39,7 +41,7 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
     let state = { phase: 'starting' }, cfg, child;
     let starting, disposing, disposed = false, online = false;
     let poll;
-    let processFailed = false, startupReceipt, terminalNeed, stoppingChild;
+    let processFailed = false, startupReceipt, terminalNeed, stoppingChild, shutdownNeed;
     const childGone = new AbortController();
     const lifetime = new AbortController(), listeners = new Set(), updates = new Set();
     const leases = new Set();
@@ -72,9 +74,10 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
         if (!owned?.pid || owned.exitCode !== null || owned.signalCode !== null)
             return false;
         const exit = new Promise(resolve => owned.once('exit', () => resolve()));
+        const started = performance.now();
         owned.kill('SIGTERM');
         let forced = false, timer;
-        await Promise.race([exit, new Promise(resolve => { timer = setTimeout(() => { forced = true; owned.kill('SIGKILL'); resolve(); }, settings.shutdownObservationSeconds * 1000); })]);
+        await Promise.race([exit, new Promise(resolve => { timer = setTimeout(() => { forced = true; shutdownNeed = observationNeed(new ObservationExpired('HELPER_SHUTDOWN_FORCED', 'shutdownObservationSeconds', settings.shutdownObservationSeconds, started, '自有网络组件正常退出', '检查组件退出日志；本次仅强制结束自有进程，不终止未知进程')); owned.kill('SIGKILL'); resolve(); }, settings.shutdownObservationSeconds * 1000); })]);
         if (timer)
             clearTimeout(timer);
         if (forced)
@@ -94,9 +97,14 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
             if (!disposed && alive())
                 publish({ phase: s.enrollment === 'online' && !s.error ? 'online' : s.error ? 'blocked' : 'starting', status: s, ...s.error ? { error: s.error } : {} });
         }
-        catch {
-            if (!disposed && alive())
-                block('CONTROL_UNAVAILABLE', '连接中断，正在等待网络组件恢复；根因未查明。', '等待恢复后自动重新连接；持续无响应时联系管理员');
+        catch (error) {
+            if (!disposed && alive()) {
+                const observed = observationNeed(error);
+                if (observed)
+                    publish({ phase: 'blocked', error: observed });
+                else
+                    block('CONTROL_UNAVAILABLE', '连接中断，正在等待网络组件恢复；根因未查明。', '检查组件私有日志、控制socket和当前网络；状态刷新不是修复，不重启或重交材料');
+            }
         }
         if (!disposed && alive())
             poll = setTimeout(() => void observe(), cfg.statusRefreshIntervalSeconds * 1000);
@@ -119,6 +127,9 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
             finally {
                 await file.close();
             }
+            if (!validHelperPolicy(settings))
+                throw new Error('CONFIG_INVALID');
+            cfg = effectiveConfig(cfg, settings);
             if (normalize(settings.helperLogFile) !== settings.helperLogFile || normalize(settings.configFile) !== settings.configFile)
                 throw new Error('CONFIG_INVALID');
             const canonical = async (p) => { try {
@@ -175,7 +186,7 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
                 return;
             }
             try {
-                child = spawn(executable.path, ['serve', '--config', settings.configFile], { stdio: ['ignore', 'pipe', log.fd], env: { ...process.env } });
+                child = spawn(executable.path, ['serve', '--config', settings.configFile, ...helperPolicyArgs(settings)], { stdio: ['ignore', 'pipe', log.fd], env: { ...process.env } });
             }
             catch (error) {
                 await log.close();
@@ -196,7 +207,8 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
             processChild.once('exit', exited);
             const ready = new Promise((resolve, reject) => {
                 let data = Buffer.alloc(0), settled = false;
-                const timer = setTimeout(() => finish(new Error('HELPER_STARTUP_EXPIRED')), settings.startupObservationSeconds * 1000);
+                const started = performance.now();
+                const timer = setTimeout(() => finish(new ObservationExpired('HELPER_STARTUP_EXPIRED', 'startupObservationSeconds', settings.startupObservationSeconds, started, '自有网络组件ready首帧', '检查组件私有日志、完整性与启动状态；保留身份，不重交开通材料')), settings.startupObservationSeconds * 1000);
                 const aborted = () => finish(new Error('DISPOSED'));
                 const earlyExit = () => finish(new Error('HELPER_EXITED'));
                 const errored = () => finish(new Error('HELPER_START_FAILED'));
@@ -258,10 +270,12 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
             if (disposed)
                 return;
             const code = error instanceof Error && /^(LOCAL_PERMISSION_DENIED|LOCAL_PATH_INVALID|HELPER_[A-Z_]+|CONTROL_[A-Z_]+|CONFIG_INVALID)$/.test(error.message) ? error.message : 'CONFIG_INVALID';
-            terminal(startupNeed ?? needs(code, '网络组件未能启动，根因未查明', '管理员检查安装配置、helper完整性和私有日志'));
+            terminal(startupNeed ?? observationNeed(error) ?? needs(code, '网络组件未能启动，根因未查明', '管理员检查安装配置、helper完整性和私有日志'));
             const forced = await stopOwned();
-            if (forced && terminalNeed)
-                terminalNeed.cause = '自有helper未在shutdownObservationSeconds内退出，已SIGKILL清理';
+            if (forced && terminalNeed) {
+                terminalNeed.cause = [terminalNeed.cause, shutdownNeed?.message, shutdownNeed?.needs].filter(Boolean).join('；');
+                publish({ ...state, error: terminalNeed });
+            }
         }
     })();
     const api = {
@@ -325,11 +339,12 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
                     return fail('DISPOSED', '登录代理已取消', '重新发起登录');
                 return ok(current);
             }
-            catch {
+            catch (error) {
                 owner.abort();
                 signal.removeEventListener('abort', cancel);
                 lifetime.signal.removeEventListener('abort', cancel);
                 childGone.signal.removeEventListener('abort', cancel);
+                diagnostic ??= observationNeed(error);
                 return diagnostic ? { ok: false, error: diagnostic } : fail('PROXY_UNAVAILABLE', '登录代理未能建立，根因未查明', '查看主机网络与信任材料');
             }
         },
@@ -346,7 +361,7 @@ export function createNetwork(settings, executable, emit = () => { }, controlIO
                 await starting;
                 await Promise.all([...leases].map(x => x.release()));
                 const forced = await stopOwned();
-                publish(forced ? { phase: 'blocked', error: needs('HELPER_SHUTDOWN_FORCED', '网络组件未在配置期限内退出，已终止自有进程', '管理员检查组件退出日志') } : { phase: 'stopped' });
+                publish(forced ? { phase: 'blocked', error: shutdownNeed } : { phase: 'stopped' });
                 listeners.clear();
                 updates.clear();
             })();

package/lib/observation.d.ts

@@ -0,0 +1,6 @@
+import type { Need } from './api.ts';
+export declare class ObservationExpired extends Error {
+    readonly need: Need;
+    constructor(code: string, setting: string, seconds: number, started: number, waitingFor: string, nextStep: string);
+}
+export declare function observationNeed(error: unknown): Need | undefined;

package/lib/observation.js

@@ -0,0 +1,14 @@
+// Only fixed stage descriptions and numeric timings enter public diagnostics.
+export class ObservationExpired extends Error {
+    need;
+    constructor(code, setting, seconds, started, waitingFor, nextStep) {
+        const elapsed = Math.max(0, (performance.now() - started) / 1000);
+        const message = `等待${waitingFor}，已等${elapsed.toFixed(3)}秒（${setting}=${seconds}秒），观察期限已到，根因未查明。`;
+        super(message + ' 下一步：' + nextStep);
+        this.name = 'ObservationExpired';
+        this.need = { code, message, needs: nextStep, actor: 'network', cause: JSON.stringify({ setting, configuredSeconds: seconds, elapsedSeconds: elapsed, waitingFor }) };
+    }
+}
+export function observationNeed(error) {
+    return error instanceof ObservationExpired ? structuredClone(error.need) : undefined;
+}

package/lib/packaged-helper.js

@@ -1,25 +1,29 @@
-import { createRequire } from 'node:module';
-import { readFileSync } from 'node:fs';
+import { readFileSync, lstatSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { fail, ok } from "./api.js";
 export function resolvePackagedHelper(moduleURL, platform = process.platform, arch = process.arch) {
+    if (platform !== 'darwin' || !['arm64', 'x64'].includes(arch))
+        return fail('HELPER_PLATFORM_UNSUPPORTED', `我需要支持 ${platform}-${arch} 的联网助手。`, '当前提供 macOS arm64 和 x64，请管理员核对设备平台');
     const name = `@ai-workbench/net-helper-${platform}-${arch}`;
     let expected;
     try {
         const root = JSON.parse(readFileSync(new URL('../package.json', moduleURL), 'utf8'));
-        expected = root.optionalDependencies?.[name];
-        if (expected === undefined)
-            return fail('HELPER_PLATFORM_UNSUPPORTED', `我需要支持 ${platform}-${arch} 的联网助手包。`, '当前提供 macOS arm64 和 x64 平台包，请管理员核对设备平台');
-        if (expected !== root.version)
-            throw new Error('平台助手依赖必须与主包版本精确一致');
-        const require = createRequire(moduleURL), metadata = JSON.parse(readFileSync(require.resolve(name + '/package.json'), 'utf8'));
-        if (metadata.name !== name || metadata.version !== expected || JSON.stringify(metadata.os) !== JSON.stringify([platform]) || JSON.stringify(metadata.cpu) !== JSON.stringify([arch]))
-            throw new Error('平台助手包的名称、版本或平台不匹配');
-        const manifest = JSON.parse(readFileSync(require.resolve(name + '/helper-manifest.json'), 'utf8'));
+        expected = root.version;
+        if (root.name !== '@ai-workbench/network' || typeof expected !== 'string' || !expected)
+            throw new Error('network主包的名称或版本无效');
+        const dir = new URL(`../helpers/${platform}-${arch}/`, moduleURL);
+        const metadata = JSON.parse(readFileSync(new URL('package.json', dir), 'utf8'));
+        if (metadata.name !== name || metadata.version !== expected || metadata.private !== true || JSON.stringify(metadata.os) !== JSON.stringify([platform]) || JSON.stringify(metadata.cpu) !== JSON.stringify([arch]))
+            throw new Error('内嵌助手的名称、版本或平台不匹配');
+        const manifest = JSON.parse(readFileSync(new URL('helper-manifest.json', dir), 'utf8'));
         if (manifest.platform !== platform || manifest.arch !== arch || typeof manifest.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(manifest.sha256))
-            throw new Error('平台助手 manifest 的架构或摘要无效');
-        return ok({ path: require.resolve(name + '/bin/aw-net'), sha256: manifest.sha256, platform, arch });
+            throw new Error('内嵌助手 manifest 的架构或摘要无效');
+        const path = fileURLToPath(new URL('bin/aw-net', dir)), st = lstatSync(path);
+        if (!st.isFile() || st.isSymbolicLink())
+            throw new Error('内嵌助手不是普通二进制文件');
+        return ok({ path, sha256: manifest.sha256, platform, arch });
     }
     catch (cause) {
-        return { ok: false, error: { code: 'HELPER_NOT_PACKAGED', message: '我需要完整的当前平台联网助手包。', needs: `请管理员安装 ${name}${expected ? '@' + expected : '（与主包同版本）'}；不要切换架构或改用旧助手`, actor: 'network', cause: cause instanceof Error ? cause.message : String(cause) } };
+        return { ok: false, error: { code: 'HELPER_NOT_PACKAGED', message: '我需要完整的当前版本远程主机网络插件。', needs: `请管理员重新安装 @ai-workbench/network${expected ? '@' + expected : ''} 的完整包；不要切换架构或改用旧助手`, actor: 'network', cause: cause instanceof Error ? cause.message : String(cause) } };
     }
 }

package/lib/settings.d.ts

@@ -0,0 +1,10 @@
+import type { PluginSettings, HelperConfig } from './api.ts';
+export declare const helperPolicyFields: readonly ["statusRefreshIntervalSeconds", "dialTimeoutSeconds", "headerTimeoutSeconds", "enrollmentObservationSeconds", "httpMaxHeaderBytes", "httpMaxResponseHeaderBytes"];
+export declare const pluginPolicyFields: readonly ["startupObservationSeconds", "shutdownObservationSeconds", "controlResponseMaxBytes", "downloadMaxRedirects"];
+export declare const settingsFields: readonly ["configFile", "helperLogFile", "startupObservationSeconds", "shutdownObservationSeconds", "controlResponseMaxBytes", "downloadMaxRedirects", "statusRefreshIntervalSeconds", "dialTimeoutSeconds", "headerTimeoutSeconds", "enrollmentObservationSeconds", "httpMaxHeaderBytes", "httpMaxResponseHeaderBytes"];
+export declare const timerSeconds: (v: unknown) => v is number;
+export declare const positiveInteger: (v: unknown) => v is number;
+export declare function validHelperPolicy(settings: PluginSettings): boolean;
+export declare function mergedSettings(initial: PluginSettings, provided: PluginSettings): PluginSettings;
+export declare function effectiveConfig(config: HelperConfig, settings: PluginSettings): HelperConfig;
+export declare function helperPolicyArgs(settings: PluginSettings): string[];

package/lib/settings.js

@@ -0,0 +1,34 @@
+export const helperPolicyFields = ['statusRefreshIntervalSeconds', 'dialTimeoutSeconds', 'headerTimeoutSeconds', 'enrollmentObservationSeconds', 'httpMaxHeaderBytes', 'httpMaxResponseHeaderBytes'];
+export const pluginPolicyFields = ['startupObservationSeconds', 'shutdownObservationSeconds', 'controlResponseMaxBytes', 'downloadMaxRedirects'];
+export const settingsFields = ['configFile', 'helperLogFile', ...pluginPolicyFields, ...helperPolicyFields];
+export const timerSeconds = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0.001 && v * 1000 <= 2147483647;
+export const positiveInteger = (v) => Number.isSafeInteger(v) && Number(v) > 0;
+export function validHelperPolicy(settings) {
+    return helperPolicyFields.every(key => {
+        const v = settings[key];
+        if (v === undefined)
+            return true;
+        if (key === 'httpMaxHeaderBytes' || key === 'httpMaxResponseHeaderBytes')
+            return positiveInteger(v);
+        if (key === 'dialTimeoutSeconds' || key === 'statusRefreshIntervalSeconds')
+            return timerSeconds(v);
+        return typeof v === 'number' && Number.isFinite(v) && v >= 1e-9 && v < 9223372036.854775;
+    });
+}
+export function mergedSettings(initial, provided) {
+    const merged = { ...provided };
+    for (const key of [...pluginPolicyFields, ...helperPolicyFields])
+        if (initial[key] !== undefined)
+            merged[key] = initial[key];
+    return merged;
+}
+export function effectiveConfig(config, settings) {
+    const result = { ...config };
+    for (const key of helperPolicyFields)
+        if (settings[key] !== undefined)
+            result[key] = settings[key];
+    return result;
+}
+export function helperPolicyArgs(settings) {
+    return helperPolicyFields.flatMap(key => settings[key] === undefined ? [] : ['--' + key, String(settings[key])]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-workbench/network",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "type": "module",
   "engines": {
     "node": ">=24.13.1"
@@ -25,7 +25,8 @@
     "lib",
     "NOTICE.md",
     "cordis.patch.yml",
-    "locale"
+    "locale",
+    "helpers"
   ],
   "dsh": {
     "bundle": {
@@ -55,10 +56,6 @@
     "dsh-plugin",
     "deepseek-harness"
   ],
-  "optionalDependencies": {
-    "@ai-workbench/net-helper-darwin-arm64": "0.4.1",
-    "@ai-workbench/net-helper-darwin-x64": "0.4.1"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/yzsnstotz/ai-workbench-network.git"