@ai-workbench/network 0.0.0-stage → 0.4.1

package/NOTICE.md

@@ -0,0 +1,18 @@
+# 依赖与来源（N 第 1 轮）
+
+N2 helper 已接入固定 tsnet 并可通过 Makefile 构建；未部署、未发包。认证HTTP/CONNECT代理及Electron44组件诊断已交；DSH插件0.3.0及新消费者Cordis组件诊断已交。真实证据见 N 回执。
+
+| 组件 | 固定版本/来源提交 | 协议 | 用途及当前证据 |
+|---|---|---|---|
+| tailscale.com/tsnet | v1.104.1 / `9a522a9786c97eb7910c01ccb7bd66557b04c910` | BSD-3-Clause | [上游源码](https://github.com/tailscale/tailscale/tree/v1.104.1/tsnet)，实际 helper 依赖；完整闭包固定于 go.mod/go.sum |
+| tailscaled HTTP proxy | 同上，`cmd/tailscaled/proxy.go` | BSD-3-Clause | [CONNECT 处理源码](https://github.com/tailscale/tailscale/blob/v1.104.1/cmd/tailscaled/proxy.go)，只读参考；本实现使用net/http.ReverseProxy及SSH direct-tcpip，未复制该文件 |
+| DeepSeek Harness | 0.2.0-rc.2 / `639ed015397290b3745d163aafe02ffee4aa3f84` | MIT（已复核固定源码package.json），不复制核心代码 | [官方上游](https://github.com/deepseek-ai/deepseek-harness/tree/dsh-v0.2.0-rc.2)，只读参考；实现只在本仓，浅克隆验证完成后精确清理 |
+| Go | 构建固定1.27.3；目标tsnet要求至少1.27.1 | BSD-3-Clause | `go mod download tailscale.com@v1.104.1` 自动选择 1.27.3。已用自动选择的1.27.3通过普通/race/vet/build |
+
+模块下载校验：`h1:9GNOm9Izqll9RH5jA5NWcLiCzXi/WtqY4EHQY2Dy2zk=`；go.mod 校验：`h1:Cb1XjScRgSOeRD7NW6uCEznme782WiOU9IxqyTWoRf0=`。原始下载元数据来自 Go 模块校验，不是构建/真实联网证明。
+
+升级注意：N2 强制用户态 netstack 拨号使用公开但不稳定 Server.Sys/Dialer API，避开 Server.Dial 的系统回退；状态恢复预检和测试依赖同版本的 StateStore/Prefs/LoginProfile 与官方启动选择逻辑。升级必须复验这些边界，不能只改版本号。
+
+N3 SSH使用 golang.org/x/crypto/ssh v0.57.0（BSD-3-Clause；实际锁定版本见go.mod）；只使用none认证与可信known_hosts。Electron44.0.0官方darwin-arm64 ZIP为诊断工具，MIT及其随附第三方许可；SHA256与引擎版本见 `docs/evidence/n3-2026-10-20/electron-artifact.json`。独立进程/内存session，没有复制进发布包。
+
+N4插件peer：@deepseek-ai/cordis4.0.4、@deepseek-ai/schemastery3.18.4，均MIT，来源为固定DSH提交的vendor目录及官方npm包。TS5.9.3/Node24类型是构建依赖；实际闭包固定package-lock.json，新消费者闭包另存证据。主机下载只用Node内置http/https/tls/stream，经helper认证CONNECT，不新增外部代理库。源码/API升级需要在自有仓库适配，不提上游PR/issue或等待上游修改。

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+安装：在 DSH「插件 → 添加插件」填写 `@ai-workbench/network@0.4.1`，或运行 `dsh plugin --profile desktop add @ai-workbench/network@0.4.1`。
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# 远程主机网络
+
+0.4.1 当前为待发布版本，由编排统一发布公开 npm；工人不执行 publish。发布前可由官方添加插件入口安装本轮固定主包 tgz 的绝对路径，平台依赖也须可解析。
+
+插件通过官方 bundle/Cordis 接口提供远程主机网络、设备身份、SSH 通道、认证登录代理及主机下载能力。不替换 DSH 服务、布局或默认设置，不增加工作区/登录界面。L 负责可信连接资料导入和登录入口，员工不手填主机、用户名、路径或密钥。没有连接资料时明确说明需要导入，不把插件 Running 当作网络已连接。
+
+主包不携带 Go 二进制；精确依赖同版本的 `@ai-workbench/net-helper-darwin-arm64`、`@ai-workbench/net-helper-darwin-x64`。npm/pnpm 按 os/cpu 安装当前平台包，插件只解析该包，检查版本、平台和 manifest，启动前验证助手 SHA256。缺包、损坏或平台不支持时明确说明“我需要 X”，不使用 PATH、旧助手、另一架构或安装时下载。三个包均不需要 postinstall/prepare 或构建脚本；预编译文件直接入包。平台包同时附实际目标编译闭包的许可证原文及来源摘要（含 Go 标准库内 vendor）；构建遇缺失或不可读声明会明确失败。现阶段只提供 macOS arm64/x64，x64 的构建/文件检查不代表 Intel 真机验收。
+
+一个默认 profile 只启用一个 N 条目。独立安装与 L 聚合安装不要重复挂载 N。N 的网络身份按系统用户隔离、持久保存；不重交未知结果的一次性 key。公开 `aiWorkbenchNetwork.activate(settings, signal)`、`getActivationState/onActivationState` 和通道 API；公开类型入口 `/api`，Cordis 类型入口 `/cordis`。`active` 表示身份恢复与消费交接完成，不等于主机 SSH 或 AI 登录已通过。六项现有设置必须由 L 按可信材料及具名策略提供，无新默认值。
+
+开发：Node >=24.13.1、Go 1.27.3、固定 tsnet v1.104.1。运行 `npm ci --ignore-scripts --omit=optional`、`npm test`、`npm run check`、`make test`、`make test-race`、`make vet`，再执行 `npm run build`。build 显式交叉构建两个 macOS 平台包并编译 TypeScript；Go 参数固定 ts_omit_logtail、禁 VCS 元数据、trimpath、CGO_ENABLED=0。这些是开发命令，员工安装不执行。二进制、manifest 和 NOTICE 副本由构建生成，不提交。
+
+发布准备按 arm64 平台包 → x64 平台包 → 主包顺序 pack/dry-run，版本必须一致；固定 tgz、SHA256、文件清单及证据见仓库 `docs/evidence/2026-10-21-N-npm/` 和 N 回执。不要把先前单平台 0.4.0 的旧 lib/bin 混入本轮产物。根盘按当前编排规则低于8GiB停；临时 HOME、依赖、日志和构建缓存放自有 Elements APFS，用后精确清理，不删除公共缓存。
+
+完整提供方合同见仓库 `contracts/net-helper.md`，第三方来源见包内 NOTICE.md。只做中文，既有英文名称保留。官方 DSH 与 HanaMesh 分别验证；不使用 owner 当前实例，GUI 加载门不替代真实入网、登录、对话、物理断网或 leo E 验收。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: ai-workbench-network
+      name: '@ai-workbench/network'

package/lib/activation.d.ts

@@ -0,0 +1,6 @@
+import { createNetwork } from './network.ts';
+import type { Executable } from './network.ts';
+import type { NetworkApi, NetworkState, PluginSettings } from './api.ts';
+export declare function createActivationService(initial: PluginSettings, executable: Executable, emit?: (s: NetworkState) => void, factory?: typeof createNetwork): NetworkApi & {
+    start(): Promise<void>;
+};

package/lib/activation.js

@@ -0,0 +1,151 @@
+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'];
+function normalized(s) {
+    if (!s || typeof s !== 'object' || Object.keys(s).some(k => !fields.includes(k)))
+        return;
+    if (typeof s.configFile !== 'string' || !isAbsolute(s.configFile) || typeof s.helperLogFile !== 'string' || !isAbsolute(s.helperLogFile) || s.configFile === s.helperLogFile)
+        return;
+    for (const v of [s.startupObservationSeconds, s.shutdownObservationSeconds])
+        if (typeof v !== 'number' || !Number.isFinite(v) || v < 0.001 || v * 1000 > 2147483647)
+            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]]));
+}
+// One stable Cordis service; callers never own, restart or borrow helper processes.
+export function createActivationService(initial, executable, emit = () => { }, factory = createNetwork) {
+    let network = { phase: 'blocked', error: { code: 'SETTINGS_REQUIRED', message: '我需要导入连接资料。', needs: '在设置 → 远程主机连接 导入连接资料', actor: 'network' } };
+    let activation = { instanceId: randomUUID(), revision: 0, phase: 'unconfigured', receipt: null, error: network.error };
+    let runtime, selected, disposed = false, disposing, handoff, generation = 0, handedOff = false, consumerOnline = false;
+    const listeners = new Set(), edges = new Set(), updates = new Set();
+    const snapshot = () => structuredClone(activation);
+    function publish(phase, error, receipt = activation.receipt) {
+        activation = { ...activation, revision: activation.revision + 1, phase, error, receipt };
+        for (const listener of listeners)
+            try {
+                listener(snapshot());
+            }
+            catch {
+                console.error('NETWORK_ACTIVATION_OBSERVER_FAILED');
+            }
+        for (const update of updates)
+            update();
+    }
+    function observed(next) {
+        if (disposed)
+            return;
+        network = next;
+        emit(structuredClone(next));
+        if (disposed)
+            return;
+        const receipt = next.status?.receipt ?? activation.receipt;
+        const unknown = next.error?.code === 'ENROLLMENT_RESULT_UNKNOWN';
+        const current = unknown ? { apiVersion: 1, session: 'key', key: 'unknown', identity: 'unconfirmed', cleanup: 'pending' } : receipt;
+        const operational = !next.error || ['NETWORK_INTERRUPTED', 'HOST_OFFLINE', 'HOST_NOT_VISIBLE'].includes(next.error.code);
+        const clean = current?.identity === 'resumable' && (current.cleanup === 'complete' || current.cleanup === 'not-required');
+        if (clean && current?.session === 'key' && operational) {
+            if (handedOff) {
+                observed({ phase: 'blocked', error: { code: 'CONTROL_PROTOCOL_INVALID', message: '身份恢复组件错误地保留密钥。', needs: '管理员核对组件版本', actor: 'network' } });
+                return;
+            }
+            publish('activating', null, current);
+            if (!disposed && !handoff) {
+                const owned = runtime;
+                generation++;
+                handoff = Promise.resolve().then(async () => {
+                    await owned.dispose();
+                    if (disposed)
+                        return;
+                    if (owned.getState().error) {
+                        observed(owned.getState());
+                        return;
+                    }
+                    if (handedOff) {
+                        observed({ phase: 'blocked', error: { code: 'CONTROL_PROTOCOL_INVALID', message: '网络身份交接状态无效。', needs: '管理员核对helper版本', actor: 'network' } });
+                        return;
+                    }
+                    handedOff = true;
+                    install(JSON.parse(selected));
+                    launch();
+                }).catch(() => observed({ phase: 'blocked', error: { code: 'HELPER_HANDOFF_FAILED', message: '网络身份交接失败，根因未查明。', needs: '保留身份并检查私有日志；不要重交密钥', actor: 'network' } }));
+            }
+            return;
+        }
+        const ready = clean && current?.session === 'identity' && !!next.status?.receipt;
+        publish(ready && operational ? 'active' : next.error ? 'blocked' : 'activating', next.error ?? null, current);
+        if (disposed)
+            return;
+        const was = consumerOnline;
+        consumerOnline = ready && next.phase === 'online';
+        if (was !== consumerOnline)
+            for (const listener of edges)
+                try {
+                    listener({ kind: consumerOnline ? 'restored' : 'lost', state: structuredClone(next) });
+                }
+                catch {
+                    console.error('NETWORK_OBSERVER_FAILED');
+                }
+    }
+    function install(config) {
+        const ownGeneration = ++generation;
+        runtime = factory(config, executable, next => { if (ownGeneration === generation)
+            observed(next); });
+    }
+    function launch() {
+        const owned = runtime, ownGeneration = generation;
+        void owned.start().then(() => {
+            if (!disposed && ownGeneration === generation && !network.error && !network.status?.receipt)
+                observed({ phase: 'blocked', error: { code: 'ENROLLMENT_RECEIPT_REQUIRED', message: '网络组件缺少消费确认。', needs: '管理员核对插件与helper版本', actor: 'network' } });
+        }).catch(() => { if (ownGeneration === generation)
+            observed({ phase: 'blocked', error: { code: 'HELPER_START_FAILED', message: '网络组件未能启动，根因未查明。', needs: '管理员检查私有日志', actor: 'network' } }); });
+    }
+    const api = {
+        async start() { if (disposed)
+            return; if (Object.keys(initial).length)
+            await api.activate(initial, new AbortController().signal);
+        else
+            emit(structuredClone(network)); },
+        getState: () => structuredClone(network), getActivationState: snapshot,
+        onState(listener) { edges.add(listener); return () => edges.delete(listener); },
+        onActivationState(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+        async activate(settings, signal) {
+            if (disposed || signal.aborted)
+                return fail('ACTIVATION_CANCELLED', '连接激活等待已取消。', '查询当前激活结果；不要重复提交密钥');
+            const config = normalized(settings);
+            if (!config)
+                return fail('SETTINGS_REQUIRED', '我需要有效的连接配置。', 'L提供六项具名网络设置');
+            const key = JSON.stringify(config);
+            if (selected !== undefined && selected !== key)
+                return fail('ACTIVATION_CONFLICT', '已有连接激活，不能替换身份。', '管理员核对当前开通上下文');
+            if (!runtime) {
+                selected = key;
+                install(config);
+                publish('activating', null);
+                if (!disposed)
+                    launch();
+            }
+            await new Promise(resolve => {
+                const done = () => { if (!disposed && !signal.aborted && activation.phase === 'activating')
+                    return; updates.delete(done); signal.removeEventListener('abort', done); resolve(); };
+                updates.add(done);
+                signal.addEventListener('abort', done, { once: true });
+                done();
+            });
+            if (disposed || signal.aborted)
+                return fail('ACTIVATION_CANCELLED', '连接激活等待已取消。', '查询当前激活结果；不要重复提交密钥');
+            return activation.phase === 'active' ? ok(snapshot()) : { ok: false, error: activation.error };
+        },
+        async connect(target, signal) { if (disposed)
+            return fail('DISPOSED', '网络服务已停止。', '重新加载插件'); return activation.phase === 'active' && runtime ? runtime.connect(target, signal) : { ok: false, error: network.error ?? { code: 'NETWORK_NOT_READY', message: '连接尚未就绪。', needs: '等待N身份交接完成', actor: 'network' } }; },
+        async openLoginProxy(signal) { if (disposed)
+            return fail('DISPOSED', '网络服务已停止。', '重新加载插件'); return activation.phase === 'active' && runtime ? runtime.openLoginProxy(signal) : { ok: false, error: network.error ?? { code: 'NETWORK_NOT_READY', message: '连接尚未就绪。', needs: '等待N身份交接完成', actor: 'network' } }; },
+        async download(source, signal) { if (disposed)
+            return fail('DISPOSED', '网络服务已停止。', '重新加载插件'); return activation.phase === 'active' && runtime ? runtime.download(source, signal) : { ok: false, error: network.error ?? { code: 'NETWORK_NOT_READY', message: '连接尚未就绪。', needs: '等待N身份交接完成', actor: 'network' } }; },
+        dispose() { if (disposing)
+            return disposing; disposed = true; return disposing = Promise.resolve().then(async () => { publish('stopped', activation.error); await runtime?.dispose(); await handoff; network = runtime?.getState() ?? { phase: 'stopped' }; emit(structuredClone(network)); publish('stopped', network.error ?? null); listeners.clear(); edges.clear(); updates.clear(); }); },
+    };
+    return api;
+}

package/lib/api.d.ts

@@ -0,0 +1,116 @@
+export interface Need {
+    code: string;
+    message: string;
+    needs: string;
+    actor: string;
+    cause?: string | null;
+}
+export type Result<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: Need;
+};
+export interface HelperStatus {
+    apiVersion: 1;
+    enrollment: string;
+    node: {
+        name: string | null;
+        ips: string[];
+    };
+    host: {
+        name: string | null;
+        online: boolean | null;
+        lastSeenAt: string | null;
+        observedAt: string | null;
+    };
+    error: Need | null;
+    receipt?: EnrollmentReceipt;
+}
+export interface NetworkState {
+    phase: 'starting' | 'online' | 'blocked' | 'stopped';
+    status?: HelperStatus;
+    error?: Need;
+}
+export type NetworkEvent = {
+    kind: 'lost' | 'restored';
+    state: NetworkState;
+};
+export interface EnrollmentTarget {
+    host: string;
+    username: string;
+    port: number;
+    knownHostsFile: string;
+}
+export interface ProxyCredentials {
+    apiVersion: 1;
+    id: string;
+    url: string;
+    username: string;
+    password: string;
+}
+export interface LoginProxyLease {
+    credentials: ProxyCredentials;
+    release(): Promise<void>;
+}
+export interface EnrollmentReceipt {
+    apiVersion: 1;
+    session: 'key' | 'identity';
+    key: 'not-required' | 'unattempted' | 'attempted' | 'confirmed' | 'unknown';
+    identity: 'unconfirmed' | 'resumable';
+    cleanup: 'not-required' | 'pending' | 'complete';
+}
+export interface ActivationState {
+    instanceId: string;
+    revision: number;
+    phase: 'unconfigured' | 'activating' | 'active' | 'blocked' | 'stopped';
+    receipt: EnrollmentReceipt | null;
+    error: Need | null;
+}
+export interface NetworkApi extends NetworkChannels {
+    activate(settings: PluginSettings, signal: AbortSignal): Promise<Result<ActivationState>>;
+    getActivationState(): ActivationState;
+    onActivationState(listener: (state: ActivationState) => void): () => void;
+}
+export interface NetworkChannels {
+    getState(): NetworkState;
+    connect(target: EnrollmentTarget, signal: AbortSignal): Promise<Result<{
+        proxyCommand: string;
+    }>>;
+    onState(listener: (event: NetworkEvent) => void): () => void;
+    openLoginProxy(signal: AbortSignal): Promise<Result<LoginProxyLease>>;
+    download(source: string, signal: AbortSignal): Promise<Result<Response>>;
+    dispose(): Promise<void>;
+}
+export interface PluginSettings {
+    configFile?: string;
+    helperLogFile?: string;
+    startupObservationSeconds?: number;
+    shutdownObservationSeconds?: number;
+    controlResponseMaxBytes?: number;
+    downloadMaxRedirects?: number;
+}
+export interface HelperConfig {
+    apiVersion: 1;
+    stateDir: string;
+    runtimeDir: string;
+    nodeName: string;
+    authKeyFile?: string;
+    host: {
+        name: string;
+        sshPort: number;
+        employee: string;
+        knownHostsFile?: string;
+    };
+    proxyListen: string;
+    statusRefreshIntervalSeconds: number;
+    dialTimeoutSeconds: number;
+    headerTimeoutSeconds: number;
+    enrollmentObservationSeconds: number;
+    httpMaxHeaderBytes: number;
+    httpMaxResponseHeaderBytes: number;
+    logUpload: false;
+}
+export declare const ok: <T>(value: T) => Result<T>;
+export declare const fail: <T = never>(code: string, message: string, needs: string, actor?: string) => Result<T>;

package/lib/api.js

@@ -0,0 +1,2 @@
+export const ok = (value) => ({ ok: true, value });
+export const fail = (code, message, needs, actor = 'network') => ({ ok: false, error: { code, message, needs, actor, cause: null } });

package/lib/control.d.ts

@@ -0,0 +1,4 @@
+import type { IncomingMessage } from 'node:http';
+export declare function control(socket: string, method: string, path: string, signal: AbortSignal, seconds: number, maxHeaderBytes: number): Promise<IncomingMessage>;
+export declare function jsonResponse(response: IncomingMessage, maxBytes: number): Promise<unknown>;
+export declare function firstFrame(response: IncomingMessage, maxBytes: number): Promise<unknown>;

package/lib/control.js

@@ -0,0 +1,57 @@
+import http from 'node:http';
+import { privateSocket } from "./private.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')));
+        req.on('error', reject);
+        req.end();
+    });
+}
+export async function jsonResponse(response, maxBytes) {
+    let bytes = 0;
+    const chunks = [];
+    for await (const chunk of response) {
+        bytes += chunk.length;
+        if (bytes > maxBytes) {
+            response.destroy();
+            throw new Error('CONTROL_RESPONSE_LIMIT');
+        }
+        chunks.push(chunk);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+export async function firstFrame(response, maxBytes) {
+    return new Promise((resolve, reject) => {
+        let data = Buffer.alloc(0);
+        const cleanup = () => { response.off('data', read); response.off('error', error); response.off('end', end); };
+        const error = () => { cleanup(); reject(new Error('CONTROL_STREAM_INVALID')); };
+        const end = () => error();
+        const read = (chunk) => {
+            data = Buffer.concat([data, chunk]);
+            if (data.length > maxBytes) {
+                cleanup();
+                response.destroy();
+                reject(new Error('CONTROL_RESPONSE_LIMIT'));
+                return;
+            }
+            const nl = data.indexOf(10);
+            if (nl < 0)
+                return;
+            cleanup();
+            response.pause();
+            try {
+                resolve(JSON.parse(data.subarray(0, nl).toString('utf8')));
+            }
+            catch {
+                response.destroy();
+                reject(new Error('CONTROL_FRAME_INVALID'));
+            }
+        };
+        response.on('data', read);
+        response.once('error', error);
+        response.once('end', end);
+    });
+}

package/lib/cordis.d.ts

@@ -0,0 +1,10 @@
+import type { NetworkApi, NetworkState } from './api.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        aiWorkbenchNetwork: NetworkApi;
+    }
+    interface Events {
+        'ai-workbench/network-state': (state: NetworkState) => void;
+    }
+}
+export {};

package/lib/cordis.js

@@ -0,0 +1 @@
+export {};

package/lib/download.d.ts

@@ -0,0 +1,2 @@
+import type { LoginProxyLease, Result } from './api.ts';
+export declare function downloadThroughProxy(source: string, lease: LoginProxyLease, signal: AbortSignal, maxRedirects: number, seconds: number, maxHeaderBytes: number): Promise<Result<Response>>;

package/lib/download.js

@@ -0,0 +1,122 @@
+import http from 'node:http';
+import https from 'node:https';
+import tls from 'node:tls';
+import { isIP } from 'node:net';
+import { Readable } from 'node:stream';
+import { fail, ok } from "./api.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) {
+    const proxy = new URL(lease.credentials.url);
+    if (proxy.protocol !== 'http:' || proxy.hostname !== '127.0.0.1' || proxy.username || proxy.password)
+        throw new Error('CONTROL_PROTOCOL_INVALID');
+    const hostname = target.hostname.replace(/^\[|\]$/g, '');
+    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')));
+        req.on('connect', (response, socket, head) => { req.setTimeout(0); if (response.statusCode !== 200) {
+            socket.destroy();
+            reject(new Error('HOST_PROXY_REJECTED'));
+            return;
+        } if (head.length)
+            socket.unshift(head); resolve(socket); });
+        req.on('error', reject);
+        req.end();
+    });
+    // The only TCP socket supplied to TLS is the authenticated local proxy tunnel.
+    const agent = new class extends https.Agent {
+        createConnection(options) { return tls.connect({ ...options, socket: tunnel, servername: isIP(hostname) ? undefined : hostname }); }
+    }({ keepAlive: false });
+    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')));
+            req.on('error', reject);
+            req.end();
+        });
+    }
+    catch (error) {
+        tunnel.destroy();
+        agent.destroy();
+        throw error;
+    }
+}
+export async function downloadThroughProxy(source, lease, signal, maxRedirects, seconds, maxHeaderBytes) {
+    let current;
+    try {
+        current = sourceURL(source);
+    }
+    catch {
+        await lease.release();
+        return fail('DOWNLOAD_SOURCE_INVALID', '通过远程主机下载只支持不含凭据的HTTPS地址', '管理员检查下载源');
+    }
+    try {
+        for (let redirects = 0;; redirects++) {
+            signal.throwIfAborted();
+            const response = await requestViaProxy(current, lease, signal, seconds, maxHeaderBytes);
+            if ([301, 302, 303, 307, 308].includes(response.statusCode) && response.headers.location) {
+                response.destroy();
+                if (redirects >= maxRedirects)
+                    throw new Error('DOWNLOAD_REDIRECT_LIMIT');
+                current = sourceURL(new URL(response.headers.location, current).href);
+                continue;
+            }
+            const headers = new Headers();
+            for (const [key, value] of Object.entries(response.headers))
+                if (value !== undefined) {
+                    for (const v of Array.isArray(value) ? value : [value])
+                        headers.append(key, v);
+                }
+            response.once('end', () => void lease.release());
+            response.once('error', () => void lease.release());
+            response.once('close', () => void lease.release());
+            const empty = [204, 205, 304].includes(response.statusCode);
+            let body = null;
+            if (!empty) {
+                const reader = Readable.toWeb(response).getReader();
+                let closed = false;
+                body = new ReadableStream({
+                    async pull(controller) {
+                        try {
+                            const chunk = await reader.read();
+                            if (closed)
+                                return;
+                            if (chunk.done) {
+                                closed = true;
+                                await lease.release();
+                                controller.close();
+                            }
+                            else
+                                controller.enqueue(chunk.value);
+                        }
+                        catch {
+                            await lease.release();
+                            if (!closed) {
+                                closed = true;
+                                controller.error(new Error('HOST_DOWNLOAD_STREAM_FAILED'));
+                            }
+                        }
+                    },
+                    async cancel() { closed = true; try {
+                        await reader.cancel();
+                    }
+                    finally {
+                        await lease.release();
+                    } },
+                });
+            }
+            const result = new Response(body, { status: response.statusCode, headers });
+            if (empty) {
+                response.resume();
+                await lease.release();
+            }
+            return ok(result);
+        }
+    }
+    catch (error) {
+        await lease.release();
+        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.d.ts

@@ -0,0 +1,12 @@
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { NetworkApi, PluginSettings } from './api.ts';
+export type * from './api.ts';
+export type * from './cordis.ts';
+export declare const name = "ai-workbench-network";
+export type Config = PluginSettings;
+export declare const Config: z<Config>;
+export declare function register(ctx: Context, api: NetworkApi & {
+    start(): Promise<void>;
+}): void;
+export declare function apply(ctx: Context, config?: Config): void;

package/lib/index.js

@@ -0,0 +1,27 @@
+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);
+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('通过远程主机下载时允许的最大重定向次数（无默认值）'),
+});
+export function register(ctx, api) {
+    ctx.provide('aiWorkbenchNetwork', api);
+    ctx.effect(() => { void api.start(); return () => api.dispose(); });
+}
+export function apply(ctx, config = {}) {
+    const executable = resolvePackagedHelper(import.meta.url);
+    if (!executable.ok) {
+        const error = executable;
+        const state = { phase: 'blocked', ...!error.ok ? { error: error.error } : {} };
+        register(ctx, { async activate() { return error; }, getActivationState: () => ({ instanceId: 'unpackaged', revision: 0, phase: 'blocked', receipt: null, error: !error.ok ? error.error : null }), onActivationState: () => () => { }, async start() { ctx.emit('ai-workbench/network-state', state); }, getState: () => structuredClone(state), async connect() { return error; }, onState: () => () => { }, async openLoginProxy() { return error; }, async download() { return error; }, async dispose() { } });
+        return;
+    }
+    register(ctx, createActivationService(config, executable.value, state => ctx.emit('ai-workbench/network-state', state)));
+}

package/lib/network.d.ts

@@ -0,0 +1,11 @@
+import { control } from './control.ts';
+import type { PluginSettings, NetworkChannels, NetworkState } from './api.ts';
+export interface Executable {
+    path: string;
+    sha256: string;
+    platform: string;
+    arch: string;
+}
+export declare function createNetwork(settings: PluginSettings, executable: Executable, emit?: (state: NetworkState) => void, controlIO?: typeof control): NetworkChannels & {
+    start(): Promise<void>;
+};

package/lib/network.js

@@ -0,0 +1,356 @@
+import { spawn } from 'node:child_process';
+import { join, isAbsolute, normalize, dirname, basename, relative, sep } from 'node:path';
+import { realpath, lstat } from 'node:fs/promises';
+import { privateFile, verifyExecutable } from "./private.js";
+import { control, jsonResponse, firstFrame } from "./control.js";
+import { fail, ok } from "./api.js";
+import { downloadThroughProxy } from "./download.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("'", "'\\''") + "'";
+const needs = (code, message, requires) => ({ code, message, needs: requires, actor: 'network', cause: null });
+function receiptFrame(receipt) {
+    if (receipt === undefined)
+        return;
+    if (receipt?.apiVersion !== 1 || !['key', 'identity'].includes(receipt.session) || !['not-required', 'unattempted', 'attempted', 'confirmed', 'unknown'].includes(receipt.key) || !['unconfirmed', 'resumable'].includes(receipt.identity) || !['not-required', 'pending', 'complete'].includes(receipt.cleanup))
+        throw new Error('CONTROL_PROTOCOL_INVALID');
+    if ((receipt.cleanup === 'complete' && (receipt.key !== 'confirmed')) || (receipt.cleanup === 'not-required' && receipt.key !== 'not-required'))
+        throw new Error('CONTROL_PROTOCOL_INVALID');
+    return { apiVersion: 1, session: receipt.session, key: receipt.key, identity: receipt.identity, cleanup: receipt.cleanup };
+}
+function statusFrame(v) {
+    if (v?.apiVersion !== 1 || typeof v.enrollment !== 'string' || !v.node || !v.host || !Array.isArray(v.node.ips) || !v.node.ips.every((x) => typeof x === 'string'))
+        throw new Error('CONTROL_PROTOCOL_INVALID');
+    for (const x of [v.node.name, v.host.name, v.host.lastSeenAt, v.host.observedAt])
+        if (x !== null && typeof x !== 'string')
+            throw new Error('CONTROL_PROTOCOL_INVALID');
+    if (v.host.online !== null && typeof v.host.online !== 'boolean')
+        throw new Error('CONTROL_PROTOCOL_INVALID');
+    let error = null;
+    if (v.error !== null) {
+        if (!v.error || !['code', 'message', 'needs', 'actor'].every(k => typeof v.error[k] === 'string'))
+            throw new Error('CONTROL_PROTOCOL_INVALID');
+        error = { code: v.error.code, message: v.error.message, needs: v.error.needs, actor: v.error.actor, cause: typeof v.error.cause === 'string' ? v.error.cause : null };
+    }
+    const receipt = receiptFrame(v.receipt);
+    return { ...receipt ? { receipt } : {}, apiVersion: 1, enrollment: v.enrollment, node: { name: v.node.name, ips: v.node.ips }, host: { name: v.host.name, online: v.host.online, lastSeenAt: v.host.lastSeenAt, observedAt: v.host.observedAt }, error };
+}
+export function createNetwork(settings, executable, emit = () => { }, controlIO = control) {
+    let state = { phase: 'starting' }, cfg, child;
+    let starting, disposing, disposed = false, online = false;
+    let poll;
+    let processFailed = false, startupReceipt, terminalNeed, stoppingChild;
+    const childGone = new AbortController();
+    const lifetime = new AbortController(), listeners = new Set(), updates = new Set();
+    const leases = new Set();
+    const snapshot = () => structuredClone(state);
+    const publish = (next) => {
+        state = next;
+        const was = online;
+        online = next.phase === 'online';
+        emit(snapshot());
+        for (const update of updates)
+            update();
+        if (was !== online)
+            for (const listener of listeners) {
+                try {
+                    listener({ kind: online ? 'restored' : 'lost', state: snapshot() });
+                }
+                catch {
+                    console.error('NETWORK_OBSERVER_FAILED');
+                }
+            }
+    };
+    const block = (code, message, requires) => publish({ phase: 'blocked', error: needs(code, message, requires) });
+    const socket = () => join(cfg.runtimeDir, 'control.sock');
+    const alive = () => !!child?.pid && !processFailed && child.exitCode === null && child.signalCode === null;
+    const terminal = (need) => { processFailed = true; terminalNeed ??= need; childGone.abort(); if (poll)
+        clearTimeout(poll); if (!disposed)
+        publish({ phase: 'blocked', error: terminalNeed, ...state.status ? { status: state.status } : startupReceipt ? { status: { apiVersion: 1, enrollment: 'error', node: { name: null, ips: [] }, host: { name: null, online: null, lastSeenAt: null, observedAt: null }, error: terminalNeed, receipt: startupReceipt } } : {} }); };
+    const stopOwned = () => stoppingChild ??= (async () => {
+        const owned = child;
+        if (!owned?.pid || owned.exitCode !== null || owned.signalCode !== null)
+            return false;
+        const exit = new Promise(resolve => owned.once('exit', () => resolve()));
+        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); })]);
+        if (timer)
+            clearTimeout(timer);
+        if (forced)
+            await exit;
+        return forced;
+    })();
+    const request = (method, path, signal) => controlIO(socket(), method, path, AbortSignal.any([signal, childGone.signal]), cfg.dialTimeoutSeconds, cfg.httpMaxHeaderBytes);
+    async function observe() {
+        if (disposed || !alive())
+            return;
+        try {
+            const res = await request('GET', '/v1/status', lifetime.signal);
+            const value = await jsonResponse(res, settings.controlResponseMaxBytes);
+            if (res.statusCode !== 200)
+                throw new Error('CONTROL_UNAVAILABLE');
+            const s = statusFrame(value);
+            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', '连接中断，正在等待网络组件恢复；根因未查明。', '等待恢复后自动重新连接；持续无响应时联系管理员');
+        }
+        if (!disposed && alive())
+            poll = setTimeout(() => void observe(), cfg.statusRefreshIntervalSeconds * 1000);
+    }
+    const start = () => starting ??= (async () => {
+        let startupNeed, handshakeComplete = false;
+        try {
+            if (!settings.configFile || !settings.helperLogFile || !seconds(settings.startupObservationSeconds) || !seconds(settings.shutdownObservationSeconds) || !integer(settings.controlResponseMaxBytes) || !Number.isSafeInteger(settings.downloadMaxRedirects) || settings.downloadMaxRedirects < 0) {
+                block('SETTINGS_REQUIRED', '我需要管理员提供网络安装配置和具名设置', '安装期交付N私有config、日志路径、观察期限、响应上限和重定向次数');
+                return;
+            }
+            if (!isAbsolute(settings.helperLogFile) || settings.helperLogFile === settings.configFile)
+                throw new Error('CONFIG_INVALID');
+            const file = await privateFile(settings.configFile);
+            let configStat;
+            try {
+                configStat = await file.stat();
+                cfg = JSON.parse(await file.readFile('utf8'));
+            }
+            finally {
+                await file.close();
+            }
+            if (normalize(settings.helperLogFile) !== settings.helperLogFile || normalize(settings.configFile) !== settings.configFile)
+                throw new Error('CONFIG_INVALID');
+            const canonical = async (p) => { try {
+                return await realpath(p);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                const parent = dirname(p);
+                if (parent === p)
+                    throw error;
+                return join(await canonical(parent), basename(p));
+            } };
+            const logPath = await canonical(settings.helperLogFile);
+            if (logPath === await canonical(settings.configFile) || (cfg?.authKeyFile && logPath === await canonical(cfg.authKeyFile)) || (cfg?.host?.knownHostsFile && logPath === await canonical(cfg.host.knownHostsFile)))
+                throw new Error('CONFIG_INVALID');
+            for (const dir of [cfg?.stateDir, cfg?.runtimeDir]) {
+                if (typeof dir !== 'string' || !isAbsolute(dir))
+                    throw new Error('CONFIG_INVALID');
+                const rel = relative(await canonical(dir), logPath);
+                if (rel === '' || (rel !== '..' && !rel.startsWith('..' + sep) && !isAbsolute(rel)))
+                    throw new Error('CONFIG_INVALID');
+            }
+            if (cfg?.apiVersion !== 1 || !isAbsolute(cfg.runtimeDir) || !cfg.host || !seconds(cfg.statusRefreshIntervalSeconds) || !seconds(cfg.dialTimeoutSeconds) || !integer(cfg.httpMaxHeaderBytes) || !integer(cfg.httpMaxResponseHeaderBytes))
+                throw new Error('CONFIG_INVALID');
+            if (executable.platform !== process.platform || executable.arch !== process.arch)
+                throw new Error('HELPER_PLATFORM_UNSUPPORTED');
+            await verifyExecutable(executable.path, executable.sha256);
+            const log = await privateFile(settings.helperLogFile, true);
+            try {
+                const st = await log.stat();
+                if (st.nlink !== 1)
+                    throw new Error('CONFIG_INVALID');
+                if (st.dev === configStat.dev && st.ino === configStat.ino)
+                    throw new Error('CONFIG_INVALID');
+                if (cfg.authKeyFile) {
+                    try {
+                        const key = await lstat(cfg.authKeyFile);
+                        if (st.dev === key.dev && st.ino === key.ino)
+                            throw new Error('CONFIG_INVALID');
+                    }
+                    catch (error) {
+                        if (error.code !== 'ENOENT')
+                            throw error;
+                    }
+                }
+            }
+            catch (error) {
+                await log.close();
+                throw error;
+            }
+            if (disposed) {
+                await log.close();
+                return;
+            }
+            try {
+                child = spawn(executable.path, ['serve', '--config', settings.configFile], { stdio: ['ignore', 'pipe', log.fd], env: { ...process.env } });
+            }
+            catch (error) {
+                await log.close();
+                throw error;
+            }
+            // Install process handlers before yielding: spawn errors can arrive on nextTick.
+            const logClosed = log.close();
+            const processChild = child;
+            processChild.on('error', () => terminal(needs('HELPER_PROCESS_FAILED', '网络组件进程失败，根因未查明', '管理员检查helper诊断日志')));
+            const exited = () => {
+                processFailed = true;
+                childGone.abort();
+                if (poll)
+                    clearTimeout(poll);
+                if (handshakeComplete)
+                    terminal(startupNeed ?? needs('HELPER_EXITED', '网络组件已退出，根因未查明', '管理员查看网络组件日志；不自动重启或重交密钥'));
+            };
+            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 aborted = () => finish(new Error('DISPOSED'));
+                const earlyExit = () => finish(new Error('HELPER_EXITED'));
+                const errored = () => finish(new Error('HELPER_START_FAILED'));
+                const read = (chunk) => {
+                    data = Buffer.concat([data, chunk]);
+                    if (data.length > settings.controlResponseMaxBytes) {
+                        finish(new Error('CONTROL_RESPONSE_LIMIT'));
+                        return;
+                    }
+                    const nl = data.indexOf(10);
+                    if (nl < 0)
+                        return;
+                    try {
+                        const frame = JSON.parse(data.subarray(0, nl).toString());
+                        if (frame.apiVersion !== 1)
+                            throw new Error();
+                        if (frame.event === 'error') {
+                            const e = frame.error;
+                            if (!e || !['code', 'message', 'needs', 'actor'].every(k => typeof e[k] === 'string' && e[k]))
+                                throw new Error();
+                            startupReceipt = receiptFrame(frame.receipt);
+                            startupNeed = { code: e.code, message: e.message, needs: e.needs, actor: e.actor, cause: null };
+                            finish(new Error('HELPER_START_FAILED'));
+                            return;
+                        }
+                        if (frame.event !== 'ready')
+                            throw new Error();
+                        if (!alive()) {
+                            finish(new Error('HELPER_EXITED'));
+                            return;
+                        }
+                        finish();
+                    }
+                    catch {
+                        finish(new Error('CONTROL_PROTOCOL_INVALID'));
+                    }
+                };
+                const finish = (error) => { if (settled)
+                    return; settled = true; handshakeComplete = true; clearTimeout(timer); lifetime.signal.removeEventListener('abort', aborted); processChild.off('error', errored); processChild.off('close', earlyExit); processChild.stdout.off('data', read); if (error)
+                    reject(error);
+                else
+                    resolve(); };
+                processChild.once('error', errored);
+                processChild.once('close', earlyExit);
+                processChild.stdout.on('data', read);
+                lifetime.signal.addEventListener('abort', aborted, { once: true });
+            });
+            try {
+                await ready;
+            }
+            finally {
+                await logClosed;
+            }
+            processChild.stdout.resume();
+            if (!disposed)
+                await observe();
+        }
+        catch (error) {
+            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完整性和私有日志'));
+            const forced = await stopOwned();
+            if (forced && terminalNeed)
+                terminalNeed.cause = '自有helper未在shutdownObservationSeconds内退出，已SIGKILL清理';
+        }
+    })();
+    const api = {
+        start, getState: snapshot,
+        onState(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+        async connect(target, signal) {
+            await start();
+            if (disposed || signal.aborted)
+                return fail('DISPOSED', '网络操作已取消', '重新发起连接');
+            if (cfg && (target.host !== cfg.host.name || target.username !== cfg.host.employee || target.port !== cfg.host.sshPort || target.knownHostsFile !== cfg.host.knownHostsFile))
+                return fail('ENROLLMENT_MISMATCH', '开通目标与网络配置不一致', '管理员重新装配同一开通上下文');
+            if (state.phase === 'starting')
+                await new Promise(resolve => { const done = () => { if (state.phase === 'starting' && !signal.aborted && !disposed)
+                    return; updates.delete(done); signal.removeEventListener('abort', done); resolve(); }; updates.add(done); signal.addEventListener('abort', done, { once: true }); done(); });
+            if (signal.aborted || disposed)
+                return fail('DISPOSED', '网络操作已取消', '重新发起连接');
+            if (state.phase !== 'online' || !alive())
+                return { ok: false, error: state.error ?? needs('NETWORK_NOT_READY', '远程主机：未连接', '等待网络在线') };
+            return ok({ proxyCommand: [executable.path, 'ssh-proxy', '--runtime-dir', cfg.runtimeDir].map(quote).join(' ') + ' %h %p' });
+        },
+        async openLoginProxy(signal) {
+            await start();
+            if (disposed || signal.aborted)
+                return fail('DISPOSED', '登录代理已取消', '重新发起登录');
+            if (state.phase !== 'online' || !alive())
+                return { ok: false, error: state.error ?? needs('NETWORK_NOT_READY', '远程主机：未连接', '等待网络在线') };
+            const owner = new AbortController();
+            const cancel = () => owner.abort();
+            signal.addEventListener('abort', cancel, { once: true });
+            lifetime.signal.addEventListener('abort', cancel, { once: true });
+            childGone.signal.addEventListener('abort', cancel, { once: true });
+            let lease, diagnostic;
+            try {
+                const res = await request('POST', '/v1/login-proxy', owner.signal);
+                if (res.statusCode !== 201) {
+                    const value = await jsonResponse(res, settings.controlResponseMaxBytes);
+                    if (value?.apiVersion === 1 && value.error && ['code', 'message', 'needs', 'actor'].every(k => typeof value.error[k] === 'string'))
+                        diagnostic = { code: value.error.code, message: value.error.message, needs: value.error.needs, actor: value.error.actor, cause: typeof value.error.cause === 'string' ? value.error.cause : null };
+                    throw new Error('PROXY_UNAVAILABLE');
+                }
+                if (res.headers['content-type'] !== 'application/x-ndjson' || res.headers['cache-control'] !== 'no-store') {
+                    res.destroy();
+                    throw new Error('CONTROL_PROTOCOL_INVALID');
+                }
+                const frame = await firstFrame(res, settings.controlResponseMaxBytes);
+                const url = new URL(frame.url);
+                if (frame.apiVersion !== 1 || url.protocol !== 'http:' || url.hostname !== '127.0.0.1' || url.username || url.password || !['id', 'username', 'password'].every(k => typeof frame[k] === 'string' && frame[k]))
+                    throw new Error('CONTROL_PROTOCOL_INVALID');
+                const credentials = { apiVersion: 1, id: frame.id, url: url.origin, username: frame.username, password: frame.password };
+                let released = false;
+                lease = { credentials, async release() { if (released)
+                        return; released = true; owner.abort(); res.destroy(); signal.removeEventListener('abort', cancel); lifetime.signal.removeEventListener('abort', cancel); childGone.signal.removeEventListener('abort', cancel); leases.delete(lease); credentials.username = ''; credentials.password = ''; } };
+                const current = lease;
+                owner.signal.addEventListener('abort', () => void current.release(), { once: true });
+                res.on('error', () => void current.release());
+                res.on('close', () => void current.release());
+                leases.add(current);
+                if (owner.signal.aborted)
+                    await current.release();
+                if (owner.signal.aborted)
+                    return fail('DISPOSED', '登录代理已取消', '重新发起登录');
+                return ok(current);
+            }
+            catch {
+                owner.abort();
+                signal.removeEventListener('abort', cancel);
+                lifetime.signal.removeEventListener('abort', cancel);
+                childGone.signal.removeEventListener('abort', cancel);
+                return diagnostic ? { ok: false, error: diagnostic } : fail('PROXY_UNAVAILABLE', '登录代理未能建立，根因未查明', '查看主机网络与信任材料');
+            }
+        },
+        async download(source, signal) { const lease = await api.openLoginProxy(signal); if (!lease.ok)
+            return lease; return downloadThroughProxy(source, lease.value, signal, settings.downloadMaxRedirects, cfg.dialTimeoutSeconds, cfg.httpMaxResponseHeaderBytes); },
+        dispose() {
+            return disposing ??= (async () => {
+                disposed = true;
+                lifetime.abort();
+                if (poll)
+                    clearTimeout(poll);
+                for (const update of updates)
+                    update();
+                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' });
+                listeners.clear();
+                updates.clear();
+            })();
+        },
+    };
+    return api;
+}

package/lib/packaged-helper.d.ts

@@ -0,0 +1,3 @@
+import type { Result } from './api.ts';
+import type { Executable } from './network.ts';
+export declare function resolvePackagedHelper(moduleURL: string, platform?: string, arch?: string): Result<Executable>;

package/lib/packaged-helper.js

@@ -0,0 +1,25 @@
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fail, ok } from "./api.js";
+export function resolvePackagedHelper(moduleURL, platform = process.platform, arch = process.arch) {
+    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'));
+        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 });
+    }
+    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) } };
+    }
+}

package/lib/private.d.ts

@@ -0,0 +1,3 @@
+export declare function privateFile(path: string, write?: boolean): Promise<import("fs/promises").FileHandle>;
+export declare function privateSocket(path: string): Promise<void>;
+export declare function verifyExecutable(path: string, sha256: string): Promise<void>;

package/lib/private.js

@@ -0,0 +1,47 @@
+import { constants } from 'node:fs';
+import { open, lstat } from 'node:fs/promises';
+import { isAbsolute, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+export async function privateFile(path, write = false) {
+    if (!isAbsolute(path))
+        throw new Error('LOCAL_PATH_INVALID');
+    await privateDirectory(dirname(path));
+    const f = await open(path, (write ? constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND : constants.O_RDONLY) | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o600);
+    try {
+        const st = await f.stat();
+        if (!st.isFile() || st.uid !== process.getuid() || (st.mode & 0o777) !== 0o600)
+            throw new Error('LOCAL_PERMISSION_DENIED');
+        return f;
+    }
+    catch (e) {
+        await f.close();
+        throw e;
+    }
+}
+export async function privateSocket(path) {
+    await privateDirectory(dirname(path));
+    const st = await lstat(path);
+    if (!st.isSocket() || st.uid !== process.getuid() || (st.mode & 0o777) !== 0o600)
+        throw new Error('LOCAL_PERMISSION_DENIED');
+}
+async function privateDirectory(path) {
+    const st = await lstat(path);
+    if (!st.isDirectory() || st.uid !== process.getuid() || (st.mode & 0o777) !== 0o700)
+        throw new Error('LOCAL_PERMISSION_DENIED');
+}
+export async function verifyExecutable(path, sha256) {
+    const f = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const st = await f.stat();
+        if (!st.isFile() || (st.mode & 0o022) !== 0 || (st.mode & 0o100) === 0 || !/^[a-f0-9]{64}$/.test(sha256))
+            throw new Error('HELPER_INTEGRITY_INVALID');
+        const hash = createHash('sha256');
+        for await (const chunk of f.createReadStream({ autoClose: false }))
+            hash.update(chunk);
+        if (hash.digest('hex') !== sha256)
+            throw new Error('HELPER_INTEGRITY_INVALID');
+    }
+    finally {
+        await f.close();
+    }
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Remote Host Network",
+    "description": "Provides remote host connectivity and device identity."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "远程主机网络",
+    "description": "提供远程主机网络连接与设备身份。"
+  }
+}

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@ai-workbench/network",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.1",
+  "type": "module",
+  "engines": {
+    "node": ">=24.13.1"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./api": {
+      "types": "./lib/api.d.ts",
+      "default": "./lib/api.js"
+    },
+    "./cordis": {
+      "types": "./lib/cordis.d.ts",
+      "default": "./lib/cordis.js"
+    },
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "files": [
+    "lib",
+    "NOTICE.md",
+    "cordis.patch.yml",
+    "locale"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.ts",
+    "check": "tsc --noEmit",
+    "build": "node scripts/build-platforms.mjs && tsc"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/schemastery": "3.18.4"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/schemastery": "3.18.4",
+    "@types/node": "24.0.0",
+    "typescript": "5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "dsh",
+    "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"
+  }
+}