@fa-software/semi2-dsh 0.0.10-preview.20260920042705

package/lib/types/web/welcome-ack.d.ts

@@ -0,0 +1,33 @@
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * dsh-client-ui-settings-models 中 bundle 私有常量的镜像（比 notice 文案高一层）：升级 pinned dsh channel
+ * （DSH_VERSION）时须核对该串仍等于客户端 bundle 里的值，回归测试钉住它；陈旧值只退化为原生行为。
+ */
+export declare const WELCOME_NOTICE_VERSION = "2026-08-13.1";
+/** 产品级 GUI onboarding 事实的 durable settings 命名空间。 */
+export declare const WELCOME_NOTICE_NAMESPACE = "ui-onboarding";
+/** 记录已确认的欢迎声明文案版本。 */
+export declare const WELCOME_NOTICE_ACK_FIELD = "welcomeNoticeVersion";
+/** 本模块依赖的最小 host settings 服务面。 */
+export interface SettingsLike {
+    describe(): Array<{
+        ns: string;
+    }>;
+    update(ns: string, patch: object): Promise<void>;
+}
+export interface SeedOptions {
+    /** 该命名空间被注册即视为 settings 服务就绪。 */
+    namespace?: string;
+    /** 两次就绪探测之间的间隔（ms）。 */
+    intervalMs?: number;
+    /** 放弃前的最多探测次数（默认 50ms × 40 ≈ 2s）。 */
+    attempts?: number;
+    /** 替换轮询等待的测试接缝。 */
+    wait?: (ms: number) => Promise<void>;
+}
+export declare const SEED_INTERVAL_MS = 50;
+export declare const SEED_ATTEMPTS = 40;
+/** 等 "ui-onboarding" 注册后并入当前版本号（幂等）；拒绝/失败会 reject 交调用方降级，命名空间始终未就绪返回 false。 */
+export declare function seedWelcomeAcknowledgement(settings: SettingsLike, options?: SeedOptions): Promise<boolean>;
+/** 在可选 `settings` 服务上 best-effort 预置：只降级。 */
+export declare function installWelcomeAck(ctx: Context): void;

package/lib/web/index.js

@@ -0,0 +1,38 @@
+import { installLoginRoute } from './login.js';
+import { installLoopbackBridge } from './loopback-bridge.js';
+import { installPreviewProxy } from './preview-proxy.js';
+import { createWorkstationRuntime } from './runtime.js';
+import { installWelcomeAck } from './welcome-ack.js';
+function warn(ctx, message) {
+    try {
+        ctx.logger('semi2-web').warn(message);
+    }
+    catch {
+        // 无 logger 的宿主（单测）忽略。
+    }
+}
+function reason(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function installWebSurface(ctx) {
+    ctx.inject(['webServer'], (workstationCtx) => {
+        // 与预览面无关的 web 面预置先装：工作区运行时不可用也不该连带跳过。
+        installWelcomeAck(workstationCtx);
+        let runtime;
+        try {
+            const webServer = workstationCtx.get('webServer');
+            runtime = createWorkstationRuntime(webServer.port);
+        }
+        catch (error) {
+            warn(workstationCtx, `工作站运行时不可用，跳过预览面：${reason(error)}`);
+            return;
+        }
+        installLoopbackBridge(workstationCtx);
+        installLoginRoute(workstationCtx);
+        workstationCtx.inject(['webRuntime', 'connection'], (webCtx) => {
+            void installPreviewProxy(webCtx, runtime).catch((error) => {
+                warn(webCtx, `预览反代启动失败：${reason(error)}`);
+            });
+        });
+    });
+}

package/lib/web/login.js

@@ -0,0 +1,79 @@
+const LOGIN_PATH = '/semi2/login';
+const LOGOUT_PATH = '/semi2/logout';
+const MAX_BODY = 8 * 1024;
+function send(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'cache-control': 'no-store',
+        'content-length': Buffer.byteLength(payload),
+    });
+    res.end(payload);
+}
+async function readJson(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buffer = chunk instanceof Uint8Array ? chunk : Buffer.from(chunk);
+        size += buffer.byteLength;
+        if (size > MAX_BODY)
+            throw new Error('BODY_TOO_LARGE');
+        chunks.push(buffer);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+function text(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+export function installLoginRoute(ctx) {
+    const webServer = ctx.get('webServer');
+    const config = ctx.get('semi2Config');
+    if (webServer === undefined || config === undefined)
+        return;
+    ctx.effect(() => webServer.register({
+        kind: 'exact',
+        path: LOGIN_PATH,
+        handler: async (req, res) => {
+            if (req.method !== 'POST') {
+                send(res, 405, { code: 'METHOD_NOT_ALLOWED' });
+                return;
+            }
+            try {
+                const raw = await readJson(req);
+                const body = raw !== null && typeof raw === 'object'
+                    ? raw
+                    : {};
+                const url = text(body.url);
+                const username = text(body.username);
+                const password = typeof body.password === 'string' ? body.password : '';
+                if (url === '' || username === '' || password === '')
+                    throw Object.assign(new Error('INVALID_INPUT'), { code: 'INVALID_INPUT' });
+                const result = await config.login({ url, username, password });
+                send(res, 200, { ok: true, userName: result.userName });
+            }
+            catch (error) {
+                const code = error !== null && typeof error === 'object' && 'code' in error
+                    ? String(error.code)
+                    : 'LOGIN_FAILED';
+                send(res, code === 'INVALID_INPUT' ? 400 : 401, { code });
+            }
+        },
+    }));
+    ctx.effect(() => webServer.register({
+        kind: 'exact',
+        path: LOGOUT_PATH,
+        handler: async (req, res) => {
+            if (req.method !== 'POST') {
+                send(res, 405, { code: 'METHOD_NOT_ALLOWED' });
+                return;
+            }
+            try {
+                await config.logout();
+                send(res, 200, { ok: true });
+            }
+            catch {
+                send(res, 400, { code: 'LOGOUT_FAILED' });
+            }
+        },
+    }));
+}

package/lib/web/loopback-bridge.js

@@ -0,0 +1,12 @@
+/**
+ * dsh-client-connection 优先看 __DSH_TRANSPORT__：ownsHost:true 即「页面骑在拥有 host 会话的传输上」（由
+ * dsh-host-webserver 渲染进 <head> 最前），浏览器端 settings scope 因此 durable；fetch/openStream 故意留空。
+ */
+export function loopbackTransportRow() {
+    return { kind: 'global', name: '__DSH_TRANSPORT__', value: { ownsHost: true } };
+}
+export function installLoopbackBridge(ctx) {
+    ctx.effect(() => ctx.on('webserver/index-inject', (table) => {
+        table.push(loopbackTransportRow());
+    }));
+}

package/lib/web/preview-proxy.js

@@ -0,0 +1,201 @@
+import { appendFileSync } from 'node:fs';
+import { createServer, request as httpRequest } from 'node:http';
+/**
+ * 现场诊断用请求 trace：SEMI2_PREVIEW_DEBUG=1 时写 /tmp/semi2-preview-proxy.log。CNB 预览网关夹在
+ * 浏览器与本代理之间，它转发的请求形状在容器外不可观测，只有这份 trace 能看到。
+ */
+const debugLog = process.env.SEMI2_PREVIEW_DEBUG === '1'
+    ? (line) => {
+        try {
+            appendFileSync('/tmp/semi2-preview-proxy.log', `${new Date().toISOString()} ${line}\n`);
+        }
+        catch {
+            // 仅诊断用：日志失败不得影响服务。
+        }
+    }
+    : undefined;
+/** 代理面向浏览器/CNB 的连接保持的空闲窗口（ms）。 */
+export const KEEP_ALIVE_TIMEOUT_MS = 72_000;
+/**
+ * 把信任边界头改写成固定的环回上游 authority：dsh 的 /api 信任栅栏只接受环回 Host 或预声明 authority，
+ * 且会话 cookie 绑定请求 Host（CNB 边缘的 authority 拼写会漂）；Origin 一并归一为同源、sec-fetch-site 钉 same-origin。
+ */
+export function rewriteHeaders(headers, upstreamHost) {
+    const output = { ...headers, host: upstreamHost };
+    if (typeof output.origin === 'string') {
+        try {
+            output.origin = `${new URL(output.origin).protocol}//${upstreamHost}`;
+        }
+        catch {
+            output.origin = `http://${upstreamHost}`;
+        }
+    }
+    if (output['sec-fetch-site'] !== undefined)
+        output['sec-fetch-site'] = 'same-origin';
+    return output;
+}
+/**
+ * 干净 `GET /` 不带有效 cookie 会被 dsh 弹 401（cookie 只在 `?token=` 交换时签发），故代理代用户把裸 `/`
+ * 转发成 `/?token=…`（token 不出服务端）；已持 cookie 的后续请求绝不能再重放（否则 303 打转），非 index 原样转发。
+ */
+export function indexProxyPath(requestUrl, authenticatedIndexUrl, shouldReplay) {
+    if (!shouldReplay)
+        return requestUrl;
+    let url;
+    try {
+        url = new URL(requestUrl, 'http://dsh.invalid');
+    }
+    catch {
+        return requestUrl;
+    }
+    if (url.pathname !== '/' || url.search !== '' || url.hash !== '')
+        return requestUrl;
+    const magic = new URL(authenticatedIndexUrl);
+    return `${magic.pathname}${magic.search}`;
+}
+/** 安装入口：`ws` 惰性加载——headless 面永不执行到这里，也就永不加载 ws。 */
+export async function installPreviewProxy(ctx, runtime) {
+    const { WebSocket, WebSocketServer } = await import('ws');
+    const connection = ctx.get('connection');
+    const upstreamHost = `127.0.0.1:${runtime.dshPort}`;
+    const authenticatedIndexUrl = connection.authenticatedUrl(`http://${upstreamHost}/`);
+    /**
+     * 代理自持（单租户）会话：CNB 预览边缘服务端跟随重定向却不保留上游 Set-Cookie，签发的 cookie 回不到浏览器，
+     * 边缘会在 token 交换 303 上打转——故由代理注入 cookie、吸收 303、对客户端返回最终文档（对外等同 dsh 原行为）。
+     */
+    const session = {};
+    const requestHasBody = (method) => method === 'POST' || method === 'PUT' || method === 'PATCH';
+    const proxy = createServer((request, response) => {
+        const requestPath = request.url ?? '/';
+        const respond = (attempt, path) => {
+            const rewritten = rewriteHeaders(request.headers, upstreamHost);
+            if (session.cookie !== undefined)
+                rewritten.cookie = session.cookie;
+            debugLog?.(`http ${request.method} ${path} host=${String(request.headers.host)} session=${session.cookie !== undefined ? 'yes' : 'no'} attempt=${attempt}`);
+            const upstream = httpRequest({
+                hostname: '127.0.0.1',
+                port: runtime.dshPort,
+                path,
+                method: request.method,
+                headers: rewritten,
+            }, (upstreamResponse) => {
+                const status = upstreamResponse.statusCode ?? 502;
+                const setCookie = (upstreamResponse.headers['set-cookie'] ?? []).map(c => c.split(';')[0]).join('; ');
+                debugLog?.(`http ← ${status} ${path} set-cookie=${(upstreamResponse.headers['set-cookie'] ?? []).length}`);
+                // 吸收 token 交换 303：采用新 cookie 并用最终文档答同一请求（请求体无法重放，故仅限无体请求）。
+                if (status === 303 && setCookie !== '' && attempt < 2 && !requestHasBody(request.method)) {
+                    session.cookie = session.cookie === undefined ? setCookie : `${session.cookie}; ${setCookie}`;
+                    upstreamResponse.resume();
+                    respond(attempt + 1, requestPath);
+                    return;
+                }
+                // 会话过期：丢弃并重做一次 token 交换。
+                if (status === 401 && attempt < 2 && !requestHasBody(request.method)) {
+                    session.cookie = undefined;
+                    upstreamResponse.resume();
+                    respond(attempt + 1, indexProxyPath(requestPath, authenticatedIndexUrl, true));
+                    return;
+                }
+                response.writeHead(status, upstreamResponse.headers);
+                upstreamResponse.pipe(response);
+            });
+            upstream.on('error', (error) => {
+                debugLog?.(`http !! upstream error ${request.url}: ${error.message}`);
+                if (!response.headersSent) {
+                    response.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' });
+                    response.end(`semi2 preview upstream error: ${error.message}`);
+                }
+            });
+            request.pipe(upstream);
+        };
+        respond(0, indexProxyPath(requestPath, authenticatedIndexUrl, session.cookie === undefined));
+    });
+    /** 经 token 交换铸造会话 cookie（WS 升级前用）。 */
+    const ensureSession = () => new Promise((resolve) => {
+        if (session.cookie !== undefined) {
+            resolve();
+            return;
+        }
+        const magic = new URL(authenticatedIndexUrl);
+        const exchange = httpRequest({
+            hostname: '127.0.0.1',
+            port: runtime.dshPort,
+            path: `${magic.pathname}${magic.search}`,
+            method: 'GET',
+            headers: { host: upstreamHost },
+        }, (res) => {
+            const setCookie = (res.headers['set-cookie'] ?? []).map(c => c.split(';')[0]).join('; ');
+            if (setCookie !== '')
+                session.cookie = setCookie;
+            debugLog?.(`session mint ← ${res.statusCode} set-cookie=${(res.headers['set-cookie'] ?? []).length}`);
+            res.resume();
+            resolve();
+        });
+        exchange.on('error', () => { resolve(); });
+        exchange.end();
+    });
+    const sockets = new WebSocketServer({ noServer: true, maxPayload: 256 * 1024 * 1024 });
+    proxy.on('upgrade', (request, socket, head) => {
+        debugLog?.(`ws upgrade ${request.url} host=${String(request.headers.host)}`);
+        void ensureSession().then(() => {
+            const headers = rewriteHeaders(request.headers, upstreamHost);
+            if (session.cookie !== undefined)
+                headers.cookie = session.cookie;
+            const upstream = new WebSocket(`ws://${upstreamHost}${request.url ?? '/'}`, {
+                headers,
+                perMessageDeflate: false,
+            });
+            const timer = setTimeout(() => {
+                upstream.terminate();
+                socket.destroy();
+            }, 10_000);
+            upstream.once('open', () => {
+                debugLog?.(`ws open ${request.url}`);
+                clearTimeout(timer);
+                sockets.handleUpgrade(request, socket, head, (client) => {
+                    const pingDown = setInterval(() => {
+                        if (client.readyState === WebSocket.OPEN)
+                            client.ping();
+                    }, runtime.pingIntervalMs);
+                    const pingUp = setInterval(() => {
+                        if (upstream.readyState === WebSocket.OPEN)
+                            upstream.ping();
+                    }, runtime.pingIntervalMs);
+                    const close = () => {
+                        clearInterval(pingDown);
+                        clearInterval(pingUp);
+                        client.terminate();
+                        upstream.terminate();
+                    };
+                    client.on('message', (data, binary) => {
+                        if (upstream.readyState === WebSocket.OPEN)
+                            upstream.send(data, { binary });
+                    });
+                    upstream.on('message', (data, binary) => {
+                        if (client.readyState === WebSocket.OPEN)
+                            client.send(data, { binary });
+                    });
+                    client.once('close', close);
+                    upstream.once('close', close);
+                    client.once('error', close);
+                    upstream.once('error', close);
+                });
+            });
+            upstream.once('error', () => {
+                clearTimeout(timer);
+                socket.destroy();
+            });
+        });
+    });
+    // Node 默认 5s keep-alive 会在 CNB 反代的复用窗口之前关掉空闲连接，复用半关 socket 会回 RST
+    // （浏览器报 ERR_CONNECTION_RESET）；keepAliveTimeout 必须高于下游复用窗口，headersTimeout 再高 3s。
+    proxy.keepAliveTimeout = KEEP_ALIVE_TIMEOUT_MS;
+    proxy.headersTimeout = KEEP_ALIVE_TIMEOUT_MS + 3_000;
+    proxy.listen(runtime.previewPort, '0.0.0.0');
+    ctx.effect(() => () => {
+        for (const client of sockets.clients)
+            client.terminate();
+        sockets.close();
+        proxy.close();
+    });
+}

package/lib/web/runtime.js

@@ -0,0 +1,19 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+/** 预览反代监听端口（CNB 预览网关与 WebIDE 侧栏都按 8788 约定）。 */
+const PREVIEW_PORT = 8788;
+/** WebSocket 保活间隔。 */
+const PING_INTERVAL_MS = 5_000;
+/** cwd 对齐 /workspace 并同步 HOME（dsh 新会话默认目录取 homedir）；dshPort 取官方 webServer 监听端口。 */
+export function createWorkstationRuntime(dshPort) {
+    const hasWorkspace = existsSync('/workspace');
+    const cwd = resolve(hasWorkspace ? '/workspace' : process.cwd());
+    if (hasWorkspace)
+        process.env.HOME = cwd;
+    return {
+        cwd,
+        dshPort,
+        previewPort: PREVIEW_PORT,
+        pingIntervalMs: PING_INTERVAL_MS,
+    };
+}

package/lib/web/welcome-ack.js

@@ -0,0 +1,51 @@
+/**
+ * dsh-client-ui-settings-models 中 bundle 私有常量的镜像（比 notice 文案高一层）：升级 pinned dsh channel
+ * （DSH_VERSION）时须核对该串仍等于客户端 bundle 里的值，回归测试钉住它；陈旧值只退化为原生行为。
+ */
+export const WELCOME_NOTICE_VERSION = '2026-08-13.1';
+/** 产品级 GUI onboarding 事实的 durable settings 命名空间。 */
+export const WELCOME_NOTICE_NAMESPACE = 'ui-onboarding';
+/** 记录已确认的欢迎声明文案版本。 */
+export const WELCOME_NOTICE_ACK_FIELD = 'welcomeNoticeVersion';
+export const SEED_INTERVAL_MS = 50;
+export const SEED_ATTEMPTS = 40;
+function defaultWait(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/** 等 "ui-onboarding" 注册后并入当前版本号（幂等）；拒绝/失败会 reject 交调用方降级，命名空间始终未就绪返回 false。 */
+export async function seedWelcomeAcknowledgement(settings, options = {}) {
+    const namespace = options.namespace ?? WELCOME_NOTICE_NAMESPACE;
+    const intervalMs = options.intervalMs ?? SEED_INTERVAL_MS;
+    const attempts = options.attempts ?? SEED_ATTEMPTS;
+    const wait = options.wait ?? defaultWait;
+    const patch = { [WELCOME_NOTICE_ACK_FIELD]: WELCOME_NOTICE_VERSION };
+    for (let remaining = attempts;; remaining -= 1) {
+        if (settings.describe().some(({ ns }) => ns === namespace)) {
+            await settings.update(namespace, patch);
+            return true;
+        }
+        if (remaining <= 0)
+            return false;
+        await wait(intervalMs);
+    }
+}
+function warn(ctx, message) {
+    try {
+        ctx.logger('semi2-welcome-ack').warn(message);
+    }
+    catch { }
+}
+/** 在可选 `settings` 服务上 best-effort 预置：只降级。 */
+export function installWelcomeAck(ctx) {
+    ctx.inject(['settings'], (settingsCtx) => {
+        const settings = settingsCtx.get('settings');
+        if (settings === undefined)
+            return;
+        void seedWelcomeAcknowledgement(settings).then((seeded) => {
+            if (!seeded)
+                warn(ctx, 'ui-onboarding 命名空间未就绪，跳过欢迎声明预置');
+        }).catch((error) => {
+            warn(ctx, '写入 ui-onboarding 欢迎声明确认失败: ' + (error instanceof Error ? error.message : String(error)));
+        });
+    });
+}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@fa-software/semi2-dsh",
+  "version": "0.0.10-preview.20260920042705",
+  "type": "module",
+  "description": "Semi2 单插件：semi2-hub 配置引导 + codegraph 结构索引 + 公共 Web 能力。",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": "./lib/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-api-remotes"
+      ]
+    }
+  },
+  "dependencies": {
+    "@colbymchenry/codegraph": "1.6.0",
+    "ws": "^8.21.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-credentials": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-skill": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.6-alpha.2",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-credentials": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-host-webserver": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-util-values": "^0.1.6-alpha.2",
+    "@graphql-codegen/cli": "7.4.0",
+    "@graphql-codegen/typescript": "6.1.0",
+    "@graphql-codegen/typescript-operations": "6.1.6",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.0.0",
+    "@types/ws": "^8.18.1",
+    "graphql": "^16.11.0",
+    "react": "^19.2.0",
+    "tsdown": "^0.22.2",
+    "typescript": "~5.8.3"
+  },
+  "scripts": {
+    "build": "rm -rf lib && graphql-codegen -c codegen.ts && tsc -p tsconfig.json && tsdown -c tsdown.config.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run build && node --test test/*.test.mjs",
+    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput",
+    "dev:client": "tsdown -c tsdown.config.ts --watch"
+  }
+}