@jingyi0605/codingns4dsh 0.1.0

package/data/build/dist/host/cli-adapters/standard-stream-driver.js

@@ -0,0 +1,205 @@
+import { spawn, spawnSync } from 'node:child_process';
+import readline from 'node:readline';
+import { firstToolText, isToolRecord, normalizeToolStatus, serializeToolValue } from './tool-observation.js';
+import { usageChunk } from './rpc-driver-utils.js';
+import { terminateChildProcess } from './process-utils.js';
+const WINDOWS = process.platform === 'win32';
+/**
+ * 把采用 JSONL/stream-json 的 CLI 统一成 Codingns4DSH 的最小驱动契约。
+ * 子类只需提供命令参数和事件映射，进程终止、stderr 消费及清理由这里统一处理。
+ */
+export class StandardStreamDriver {
+    descriptor;
+    binaries;
+    runSpawnSync;
+    runSpawn;
+    versionArgs;
+    modelArgs;
+    cachedBinary = null;
+    processes = new Set();
+    constructor(descriptor, defaults, options = {}) {
+        this.descriptor = descriptor;
+        this.binaries = options.binaries ?? defaults.binaries;
+        this.versionArgs = options.versionArgs ?? defaults.versionArgs ?? ['--version'];
+        this.modelArgs = options.modelArgs ?? defaults.modelArgs ?? ['--help'];
+        this.runSpawnSync = options.spawnSync ?? spawnSync;
+        this.runSpawn = options.spawn ?? spawn;
+    }
+    async detect() {
+        for (const command of this.binaries) {
+            try {
+                const result = this.runSpawnSync(command, this.versionArgs, { encoding: 'utf8', timeout: 5_000, windowsHide: true, shell: WINDOWS });
+                const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`;
+                const version = this.parseVersion(output);
+                if (result.status === 0 && version !== null) {
+                    this.cachedBinary = command;
+                    return { installed: true, version, command };
+                }
+            }
+            catch {
+                // 候选命令不存在时继续尝试下一个名称。
+            }
+        }
+        return { installed: false, version: null, command: null };
+    }
+    async listModels() {
+        const command = this.cachedBinary ?? (await this.detect()).command;
+        if (command === null)
+            return emptyCatalog();
+        try {
+            const result = this.runSpawnSync(command, this.modelArgs, { encoding: 'utf8', timeout: 12_000, windowsHide: true, shell: WINDOWS });
+            if (result.status !== 0)
+                return emptyCatalog();
+            return this.parseModels(`${result.stdout ?? ''}\n${result.stderr ?? ''}`);
+        }
+        catch {
+            return emptyCatalog();
+        }
+    }
+    async *executeTurn(input) {
+        const command = this.cachedBinary ?? (await this.detect()).command;
+        if (command === null)
+            throw new Error(`${this.descriptor.name} 未安装`);
+        const child = this.runSpawn(command, this.buildArgs(input), {
+            cwd: input.cwd ?? process.cwd(), env: { ...process.env }, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, shell: WINDOWS,
+        });
+        this.processes.add(child);
+        let emittedFinish = false;
+        let emittedBinding = input.providerSessionId !== undefined;
+        const onAbort = () => { terminateChildProcess(child); };
+        input.signal?.addEventListener('abort', onAbort, { once: true });
+        if (input.signal?.aborted)
+            onAbort();
+        child.stderr.on('data', () => undefined);
+        try {
+            const lines = readline.createInterface({ input: child.stdout });
+            try {
+                for await (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    const parsed = parseJson(line);
+                    if (parsed === null)
+                        continue;
+                    if (!emittedBinding) {
+                        const providerSessionId = typeof parsed.session_id === 'string'
+                            ? parsed.session_id
+                            : typeof parsed.sessionId === 'string'
+                                ? parsed.sessionId
+                                : null;
+                        if (providerSessionId !== null && providerSessionId.trim() !== '') {
+                            emittedBinding = true;
+                            yield { type: 'session-binding', providerSessionId: providerSessionId.trim() };
+                        }
+                    }
+                    for (const chunk of this.parseEvent(parsed, input)) {
+                        if (chunk.type === 'finish')
+                            emittedFinish = true;
+                        yield chunk;
+                    }
+                }
+            }
+            finally {
+                lines.close();
+            }
+            if (!emittedFinish) {
+                if (input.signal?.aborted)
+                    yield { type: 'finish', reason: 'cancel' };
+                else
+                    throw new Error(`${this.descriptor.name} 执行失败`);
+            }
+        }
+        finally {
+            input.signal?.removeEventListener('abort', onAbort);
+            this.processes.delete(child);
+            terminateChildProcess(child);
+        }
+    }
+    dispose() {
+        for (const child of this.processes)
+            terminateChildProcess(child);
+        this.processes.clear();
+        this.cachedBinary = null;
+    }
+    parseVersion(output) { return output.match(/\b\d+\.\d+(?:\.\d+)?(?:[-+][0-9A-Za-z.-]+)?\b/u)?.[0] ?? null; }
+    parseEvent(value, input) {
+        return genericEventChunks(value, input.signal?.aborted ?? false);
+    }
+    parseModels(output) { return parseHelpModels(output); }
+}
+export function emptyCatalog() { return { groups: [], currentModel: null, currentEffort: null }; }
+function parseJson(line) { try {
+    const value = JSON.parse(line);
+    return isRecord(value) ? value : null;
+}
+catch {
+    return null;
+} }
+function isRecord(value) { return typeof value === 'object' && value !== null && !Array.isArray(value); }
+function genericEventChunks(value, cancelled) {
+    const chunks = [];
+    const type = typeof value.type === 'string' ? value.type.toLowerCase() : '';
+    const event = isRecord(value.event) ? value.event : value;
+    const eventType = typeof event.type === 'string' ? event.type.toLowerCase() : type;
+    if (eventType.includes('think') || eventType.includes('reason')) {
+        const delta = isRecord(event.delta) ? event.delta : event;
+        const reasoning = typeof event.delta === 'string' ? event.delta : typeof delta.text === 'string' ? delta.text : typeof delta.content === 'string' ? delta.content : null;
+        if (reasoning)
+            chunks.push({ type: 'reasoning-delta', text: reasoning });
+    }
+    else {
+        const delta = isRecord(event.delta) ? event.delta : event;
+        const text = typeof event.delta === 'string' ? event.delta : typeof delta.text === 'string' ? delta.text : typeof delta.content === 'string' ? delta.content : null;
+        if (text !== null && text.length > 0 && !['result', 'final', 'error'].includes(eventType))
+            chunks.push({ type: 'text-delta', text });
+        const message = isRecord(event.message) ? event.message : null;
+        const messageContent = message === null ? null : typeof message.content === 'string' ? message.content : null;
+        if (messageContent)
+            chunks.push({ type: 'text-delta', text: messageContent });
+    }
+    const nestedTool = isToolRecord(event.tool_call) ? event.tool_call : isToolRecord(event.toolCall) ? event.toolCall : isToolRecord(event.function) ? event.function : event;
+    const toolName = firstToolText(nestedTool.toolName, nestedTool.tool_name, nestedTool.name);
+    const callId = firstToolText(nestedTool.callId, nestedTool.call_id, nestedTool.toolCallId, nestedTool.tool_call_id, nestedTool.toolUseId, nestedTool.tool_use_id, nestedTool.id, event.tool_call_id, event.tool_use_id);
+    if ((toolName || callId) && (eventType.includes('tool') || eventType.includes('function') || eventType.includes('command'))) {
+        const input = serializeToolValue(nestedTool.input ?? nestedTool.arguments ?? nestedTool.args ?? nestedTool.parameters);
+        const output = serializeToolValue(nestedTool.output ?? nestedTool.result);
+        const error = serializeToolValue(nestedTool.error);
+        const fallback = error !== undefined || eventType.includes('error') || eventType.includes('fail')
+            ? 'failed'
+            : output !== undefined || eventType.includes('result') || eventType.includes('complete')
+                ? 'completed'
+                : 'running';
+        chunks.push({
+            type: 'tool-event',
+            toolName: toolName ?? 'tool',
+            status: normalizeToolStatus(nestedTool.status ?? nestedTool.state, fallback),
+            ...(callId ? { callId } : {}),
+            ...(input !== undefined ? { input } : {}),
+            ...(output !== undefined ? { output } : {}),
+            ...(output !== undefined ? { outputMode: eventType.includes('delta') ? 'delta' : 'snapshot' } : {}),
+            ...(error !== undefined ? { error } : {}),
+            ...(firstToolText(nestedTool.agentId, nestedTool.agent_id) ? { agentId: firstToolText(nestedTool.agentId, nestedTool.agent_id) } : {}),
+            ...(serializeToolValue(nestedTool.detail) !== undefined ? { detail: serializeToolValue(nestedTool.detail) } : {}),
+        });
+    }
+    const usage = isRecord(value.usage) ? value.usage : isRecord(event.usage) ? event.usage : null;
+    const usageEvent = usageChunk(usage);
+    if (usageEvent)
+        chunks.push(usageEvent);
+    if (['result', 'turn_end', 'done', 'complete', 'completed', 'final'].includes(eventType) || type === 'result')
+        chunks.push({ type: 'finish', reason: cancelled ? 'cancel' : 'stop' });
+    return chunks;
+}
+function parseHelpModels(output) {
+    const models = [];
+    const seen = new Set();
+    for (const line of output.split(/\r?\n/u)) {
+        const match = line.match(/(?:--model(?:=|\s+)|model(?:s)?\s*:\s*)([A-Za-z0-9][A-Za-z0-9_./:-]{2,})/iu);
+        const id = match?.[1];
+        if (!id || /^(?:model|models|string|value)$/iu.test(id) || seen.has(id))
+            continue;
+        seen.add(id);
+        models.push({ id, name: id, efforts: [] });
+    }
+    return models.length === 0 ? emptyCatalog() : { groups: [{ id: 'default', name: '可用模型', models }], currentModel: null, currentEffort: null };
+}
+//# sourceMappingURL=standard-stream-driver.js.map

package/data/build/dist/host/cli-adapters/stream-normalizer.d.ts

@@ -0,0 +1,25 @@
+import type { CodingNsAgentEvent } from '../../shared/contracts/cli-adapter.js';
+type SnapshotChunk = Extract<CodingNsAgentEvent, {
+    readonly type: 'reasoning-snapshot' | 'text-snapshot';
+}>;
+export type CodingNsNormalizedAgentEvent = Exclude<CodingNsAgentEvent, SnapshotChunk>;
+/**
+ * 把驱动差异收敛成 DSH 可消费的增量流。
+ *
+ * 有些 CLI 发送真正的 delta，有些 CLI 反复发送从头累积的 snapshot。规范化器
+ * 分别记录推理和正文已经发送的内容，避免完整快照被重复追加到 DSH 会话日志。
+ */
+export declare class CodingNsAgentEventNormalizer {
+    private reasoning;
+    private text;
+    private reasoningBoundary;
+    private textBoundary;
+    private usage;
+    push(chunk: CodingNsAgentEvent): readonly CodingNsNormalizedAgentEvent[];
+    /** 流未携带 finish 时仍返回最后一次统计，避免正常结束路径丢失 usage。 */
+    flush(): readonly CodingNsNormalizedAgentEvent[];
+    private appendSnapshot;
+    private takeUsage;
+}
+export {};
+//# sourceMappingURL=stream-normalizer.d.ts.map

package/data/build/dist/host/cli-adapters/stream-normalizer.js

@@ -0,0 +1,83 @@
+/**
+ * 把驱动差异收敛成 DSH 可消费的增量流。
+ *
+ * 有些 CLI 发送真正的 delta，有些 CLI 反复发送从头累积的 snapshot。规范化器
+ * 分别记录推理和正文已经发送的内容，避免完整快照被重复追加到 DSH 会话日志。
+ */
+export class CodingNsAgentEventNormalizer {
+    reasoning = '';
+    text = '';
+    reasoningBoundary = false;
+    textBoundary = false;
+    usage = null;
+    push(chunk) {
+        if (chunk.type === 'reasoning-delta') {
+            this.reasoning = this.reasoningBoundary ? chunk.text : this.reasoning + chunk.text;
+            this.reasoningBoundary = false;
+            return chunk.text === '' ? [] : [chunk];
+        }
+        if (chunk.type === 'text-delta') {
+            this.text = this.textBoundary ? chunk.text : this.text + chunk.text;
+            this.textBoundary = false;
+            return chunk.text === '' ? [] : [chunk];
+        }
+        if (chunk.type === 'reasoning-snapshot')
+            return this.appendSnapshot('reasoning', chunk.text);
+        if (chunk.type === 'text-snapshot')
+            return this.appendSnapshot('text', chunk.text);
+        if (chunk.type === 'usage') {
+            this.usage = chunk;
+            return [];
+        }
+        if (chunk.type === 'tool-event') {
+            this.reasoningBoundary = true;
+            this.textBoundary = true;
+            return [chunk];
+        }
+        if (chunk.type === 'finish') {
+            const usage = this.takeUsage();
+            return usage === null ? [chunk] : [usage, chunk];
+        }
+        return [chunk];
+    }
+    /** 流未携带 finish 时仍返回最后一次统计，避免正常结束路径丢失 usage。 */
+    flush() {
+        const usage = this.takeUsage();
+        return usage === null ? [] : [usage];
+    }
+    appendSnapshot(channel, snapshot) {
+        const previous = channel === 'reasoning' ? this.reasoning : this.text;
+        const boundary = channel === 'reasoning' ? this.reasoningBoundary : this.textBoundary;
+        if (channel === 'reasoning')
+            this.reasoningBoundary = false;
+        else
+            this.textBoundary = false;
+        // 工具前后通常是两条不同的 Assistant 消息。只有新快照不包含旧基线时才
+        // 开启新段；累计快照仍按原基线去重，避免工具事件导致整段重放。
+        if (boundary && !snapshot.startsWith(previous)) {
+            if (channel === 'reasoning')
+                this.reasoning = snapshot;
+            else
+                this.text = snapshot;
+            return snapshot === '' ? [] : [{ type: `${channel}-delta`, text: snapshot }];
+        }
+        if (previous.startsWith(snapshot))
+            return [];
+        const text = snapshot.startsWith(previous)
+            ? snapshot.slice(previous.length)
+            : snapshot.slice(Math.min(previous.length, snapshot.length));
+        if (snapshot.length >= previous.length) {
+            if (channel === 'reasoning')
+                this.reasoning = snapshot;
+            else
+                this.text = snapshot;
+        }
+        return text === '' ? [] : [{ type: `${channel}-delta`, text }];
+    }
+    takeUsage() {
+        const usage = this.usage;
+        this.usage = null;
+        return usage;
+    }
+}
+//# sourceMappingURL=stream-normalizer.js.map

package/data/build/dist/host/cli-adapters/tool-observation.d.ts

@@ -0,0 +1,9 @@
+import type { CodingNsAgentToolEvent } from '../../shared/contracts/cli-adapter.js';
+export type ExternalToolStatus = NonNullable<CodingNsAgentToolEvent['status']>;
+/** 保留 Provider 的结构化参数和结果，不用隐式的 [object Object] 丢失信息。 */
+export declare function serializeToolValue(value: unknown): string | undefined;
+/** 工具状态的常见别名统一到 Host 契约，未知值使用调用方给出的协议阶段。 */
+export declare function normalizeToolStatus(value: unknown, fallback: ExternalToolStatus): ExternalToolStatus;
+export declare function firstToolText(...values: unknown[]): string | undefined;
+export declare function isToolRecord(value: unknown): value is Record<string, any>;
+//# sourceMappingURL=tool-observation.d.ts.map

package/data/build/dist/host/cli-adapters/tool-observation.js

@@ -0,0 +1,39 @@
+/** 保留 Provider 的结构化参数和结果，不用隐式的 [object Object] 丢失信息。 */
+export function serializeToolValue(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === 'string')
+        return value;
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/** 工具状态的常见别名统一到 Host 契约，未知值使用调用方给出的协议阶段。 */
+export function normalizeToolStatus(value, fallback) {
+    const status = typeof value === 'string' ? value.trim().toLowerCase().replace(/[\s-]+/gu, '_') : '';
+    if (['queued', 'pending', 'starting', 'started'].includes(status))
+        return 'started';
+    if (['running', 'in_progress', 'inprogress', 'streaming'].includes(status))
+        return 'running';
+    if (['completed', 'complete', 'done', 'success', 'succeeded'].includes(status))
+        return 'completed';
+    if (['failed', 'failure', 'error', 'denied', 'rejected', 'cancelled', 'canceled'].includes(status))
+        return 'failed';
+    return fallback;
+}
+export function firstToolText(...values) {
+    for (const value of values) {
+        if (typeof value === 'string' && value.trim() !== '')
+            return value.trim();
+        if (typeof value === 'number' && Number.isFinite(value))
+            return String(value);
+    }
+    return undefined;
+}
+export function isToolRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=tool-observation.js.map

package/data/build/dist/host/control-api-client.d.ts

@@ -0,0 +1,84 @@
+import type { AuthDeviceManagementSnapshotDto, HostBindRequest, HostBindResponse, HostBindingsResponse, HostLabelAvailabilityResponse, HostUnbindResponse, LoginByEmailRequest } from '../shared/contracts/auth.js';
+import type { DshDeviceHeartbeatResponse, DshDeviceListResponse, DshDeviceRegistrationRequest, DshDeviceRegistrationResponse, DshRelayTicketRequest, DshRelayTicketResponse } from '../shared/contracts/dsh-device.js';
+import type { RelaySignalingTicketRequest, RelaySignalingTicketResponse } from '../shared/contracts/signaling.js';
+/** 仅 Host 使用的控制面会话响应；refresh token 不进入 shared/client 类型。 */
+export interface LoginByEmailResponse {
+    account: import('../shared/contracts/auth.js').AccountProfile;
+    accessToken: string;
+    expiresAt: string;
+    refreshToken: string;
+    refreshTokenExpiresAt: string;
+}
+export interface RefreshTokenRequest {
+    refreshToken: string;
+}
+export type RefreshTokenResponse = LoginByEmailResponse;
+/** codingns-proxy Control API 的真实路径，供后续 HTTP 实现复用。 */
+export declare const CODINGNS_CONTROL_API_PATHS: {
+    readonly login: "/api/public/auth/login";
+    readonly refresh: "/api/public/auth/refresh";
+    readonly me: "/api/v1/auth/me";
+    readonly hosts: "/api/v1/hosts";
+    readonly bind: "/api/v1/hosts/bind";
+    readonly availability: "/api/v1/hosts/availability";
+    readonly signalingTicket: "/api/v1/relay/signaling/ticket";
+    readonly dshDevices: "/api/v1/dsh/devices";
+    readonly dshRelayTicket: "/api/v1/dsh/relay/ticket";
+};
+export declare class CodingNsControlApiError extends Error {
+    readonly status: number;
+    readonly errorCode: string | null;
+    constructor(message: string, status: number, errorCode?: string | null);
+}
+/**
+ * 控制面客户端边界。实现必须由调用方注入，阶段 2 不执行 fetch。
+ * accessToken 只作为调用参数存在，不进入凭据存储或公开快照。
+ */
+export interface CodingNsControlApiClient {
+    login(request: LoginByEmailRequest): Promise<LoginByEmailResponse>;
+    refresh(request: RefreshTokenRequest): Promise<RefreshTokenResponse>;
+    getDevices(accessToken: string): Promise<AuthDeviceManagementSnapshotDto>;
+    listHostBindings(accessToken: string): Promise<HostBindingsResponse>;
+    bindHost(accessToken: string, request: HostBindRequest): Promise<HostBindResponse>;
+    unbindHost(accessToken: string, bindingId: string): Promise<HostUnbindResponse>;
+    checkHostLabelAvailability(accessToken: string, hostLabel: string): Promise<HostLabelAvailabilityResponse>;
+    createSignalingTicket(accessToken: string, request: RelaySignalingTicketRequest): Promise<RelaySignalingTicketResponse>;
+    registerDshDevice(accessToken: string, request: DshDeviceRegistrationRequest): Promise<DshDeviceRegistrationResponse>;
+    listDshDevices(accessToken: string): Promise<DshDeviceListResponse>;
+    heartbeatDshDevice(accessToken: string, deviceId: string, deviceCredential: string): Promise<DshDeviceHeartbeatResponse>;
+    createDshRelayTicket(accessToken: string, request: DshRelayTicketRequest): Promise<DshRelayTicketResponse>;
+}
+/** 设计文档中的简写名称；保留长名称以明确其 Control API 边界。 */
+export type CodingNsControlClient = CodingNsControlApiClient;
+export interface HttpCodingNsControlApiClientOptions {
+    controlBaseUrl: string;
+    /** 设备接口属于当前 Host API，默认与 Control API 使用同一基地址。 */
+    hostApiBaseUrl?: string;
+    fetcher?: typeof fetch;
+}
+/** 基于原生 fetch 的 Host 控制面客户端；不把 token 写入日志或快照。 */
+export declare class HttpCodingNsControlApiClient implements CodingNsControlApiClient {
+    private readonly controlBaseUrl;
+    private readonly hostApiBaseUrl;
+    private readonly fetcher;
+    constructor(options: HttpCodingNsControlApiClientOptions);
+    login(request: LoginByEmailRequest): Promise<LoginByEmailResponse>;
+    refresh(request: RefreshTokenRequest): Promise<RefreshTokenResponse>;
+    /**
+     * codingns-proxy Connect 只提供账号和 Host 绑定接口，没有旧版的设备管理接口。
+     * 保留 DTO 方法是为了兼容插件 RPC；不能向不存在的 `/api/auth/devices` 发请求，
+     * 否则登录成功后的补充状态读取会被误报成登录失败。
+     */
+    getDevices(_accessToken: string): Promise<AuthDeviceManagementSnapshotDto>;
+    listHostBindings(accessToken: string): Promise<HostBindingsResponse>;
+    bindHost(accessToken: string, request: HostBindRequest): Promise<HostBindResponse>;
+    unbindHost(accessToken: string, bindingId: string): Promise<HostUnbindResponse>;
+    checkHostLabelAvailability(accessToken: string, hostLabel: string): Promise<HostLabelAvailabilityResponse>;
+    createSignalingTicket(accessToken: string, request: RelaySignalingTicketRequest): Promise<RelaySignalingTicketResponse>;
+    registerDshDevice(accessToken: string, request: DshDeviceRegistrationRequest): Promise<DshDeviceRegistrationResponse>;
+    listDshDevices(accessToken: string): Promise<DshDeviceListResponse>;
+    heartbeatDshDevice(accessToken: string, deviceId: string, deviceCredential: string): Promise<DshDeviceHeartbeatResponse>;
+    createDshRelayTicket(accessToken: string, request: DshRelayTicketRequest): Promise<DshRelayTicketResponse>;
+    private request;
+}
+//# sourceMappingURL=control-api-client.d.ts.map

package/data/build/dist/host/control-api-client.js

@@ -0,0 +1,130 @@
+/** codingns-proxy Control API 的真实路径，供后续 HTTP 实现复用。 */
+export const CODINGNS_CONTROL_API_PATHS = {
+    login: '/api/public/auth/login',
+    refresh: '/api/public/auth/refresh',
+    me: '/api/v1/auth/me',
+    // 当前 codingns-proxy 没有独立的设备管理接口；设备绑定通过 hosts 返回。
+    hosts: '/api/v1/hosts',
+    bind: '/api/v1/hosts/bind',
+    availability: '/api/v1/hosts/availability',
+    signalingTicket: '/api/v1/relay/signaling/ticket',
+    dshDevices: '/api/v1/dsh/devices',
+    dshRelayTicket: '/api/v1/dsh/relay/ticket',
+};
+export class CodingNsControlApiError extends Error {
+    status;
+    errorCode;
+    constructor(message, status, errorCode = null) {
+        super(message);
+        this.name = 'CodingNsControlApiError';
+        this.status = status;
+        this.errorCode = errorCode;
+    }
+}
+/** 基于原生 fetch 的 Host 控制面客户端；不把 token 写入日志或快照。 */
+export class HttpCodingNsControlApiClient {
+    controlBaseUrl;
+    hostApiBaseUrl;
+    fetcher;
+    constructor(options) {
+        this.controlBaseUrl = normalizeBaseUrl(options.controlBaseUrl);
+        this.hostApiBaseUrl = normalizeBaseUrl(options.hostApiBaseUrl ?? options.controlBaseUrl);
+        this.fetcher = options.fetcher ?? globalThis.fetch.bind(globalThis);
+    }
+    login(request) {
+        return this.request(this.controlBaseUrl, CODINGNS_CONTROL_API_PATHS.login, { method: 'POST', body: request });
+    }
+    refresh(request) {
+        return this.request(this.controlBaseUrl, CODINGNS_CONTROL_API_PATHS.refresh, { method: 'POST', body: request });
+    }
+    /**
+     * codingns-proxy Connect 只提供账号和 Host 绑定接口，没有旧版的设备管理接口。
+     * 保留 DTO 方法是为了兼容插件 RPC；不能向不存在的 `/api/auth/devices` 发请求，
+     * 否则登录成功后的补充状态读取会被误报成登录失败。
+     */
+    getDevices(_accessToken) {
+        return Promise.resolve({
+            currentDevice: null,
+            otherActiveDevices: [],
+            recentLoginRecords: [],
+        });
+    }
+    listHostBindings(accessToken) {
+        return this.request(this.controlBaseUrl, CODINGNS_CONTROL_API_PATHS.hosts, { token: accessToken });
+    }
+    bindHost(accessToken, request) {
+        return this.request(this.controlBaseUrl, CODINGNS_CONTROL_API_PATHS.bind, { method: 'POST', token: accessToken, body: request });
+    }
+    unbindHost(accessToken, bindingId) {
+        return this.request(this.controlBaseUrl, `/api/v1/hosts/${encodeURIComponent(bindingId)}`, { method: 'DELETE', token: accessToken });
+    }
+    checkHostLabelAvailability(accessToken, hostLabel) {
+        return this.request(this.controlBaseUrl, `${CODINGNS_CONTROL_API_PATHS.availability}?hostLabel=${encodeURIComponent(hostLabel)}`, { token: accessToken });
+    }
+    createSignalingTicket(accessToken, request) {
+        return this.request(this.controlBaseUrl, CODINGNS_CONTROL_API_PATHS.signalingTicket, {
+            method: 'POST',
+            token: accessToken,
+            body: request,
+        });
+    }
+    registerDshDevice(accessToken, request) {
+        return this.request(this.controlBaseUrl, CODINGNS_CONTROL_API_PATHS.dshDevices, { method: 'POST', token: accessToken, body: request });
+    }
+    listDshDevices(accessToken) {
+        return this.request(this.controlBaseUrl, CODINGNS_CONTROL_API_PATHS.dshDevices, { token: accessToken });
+    }
+    heartbeatDshDevice(accessToken, deviceId, deviceCredential) {
+        return this.request(this.controlBaseUrl, `${CODINGNS_CONTROL_API_PATHS.dshDevices}/${encodeURIComponent(deviceId)}/heartbeat`, {
+            method: 'POST',
+            token: accessToken,
+            headers: { 'x-dsh-device-credential': deviceCredential },
+        });
+    }
+    createDshRelayTicket(accessToken, request) {
+        return this.request(this.controlBaseUrl, CODINGNS_CONTROL_API_PATHS.dshRelayTicket, {
+            method: 'POST',
+            token: accessToken,
+            body: request,
+            headers: { 'x-dsh-device-credential': request.deviceCredential },
+        });
+    }
+    async request(baseUrl, path, options = {}) {
+        const headers = new Headers({ accept: 'application/json' });
+        for (const [key, value] of Object.entries(options.headers ?? {}))
+            headers.set(key, value);
+        if (options.body !== undefined)
+            headers.set('content-type', 'application/json');
+        if (options.token)
+            headers.set('authorization', `Bearer ${options.token}`);
+        const requestInit = { method: options.method ?? 'GET', headers };
+        if (options.body !== undefined)
+            requestInit.body = JSON.stringify(options.body);
+        const response = await this.fetcher(`${baseUrl}${path}`, requestInit);
+        const raw = await response.text();
+        let data = null;
+        if (raw) {
+            try {
+                data = JSON.parse(raw);
+            }
+            catch {
+                data = null;
+            }
+        }
+        if (!response.ok) {
+            const error = isRecord(data) && typeof data.errorCode === 'string' ? data.errorCode : null;
+            throw new CodingNsControlApiError(`Control API 请求失败 (${response.status})`, response.status, error);
+        }
+        return data;
+    }
+}
+function normalizeBaseUrl(value) {
+    const url = new URL(value);
+    if (url.protocol !== 'https:' && url.protocol !== 'http:')
+        throw new TypeError('Control API 地址必须使用 HTTP(S)');
+    return url.toString().replace(/\/$/u, '');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=control-api-client.js.map

package/data/build/dist/host/credential-store.d.ts

@@ -0,0 +1,54 @@
+import type { DshDeviceCredentialRecord } from '../shared/contracts/dsh-device.js';
+/** 仅 Host 内部使用的敏感凭据；不要从 Client entry 导入或序列化到客户端。 */
+export interface HostCredentialRecord {
+    controlBaseUrl: string;
+    accountId: string;
+    refreshToken: string;
+    refreshTokenExpiresAt: string;
+    deviceId: string | null;
+    savedAt: string;
+}
+/** Host 凭据存储抽象；生产实现应接入 DSH/Codingns4DSH 的安全凭据存储。 */
+export interface CodingNsCredentialStore {
+    read(): Promise<HostCredentialRecord | null>;
+    write(record: HostCredentialRecord): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * 测试用内存实现。
+ * 不提供持久化或加密语义，不能用于生产；用于阶段 2 状态机单元测试。
+ */
+export declare class InMemoryCodingNsCredentialStore implements CodingNsCredentialStore {
+    private record;
+    read(): Promise<HostCredentialRecord | null>;
+    write(record: HostCredentialRecord): Promise<void>;
+    clear(): Promise<void>;
+}
+/** Host 侧 refresh token 的文件存储；文件权限限制为当前用户可读写。 */
+export declare class FileCodingNsCredentialStore implements CodingNsCredentialStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    read(): Promise<HostCredentialRecord | null>;
+    write(record: HostCredentialRecord): Promise<void>;
+    clear(): Promise<void>;
+}
+/** DSH device credential 独立存储，避免与 Codingns4DSH refresh token 混用。 */
+export interface DshDeviceCredentialStore {
+    read(): Promise<DshDeviceCredentialRecord | null>;
+    write(record: DshDeviceCredentialRecord): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare class InMemoryDshDeviceCredentialStore implements DshDeviceCredentialStore {
+    private record;
+    read(): Promise<DshDeviceCredentialRecord | null>;
+    write(record: DshDeviceCredentialRecord): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare class FileDshDeviceCredentialStore implements DshDeviceCredentialStore {
+    private readonly filePath;
+    constructor(filePath: string);
+    read(): Promise<DshDeviceCredentialRecord | null>;
+    write(record: DshDeviceCredentialRecord): Promise<void>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=credential-store.d.ts.map