@jingyi0605/codingns4dsh 0.1.0

package/data/build/dist/shared/contracts/config.d.ts

@@ -0,0 +1,113 @@
+import type { FeatureDescriptor } from './feature.js';
+import type { CodingNsCliSessionRecord } from './cli-adapter.js';
+/** 适配器最近一次使用的模型与思考强度。 */
+export interface CodingNsCliAdapterPreference {
+    readonly modelId?: string | undefined;
+    readonly effortId?: string | undefined;
+}
+/** Codingns4DSH 在 DSH 设置文档中持久化的用户选项。 */
+export interface CodingNsSettings {
+    /** Control API 地址不是秘密，可以由 Web 设置页保存到 Host 设置。 */
+    controlBaseUrl: string;
+    /** Control API 地址候选列表；列表本身不包含任何凭据。 */
+    controlBaseUrls: string[];
+    /** 局域网访问 DSH 的唯一监听映射及启动策略。 */
+    lanAccessDsh: LanAccessDshSettings;
+    /** 插件 Sidebar 终端的默认 profile 与受控外观设置。 */
+    terminalEnhancement: TerminalEnhancementSettings;
+    /** 原生工作区会话行的浏览器端增强选项。 */
+    workspaceSessionEnhancement: WorkspaceSessionEnhancementSettings;
+    /**
+     * 功能模块启用意图：模块名 -> 是否启用。
+     *
+     * 缺省时回落到模块自己声明的 enabledByDefault，因此设置结构不随模块数量变化。
+    */
+    modules: Record<string, boolean>;
+    /** 外部 Agent 启用意图：适配器 id -> 是否启用；缺省时所有已注册 Agent 启用。 */
+    agentAdapters?: Record<string, boolean>;
+    /** Host 侧外部 Agent 会话索引；不含凭据和原始消息。 */
+    cliSessions?: CodingNsCliSessionRecord[];
+    /** 适配器级最近选择；新建会话时作为默认模型和思考强度。 */
+    agentAdapterPreferences?: Record<string, CodingNsCliAdapterPreference>;
+}
+/** 跨平台终端 profile；`system` 由 Host 根据平台和已安装 shell 解析。 */
+export type TerminalProfileId = 'system' | 'zsh' | 'bash' | 'powershell' | 'cmd' | 'git-bash';
+/** 终端持久记录的归属范围；工作区模式允许不同 DSH 会话共享终端。 */
+export type TerminalBindingScope = 'workspace' | 'session';
+export type TerminalAppearanceTheme = 'inherit' | 'custom';
+export type TerminalCursorStyle = 'block' | 'bar' | 'underline';
+/** 仅保存可映射到 xterm 公开选项的外观字段。 */
+export interface TerminalAppearanceSettings {
+    theme: TerminalAppearanceTheme;
+    background: string | null;
+    foreground: string | null;
+    cursorColor: string | null;
+    fontFamily: string | null;
+    fontSize: number | null;
+    lineHeight: number | null;
+    cursorStyle: TerminalCursorStyle | null;
+    cursorBlink: boolean | null;
+    scrollback: number | null;
+}
+export interface TerminalEnhancementSettings {
+    /** 缺省按工作区归属；旧设置缺少此字段时由 schema 回填。 */
+    bindingScope?: TerminalBindingScope;
+    defaultProfile: TerminalProfileId;
+    appearance: TerminalAppearanceSettings;
+}
+/** 工作区会话增强的用户可见设置；每个子能力都可以独立开关。 */
+export interface WorkspaceSessionEnhancementSettings {
+    showAdapterLogo: boolean;
+    /** 是否在每个有归档会话的工作区中显示归档入口。 */
+    showArchivedSessions: boolean;
+    /** 是否在对话底部显示订阅与上游用量检测。 */
+    showSubscriptionUsage: boolean;
+}
+/** 局域网访问 DSH 的持久化配置；dshPort 为 0 表示启动时自动探测。 */
+export interface LanAccessDshSettings {
+    autoStart: boolean;
+    listenHost: string;
+    listenPort: number;
+    dshPort: number;
+}
+export interface LoginProtectionScopes {
+    /** 局域网网卡入口。 */
+    lan: boolean;
+    /** DSH-Codingns4DSH 中继入口。 */
+    relay: boolean;
+}
+/** 登录保护的公开设置；密码哈希仅保存在 Host 私有凭据文件中。 */
+export interface LanAccessDshLoginSettings {
+    enabled: boolean;
+    username: string;
+    passwordConfigured: boolean;
+    timeoutSeconds: number;
+    scopes: LoginProtectionScopes;
+}
+export declare const CODINGNS_SETTINGS_NAMESPACE = "codingns";
+export declare const CODINGNS_CONTROL_BASE_URL_FIELD = "controlBaseUrl";
+export declare const CODINGNS_CONTROL_BASE_URLS_FIELD = "controlBaseUrls";
+export declare const CODINGNS_MODULES_FIELD = "modules";
+export declare const CODINGNS_LAN_ACCESS_DSH_FIELD = "lanAccessDsh";
+export declare const CODINGNS_TERMINAL_ENHANCEMENT_FIELD = "terminalEnhancement";
+export declare const CODINGNS_WORKSPACE_SESSION_ENHANCEMENT_FIELD = "workspaceSessionEnhancement";
+export declare const DEFAULT_CODINGNS_CONTROL_BASE_URL = "https://channel.codingns.com:1443";
+export declare const DEFAULT_CODINGNS_CONTROL_BASE_URLS: string[];
+export declare const DEFAULT_TERMINAL_ENHANCEMENT_SETTINGS: TerminalEnhancementSettings;
+export declare const DEFAULT_WORKSPACE_SESSION_ENHANCEMENT_SETTINGS: WorkspaceSessionEnhancementSettings;
+export declare const DEFAULT_CODINGNS_SETTINGS: CodingNsSettings;
+/** 重启生效模块在当前进程启动时捕获的有效状态。 */
+export type RestartFeatureStates = Readonly<Record<string, boolean>>;
+export declare function captureRestartFeatureStates(descriptors: readonly FeatureDescriptor[], settings: CodingNsSettings | undefined, dshVersion?: string): Record<string, boolean>;
+/**
+ * 判定一个功能模块当前是否应当启用。
+ *
+ * 常驻模块（ui.alwaysEnabled）始终启用；其余模块读取设置里的用户意图，
+ * 用户没有表达过意图时使用模块自己声明的 enabledByDefault。
+ */
+export declare function isFeatureEnabled(descriptor: FeatureDescriptor, settings: CodingNsSettings | undefined): boolean;
+/** 汇总当前应当启用的模块名，交给 FeatureRegistry.reconcile 对齐状态。 */
+export declare function enabledFeatureNames(descriptors: readonly FeatureDescriptor[], settings: CodingNsSettings | undefined, restartStates?: RestartFeatureStates, dshVersion?: string): string[];
+/** 判断模块是否可以在当前 DSH 版本运行。未提供运行时版本时保留旧调用方行为。 */
+export declare function isFeatureDshVersionCompatible(descriptor: FeatureDescriptor, dshVersion?: string): boolean;
+//# sourceMappingURL=config.d.ts.map

package/data/build/dist/shared/contracts/config.js

@@ -0,0 +1,86 @@
+import { isDshVersionAtLeast } from './version.js';
+export const CODINGNS_SETTINGS_NAMESPACE = 'codingns';
+export const CODINGNS_CONTROL_BASE_URL_FIELD = 'controlBaseUrl';
+export const CODINGNS_CONTROL_BASE_URLS_FIELD = 'controlBaseUrls';
+export const CODINGNS_MODULES_FIELD = 'modules';
+export const CODINGNS_LAN_ACCESS_DSH_FIELD = 'lanAccessDsh';
+export const CODINGNS_TERMINAL_ENHANCEMENT_FIELD = 'terminalEnhancement';
+export const CODINGNS_WORKSPACE_SESSION_ENHANCEMENT_FIELD = 'workspaceSessionEnhancement';
+export const DEFAULT_CODINGNS_CONTROL_BASE_URL = 'https://channel.codingns.com:1443';
+export const DEFAULT_CODINGNS_CONTROL_BASE_URLS = [DEFAULT_CODINGNS_CONTROL_BASE_URL];
+export const DEFAULT_TERMINAL_ENHANCEMENT_SETTINGS = {
+    bindingScope: 'workspace',
+    defaultProfile: 'system',
+    appearance: {
+        theme: 'inherit',
+        background: null,
+        foreground: null,
+        cursorColor: null,
+        fontFamily: null,
+        fontSize: null,
+        lineHeight: null,
+        cursorStyle: null,
+        cursorBlink: null,
+        scrollback: null,
+    },
+};
+export const DEFAULT_WORKSPACE_SESSION_ENHANCEMENT_SETTINGS = {
+    showAdapterLogo: true,
+    showArchivedSessions: true,
+    showSubscriptionUsage: true,
+};
+export const DEFAULT_CODINGNS_SETTINGS = {
+    controlBaseUrl: DEFAULT_CODINGNS_CONTROL_BASE_URL,
+    controlBaseUrls: [...DEFAULT_CODINGNS_CONTROL_BASE_URLS],
+    modules: {},
+    agentAdapters: {},
+    agentAdapterPreferences: {},
+    terminalEnhancement: DEFAULT_TERMINAL_ENHANCEMENT_SETTINGS,
+    workspaceSessionEnhancement: DEFAULT_WORKSPACE_SESSION_ENHANCEMENT_SETTINGS,
+    lanAccessDsh: {
+        autoStart: false,
+        listenHost: '0.0.0.0',
+        listenPort: 13080,
+        dshPort: 0,
+    },
+};
+export function captureRestartFeatureStates(descriptors, settings, dshVersion) {
+    const states = {};
+    for (const descriptor of descriptors) {
+        if (descriptor.activation === 'restart') {
+            states[descriptor.name] = isFeatureDshVersionCompatible(descriptor, dshVersion)
+                && isFeatureEnabled(descriptor, settings);
+        }
+    }
+    return states;
+}
+/**
+ * 判定一个功能模块当前是否应当启用。
+ *
+ * 常驻模块（ui.alwaysEnabled）始终启用；其余模块读取设置里的用户意图，
+ * 用户没有表达过意图时使用模块自己声明的 enabledByDefault。
+ */
+export function isFeatureEnabled(descriptor, settings) {
+    if (descriptor.ui?.alwaysEnabled === true)
+        return true;
+    return settings?.modules[descriptor.name] ?? descriptor.enabledByDefault;
+}
+/** 汇总当前应当启用的模块名，交给 FeatureRegistry.reconcile 对齐状态。 */
+export function enabledFeatureNames(descriptors, settings, restartStates, dshVersion) {
+    const names = [];
+    for (const descriptor of descriptors) {
+        const enabled = descriptor.activation === 'restart' && restartStates !== undefined
+            ? restartStates[descriptor.name] ?? descriptor.enabledByDefault
+            : isFeatureEnabled(descriptor, settings);
+        if (enabled && isFeatureDshVersionCompatible(descriptor, dshVersion))
+            names.push(descriptor.name);
+    }
+    return names;
+}
+/** 判断模块是否可以在当前 DSH 版本运行。未提供运行时版本时保留旧调用方行为。 */
+export function isFeatureDshVersionCompatible(descriptor, dshVersion) {
+    if (descriptor.minimumDshVersion === undefined || dshVersion === undefined)
+        return true;
+    return isDshVersionAtLeast(dshVersion, descriptor.minimumDshVersion);
+}
+//# sourceMappingURL=config.js.map

package/data/build/dist/shared/contracts/debug-config.d.ts

@@ -0,0 +1,28 @@
+import type { CodingNsTerminalShell, CodingNsTerminalRuntimeType } from './terminal.js';
+/** Workspace 级 Spec003 配置文件。 */
+export interface DebugConfig {
+    readonly version: 1;
+    readonly profiles: readonly DebugProfile[];
+}
+/** 一条按配置启动的终端命令。 */
+export interface DebugProfile {
+    readonly id: string;
+    readonly name: string;
+    readonly cwdRelative: string;
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+    readonly shell: DebugShell;
+    readonly runtimeType: DebugRuntimeType;
+    readonly port: number | null;
+    readonly proxy: DebugProxyConfig;
+}
+export type DebugRuntimeType = CodingNsTerminalRuntimeType;
+export type DebugShell = CodingNsTerminalShell;
+export interface DebugProxyConfig {
+    readonly enabled: boolean;
+}
+export declare const EMPTY_DEBUG_CONFIG: DebugConfig;
+/** 解析并校验 Workspace 配置；不接受绝对路径、越界路径和秘密环境变量。 */
+export declare function parseDebugConfig(value: unknown): DebugConfig;
+//# sourceMappingURL=debug-config.d.ts.map

package/data/build/dist/shared/contracts/debug-config.js

@@ -0,0 +1,78 @@
+export const EMPTY_DEBUG_CONFIG = { version: 1, profiles: [] };
+/** 解析并校验 Workspace 配置；不接受绝对路径、越界路径和秘密环境变量。 */
+export function parseDebugConfig(value) {
+    if (!isRecord(value) || value.version !== 1 || !Array.isArray(value.profiles)) {
+        throw new TypeError('Spec003 配置必须是 version=1 的对象');
+    }
+    const profiles = value.profiles.map(parseDebugProfile);
+    const ids = new Set();
+    for (const profile of profiles) {
+        if (ids.has(profile.id))
+            throw new TypeError(`Spec003 配置项 ID 重复: ${profile.id}`);
+        ids.add(profile.id);
+    }
+    return { version: 1, profiles };
+}
+function parseDebugProfile(value) {
+    if (!isRecord(value))
+        throw new TypeError('Spec003 配置项必须是对象');
+    const id = stringField(value.id, 'id');
+    const name = stringField(value.name, 'name');
+    const cwdRelative = stringField(value.cwdRelative, 'cwdRelative');
+    if (!isRelativePath(cwdRelative))
+        throw new TypeError('cwdRelative 必须是 Workspace 内相对路径');
+    const command = stringField(value.command, 'command');
+    const args = stringArray(value.args ?? [], 'args');
+    const env = recordOfStrings(value.env ?? {}, 'env');
+    if (Object.keys(env).some((key) => /(?:TOKEN|SECRET|PASSWORD|PRIVATE_KEY|API_KEY)/iu.test(key))) {
+        throw new TypeError('配置不能持久化秘密环境变量');
+    }
+    if (!isRecord(value.shell))
+        throw new TypeError('shell 必须是对象');
+    const profileId = stringField(value.shell.profileId, 'shell.profileId');
+    if (profileId !== 'zsh' && profileId !== 'bash' && profileId !== 'powershell' && profileId !== 'cmd' && profileId !== 'git-bash')
+        throw new TypeError('shell.profileId 无效');
+    const shell = {
+        profileId,
+        path: stringField(value.shell.path, 'shell.path'),
+        args: stringArray(value.shell.args ?? [], 'shell.args'),
+        name: stringField(value.shell.name, 'shell.name'),
+    };
+    const runtimeType = value.runtimeType;
+    if (runtimeType !== 'local-pty' && runtimeType !== 'tmux' && runtimeType !== 'conpty-powershell' && runtimeType !== 'conpty-cmd' && runtimeType !== 'conpty-git-bash') {
+        throw new TypeError('runtimeType 无效');
+    }
+    const port = value.port === undefined || value.port === null ? null : portValue(value.port);
+    const proxyValue = value.proxy === undefined ? {} : value.proxy;
+    if (!isRecord(proxyValue))
+        throw new TypeError('proxy 必须是对象');
+    const enabled = proxyValue.enabled === undefined ? false : proxyValue.enabled;
+    if (typeof enabled !== 'boolean')
+        throw new TypeError('proxy.enabled 必须是布尔值');
+    return { id, name, cwdRelative, command, args, env, shell, runtimeType, port, proxy: { enabled } };
+}
+function stringField(value, field) {
+    if (typeof value !== 'string' || value.trim() === '' || value.includes('\0') || value.length > 512)
+        throw new TypeError(`${field} 必须是非空字符串`);
+    return value.trim();
+}
+function stringArray(value, field) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || item.includes('\0') || item.length > 4096))
+        throw new TypeError(`${field} 必须是字符串数组`);
+    return [...value];
+}
+function recordOfStrings(value, field) {
+    if (!isRecord(value) || Object.entries(value).some(([key, item]) => key.trim() === '' || typeof item !== 'string'))
+        throw new TypeError(`${field} 必须是字符串对象`);
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, item]));
+}
+function portValue(value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1 || value > 65535)
+        throw new TypeError('port 必须是 1 到 65535 的整数');
+    return value;
+}
+function isRelativePath(value) {
+    return value === '.' || (value !== '' && !value.startsWith('/') && !/^[A-Za-z]:[\\/]/u.test(value) && value !== '..' && !value.startsWith('../') && !value.startsWith('..\\') && !value.includes('/../') && !value.includes('\\..'));
+}
+function isRecord(value) { return typeof value === 'object' && value !== null && !Array.isArray(value); }
+//# sourceMappingURL=debug-config.js.map

package/data/build/dist/shared/contracts/debug.d.ts

@@ -0,0 +1,75 @@
+/** Spec003 调试运行模式。`pty` 复用现有终端启动器，`process` 由 Spec003 自己管理。 */
+export type DebugRuntimeMode = 'process' | 'pty';
+/** 调试运行实例的生命周期状态。 */
+export type DebugRuntimeState = 'PREPARING' | 'STARTING' | 'RUNNING' | 'STOPPING' | 'EXITED' | 'FAILED' | 'LOST';
+/** 端口发现结果的归属等级。 */
+export type DebugProcessOwnership = 'managed' | 'agent_terminal' | 'discovered';
+/** 端口在调试面板中的状态。 */
+export type DebugPortState = 'UNCONFIGURED' | 'AVAILABLE' | 'LEASED' | 'LISTENING_OWNED' | 'OCCUPIED_EXTERNAL' | 'MISMATCH';
+/** 框架分析的准入等级。 */
+export type DebugCompatibilityLevel = 'supported' | 'conditional' | 'unsupported' | 'unknown';
+/** 启动计划状态。 */
+export type DebugPlanState = 'draft' | 'ready' | 'blocked' | 'expired' | 'consumed';
+/** AI 兜底补丁状态。 */
+export type DebugAiFallbackState = 'PENDING' | 'APPLIED' | 'REJECTED' | 'ROLLED_BACK' | 'KEPT' | 'CONFLICT';
+/** 调试代理支持的协议。 */
+export type DebugProxyProtocol = 'http' | 'sse' | 'websocket';
+/** 阶段 0 冻结的调试 RPC 名称；具体实现由后续阶段登记。 */
+export declare const DEBUG_RPC_ENDPOINTS: readonly ["debug/snapshot", "debug/profile/list", "debug/profile/create", "debug/profile/update", "debug/profile/delete", "debug/profile/clone", "debug/analysis/get", "debug/analysis/refresh", "debug/analysis/matrix", "debug/plan/create", "debug/plan/discard", "debug/runtime/start", "debug/runtime/get", "debug/runtime/list", "debug/runtime/stop", "debug/runtime/restart", "debug/process/inspect-port", "debug/process/terminate-candidate", "debug/log/read", "debug/log/follow", "debug/ai/preview", "debug/ai/apply", "debug/ai/reject", "debug/ai/rollback", "debug/ai/keep", "debug/proxy/get", "debug/proxy/enable", "debug/proxy/disable", "debug/settings/get", "debug/settings/set"];
+export type DebugRpcEndpoint = typeof DEBUG_RPC_ENDPOINTS[number];
+/** 调试领域稳定错误码。错误码先冻结，后续 Host 实现不得用自由文本替代。 */
+export declare const DEBUG_ERROR_CODES: {
+    readonly INVALID_REQUEST: "DEBUG_INVALID_REQUEST";
+    readonly WORKSPACE_REQUIRED: "DEBUG_WORKSPACE_REQUIRED";
+    readonly WORKSPACE_SESSION_MISMATCH: "DEBUG_WORKSPACE_SESSION_MISMATCH";
+    readonly GENERATION_STALE: "DEBUG_GENERATION_STALE";
+    readonly REVISION_CONFLICT: "DEBUG_REVISION_CONFLICT";
+    readonly PROFILE_NOT_FOUND: "DEBUG_PROFILE_NOT_FOUND";
+    readonly PROCESS_INSTANCE_NOT_FOUND: "DEBUG_PROCESS_INSTANCE_NOT_FOUND";
+    readonly PROCESS_IDENTITY_MISMATCH: "DEBUG_PROCESS_IDENTITY_MISMATCH";
+    readonly PORT_LEASE_CONFLICT: "DEBUG_PORT_LEASE_CONFLICT";
+    readonly RUNTIME_NOT_FOUND: "DEBUG_RUNTIME_NOT_FOUND";
+    readonly PROXY_ROUTE_NOT_FOUND: "DEBUG_PROXY_ROUTE_NOT_FOUND";
+    readonly DSH_HOST_API_UNAVAILABLE: "DEBUG_DSH_HOST_API_UNAVAILABLE";
+};
+export type DebugErrorCode = typeof DEBUG_ERROR_CODES[keyof typeof DEBUG_ERROR_CODES];
+/** 所有调试 RPC 都必须携带的作用域。generation 由当前连接/资源作用域产生。 */
+export interface DebugRpcScope {
+    readonly sessionId: string;
+    readonly workspaceId: string;
+    readonly generation: number;
+}
+/** 需要乐观并发控制的调试写请求。两个版本字段最多提供一个。 */
+export interface DebugMutationScope extends DebugRpcScope {
+    readonly recordId: string;
+    readonly expectedRevision?: number;
+    readonly expectedUpdatedAt?: string;
+}
+/** PTY 启动请求只携带意图，不携带绝对路径、PID 或端口目标。 */
+export interface DebugPtyLaunchRequest extends DebugRpcScope {
+    readonly profileId: string;
+    readonly cols: number;
+    readonly rows: number;
+}
+/** 调试面板保存的运行实例摘要。完整进程身份只留在 Host。 */
+export interface DebugProcessInstance {
+    readonly id: string;
+    readonly workspaceId: string;
+    readonly profileId: string;
+    readonly runtimeMode: DebugRuntimeMode;
+    readonly state: DebugRuntimeState;
+    readonly ownership: 'managed';
+    readonly terminalId: string | null;
+    readonly pid: number | null;
+    readonly processFingerprint: string | null;
+    readonly startedAt: string | null;
+    readonly stoppedAt: string | null;
+    readonly exitCode: number | null;
+}
+/** 规范化并校验调试 RPC 作用域。禁止把 Client 的任意对象直接传入业务层。 */
+export declare function parseDebugRpcScope(value: unknown): DebugRpcScope;
+/** 规范化并校验带记录 ID 的调试写请求。 */
+export declare function parseDebugMutationScope(value: unknown): DebugMutationScope;
+/** 校验 PTY 调用参数，避免把终端尺寸或路径类字段直接信任到 Host。 */
+export declare function parseDebugPtyLaunchRequest(value: unknown): DebugPtyLaunchRequest;
+//# sourceMappingURL=debug.d.ts.map

package/data/build/dist/shared/contracts/debug.js

@@ -0,0 +1,121 @@
+/** 阶段 0 冻结的调试 RPC 名称；具体实现由后续阶段登记。 */
+export const DEBUG_RPC_ENDPOINTS = [
+    'debug/snapshot',
+    'debug/profile/list',
+    'debug/profile/create',
+    'debug/profile/update',
+    'debug/profile/delete',
+    'debug/profile/clone',
+    'debug/analysis/get',
+    'debug/analysis/refresh',
+    'debug/analysis/matrix',
+    'debug/plan/create',
+    'debug/plan/discard',
+    'debug/runtime/start',
+    'debug/runtime/get',
+    'debug/runtime/list',
+    'debug/runtime/stop',
+    'debug/runtime/restart',
+    'debug/process/inspect-port',
+    'debug/process/terminate-candidate',
+    'debug/log/read',
+    'debug/log/follow',
+    'debug/ai/preview',
+    'debug/ai/apply',
+    'debug/ai/reject',
+    'debug/ai/rollback',
+    'debug/ai/keep',
+    'debug/proxy/get',
+    'debug/proxy/enable',
+    'debug/proxy/disable',
+    'debug/settings/get',
+    'debug/settings/set',
+];
+/** 调试领域稳定错误码。错误码先冻结，后续 Host 实现不得用自由文本替代。 */
+export const DEBUG_ERROR_CODES = {
+    INVALID_REQUEST: 'DEBUG_INVALID_REQUEST',
+    WORKSPACE_REQUIRED: 'DEBUG_WORKSPACE_REQUIRED',
+    WORKSPACE_SESSION_MISMATCH: 'DEBUG_WORKSPACE_SESSION_MISMATCH',
+    GENERATION_STALE: 'DEBUG_GENERATION_STALE',
+    REVISION_CONFLICT: 'DEBUG_REVISION_CONFLICT',
+    PROFILE_NOT_FOUND: 'DEBUG_PROFILE_NOT_FOUND',
+    PROCESS_INSTANCE_NOT_FOUND: 'DEBUG_PROCESS_INSTANCE_NOT_FOUND',
+    PROCESS_IDENTITY_MISMATCH: 'DEBUG_PROCESS_IDENTITY_MISMATCH',
+    PORT_LEASE_CONFLICT: 'DEBUG_PORT_LEASE_CONFLICT',
+    RUNTIME_NOT_FOUND: 'DEBUG_RUNTIME_NOT_FOUND',
+    PROXY_ROUTE_NOT_FOUND: 'DEBUG_PROXY_ROUTE_NOT_FOUND',
+    DSH_HOST_API_UNAVAILABLE: 'DEBUG_DSH_HOST_API_UNAVAILABLE',
+};
+/** 规范化并校验调试 RPC 作用域。禁止把 Client 的任意对象直接传入业务层。 */
+export function parseDebugRpcScope(value) {
+    if (!isRecord(value))
+        throw new TypeError('调试 RPC 作用域必须是对象');
+    const sessionId = nonEmptyString(value.sessionId, 'sessionId');
+    const workspaceId = nonEmptyString(value.workspaceId, 'workspaceId');
+    const generation = nonNegativeInteger(value.generation, 'generation');
+    return { sessionId, workspaceId, generation };
+}
+/** 规范化并校验带记录 ID 的调试写请求。 */
+export function parseDebugMutationScope(value) {
+    if (!isRecord(value))
+        throw new TypeError('调试写请求必须是对象');
+    rejectUnknownFields(value, ['sessionId', 'workspaceId', 'generation', 'recordId', 'expectedRevision', 'expectedUpdatedAt'], '调试写请求');
+    const scope = parseDebugRpcScope(value);
+    const recordId = nonEmptyString(value.recordId, 'recordId');
+    const expectedRevision = value.expectedRevision;
+    const expectedUpdatedAt = value.expectedUpdatedAt;
+    if (expectedRevision !== undefined && expectedUpdatedAt !== undefined) {
+        throw new TypeError('expectedRevision 和 expectedUpdatedAt 只能提供一个');
+    }
+    if (expectedRevision !== undefined)
+        nonNegativeInteger(expectedRevision, 'expectedRevision');
+    if (expectedUpdatedAt !== undefined)
+        nonEmptyString(expectedUpdatedAt, 'expectedUpdatedAt');
+    return {
+        ...scope,
+        recordId,
+        ...(expectedRevision === undefined ? {} : { expectedRevision: nonNegativeInteger(expectedRevision, 'expectedRevision') }),
+        ...(expectedUpdatedAt === undefined ? {} : { expectedUpdatedAt: nonEmptyString(expectedUpdatedAt, 'expectedUpdatedAt') }),
+    };
+}
+/** 校验 PTY 调用参数，避免把终端尺寸或路径类字段直接信任到 Host。 */
+export function parseDebugPtyLaunchRequest(value) {
+    if (!isRecord(value))
+        throw new TypeError('PTY 启动请求必须是对象');
+    rejectUnknownFields(value, ['sessionId', 'workspaceId', 'generation', 'profileId', 'cols', 'rows'], 'PTY 启动请求');
+    const scope = parseDebugRpcScope(value);
+    const profileId = nonEmptyString(value.profileId, 'profileId');
+    const cols = positiveInteger(value.cols, 'cols');
+    const rows = positiveInteger(value.rows, 'rows');
+    if (cols > 500 || rows > 200)
+        throw new RangeError('PTY 尺寸超出允许范围');
+    return { ...scope, profileId, cols, rows };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function rejectUnknownFields(value, allowed, label) {
+    const allowedFields = new Set(allowed);
+    const unknown = Object.keys(value).find((key) => !allowedFields.has(key));
+    if (unknown !== undefined)
+        throw new TypeError(`${label}包含未知字段: ${unknown}`);
+}
+function nonEmptyString(value, field) {
+    if (typeof value !== 'string' || value.trim() === '' || value.length > 512) {
+        throw new TypeError(`${field} 必须是非空字符串`);
+    }
+    return value;
+}
+function nonNegativeInteger(value, field) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError(`${field} 必须是非负整数`);
+    }
+    return value;
+}
+function positiveInteger(value, field) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+        throw new TypeError(`${field} 必须是正整数`);
+    }
+    return value;
+}
+//# sourceMappingURL=debug.js.map

package/data/build/dist/shared/contracts/dsh-device.d.ts

@@ -0,0 +1,72 @@
+import type { RelayIceServer, RelaySignalingTicketResponse } from './signaling.js';
+/** DSH-Codingns4DSH 自己的设备记录，不与 Codingns4DSH Host binding 共用身份。 */
+export interface DshDeviceSummary {
+    /** DSH 独立设备身份；不能与 Codingns4DSH host bindingId 混用。 */
+    dshDeviceId: string;
+    /** 旧 DTO 兼容字段，服务端迁移期间可存在。 */
+    deviceId?: string;
+    displayName: string;
+    protocolVersion: string;
+    capabilities: string[];
+    dtlsFingerprint: string;
+    tunnelDomain?: string;
+    status: 'active' | 'disabled' | 'revoked' | 'offline';
+    online: boolean;
+    lastHeartbeatAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface DshDeviceRegistrationRequest {
+    displayName: string;
+    devicePublicKey: string;
+    dtlsFingerprint: string;
+    protocolVersion: string;
+    capabilities: string[];
+}
+export interface DshDeviceRegistrationResponse {
+    device: DshDeviceSummary;
+    deviceCredential: string;
+    credentialVersion: number;
+}
+export interface DshDeviceListResponse {
+    devices: DshDeviceSummary[];
+    currentDeviceId?: string;
+}
+export interface DshDeviceHeartbeatResponse {
+    device: DshDeviceSummary;
+    credentialVersion: number;
+}
+export interface DshRelayTicketRequest {
+    dshDeviceId: string;
+    deviceCredential: string;
+    hostDtlsFingerprint: string;
+    credentialVersion: number;
+    role?: 'host' | 'client';
+}
+/** DSH ticket 复用 Relay 的 ICE/信令字段，但不带 Codingns4DSH bindingId。 */
+export interface DshRelayTicketResponse extends Omit<RelaySignalingTicketResponse, 'bindingId' | 'tunnelDomain' | 'hostDtlsFingerprint' | 'credentialVersion'> {
+    product: 'codingns4dsh';
+    dshDeviceId: string;
+    hostDtlsFingerprint: string;
+    tunnelDomain?: string;
+    credentialVersion: number;
+    hostScope?: {
+        hostId: string;
+        kind: 'local' | 'remote';
+    };
+}
+/** H5/Host 侧使用的票据别名，名称与 Relay API DTO 保持一致。 */
+export type DshRelaySignalingTicket = DshRelayTicketResponse;
+export type DshRelayTicketLike = DshRelayTicketResponse | RelaySignalingTicketResponse;
+export type DshIceServer = RelayIceServer;
+/** Host 本地保存的 DSH 设备凭据；deviceCredential 只存在 Host。 */
+export interface DshDeviceCredentialRecord {
+    deviceId: string;
+    deviceCredential: string;
+    credentialVersion: number;
+    dtlsFingerprint: string;
+    tunnelDomain: string | null;
+    displayName: string;
+    savedAt: string;
+}
+//# sourceMappingURL=dsh-device.d.ts.map

package/data/build/dist/shared/contracts/dsh-device.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dsh-device.js.map

package/data/build/dist/shared/contracts/errors.d.ts

@@ -0,0 +1,33 @@
+export declare const CODINGNS_DSH_ERROR_CODES: {
+    readonly PLUGIN_MANIFEST_INVALID: "PLUGIN_MANIFEST_INVALID";
+    readonly DSH_VERSION_UNSUPPORTED: "DSH_VERSION_UNSUPPORTED";
+    readonly HOST_ENTRY_UNAVAILABLE: "HOST_ENTRY_UNAVAILABLE";
+    readonly CLIENT_ENTRY_UNAVAILABLE: "CLIENT_ENTRY_UNAVAILABLE";
+    readonly TRANSPORT_NOT_READY: "TRANSPORT_NOT_READY";
+    readonly PEER_HOST_NOT_FOUND: "PEER_HOST_NOT_FOUND";
+    readonly PEER_HOST_VERSION_MISMATCH: "PEER_HOST_VERSION_MISMATCH";
+    readonly PEER_HOST_SESSION_REQUIRED: "PEER_HOST_SESSION_REQUIRED";
+    readonly DEBUG_INVALID_REQUEST: "DEBUG_INVALID_REQUEST";
+    readonly DEBUG_WORKSPACE_REQUIRED: "DEBUG_WORKSPACE_REQUIRED";
+    readonly DEBUG_WORKSPACE_SESSION_MISMATCH: "DEBUG_WORKSPACE_SESSION_MISMATCH";
+    readonly DEBUG_GENERATION_STALE: "DEBUG_GENERATION_STALE";
+    readonly DEBUG_REVISION_CONFLICT: "DEBUG_REVISION_CONFLICT";
+    readonly DEBUG_PROFILE_NOT_FOUND: "DEBUG_PROFILE_NOT_FOUND";
+    readonly DEBUG_PROCESS_INSTANCE_NOT_FOUND: "DEBUG_PROCESS_INSTANCE_NOT_FOUND";
+    readonly DEBUG_PROCESS_IDENTITY_MISMATCH: "DEBUG_PROCESS_IDENTITY_MISMATCH";
+    readonly DEBUG_PORT_LEASE_CONFLICT: "DEBUG_PORT_LEASE_CONFLICT";
+    readonly DEBUG_RUNTIME_NOT_FOUND: "DEBUG_RUNTIME_NOT_FOUND";
+    readonly DEBUG_PROXY_ROUTE_NOT_FOUND: "DEBUG_PROXY_ROUTE_NOT_FOUND";
+    readonly DEBUG_DSH_HOST_API_UNAVAILABLE: "DEBUG_DSH_HOST_API_UNAVAILABLE";
+};
+export declare const SUPPORTED_DSH_VERSION: "0.1.6-alpha.2";
+export declare const SUPPORTED_DSH_COMPATIBILITY: ">=0.1.5-rc.3 <0.1.7-0";
+export type CodingNsDshErrorCode = typeof CODINGNS_DSH_ERROR_CODES[keyof typeof CODINGNS_DSH_ERROR_CODES];
+/** 统一错误形状；阶段 0 只定义，不主动产生这些业务错误。 */
+export declare class CodingNsDshError extends Error {
+    readonly code: CodingNsDshErrorCode;
+    constructor(code: CodingNsDshErrorCode, message: string, options?: ErrorOptions);
+}
+/** 启动期严格检查 DSH 兼容范围，不对未知版本静默降级。 */
+export declare function assertSupportedDshVersion(version: string): void;
+//# sourceMappingURL=errors.d.ts.map

package/data/build/dist/shared/contracts/errors.js

@@ -0,0 +1,41 @@
+import { DSH_COMPATIBILITY, DSH_VERSION, isDshVersionCompatible } from './version.js';
+export const CODINGNS_DSH_ERROR_CODES = {
+    PLUGIN_MANIFEST_INVALID: 'PLUGIN_MANIFEST_INVALID',
+    DSH_VERSION_UNSUPPORTED: 'DSH_VERSION_UNSUPPORTED',
+    HOST_ENTRY_UNAVAILABLE: 'HOST_ENTRY_UNAVAILABLE',
+    CLIENT_ENTRY_UNAVAILABLE: 'CLIENT_ENTRY_UNAVAILABLE',
+    TRANSPORT_NOT_READY: 'TRANSPORT_NOT_READY',
+    PEER_HOST_NOT_FOUND: 'PEER_HOST_NOT_FOUND',
+    PEER_HOST_VERSION_MISMATCH: 'PEER_HOST_VERSION_MISMATCH',
+    PEER_HOST_SESSION_REQUIRED: 'PEER_HOST_SESSION_REQUIRED',
+    DEBUG_INVALID_REQUEST: 'DEBUG_INVALID_REQUEST',
+    DEBUG_WORKSPACE_REQUIRED: 'DEBUG_WORKSPACE_REQUIRED',
+    DEBUG_WORKSPACE_SESSION_MISMATCH: 'DEBUG_WORKSPACE_SESSION_MISMATCH',
+    DEBUG_GENERATION_STALE: 'DEBUG_GENERATION_STALE',
+    DEBUG_REVISION_CONFLICT: 'DEBUG_REVISION_CONFLICT',
+    DEBUG_PROFILE_NOT_FOUND: 'DEBUG_PROFILE_NOT_FOUND',
+    DEBUG_PROCESS_INSTANCE_NOT_FOUND: 'DEBUG_PROCESS_INSTANCE_NOT_FOUND',
+    DEBUG_PROCESS_IDENTITY_MISMATCH: 'DEBUG_PROCESS_IDENTITY_MISMATCH',
+    DEBUG_PORT_LEASE_CONFLICT: 'DEBUG_PORT_LEASE_CONFLICT',
+    DEBUG_RUNTIME_NOT_FOUND: 'DEBUG_RUNTIME_NOT_FOUND',
+    DEBUG_PROXY_ROUTE_NOT_FOUND: 'DEBUG_PROXY_ROUTE_NOT_FOUND',
+    DEBUG_DSH_HOST_API_UNAVAILABLE: 'DEBUG_DSH_HOST_API_UNAVAILABLE',
+};
+export const SUPPORTED_DSH_VERSION = DSH_VERSION;
+export const SUPPORTED_DSH_COMPATIBILITY = DSH_COMPATIBILITY;
+/** 统一错误形状；阶段 0 只定义，不主动产生这些业务错误。 */
+export class CodingNsDshError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = 'CodingNsDshError';
+        this.code = code;
+    }
+}
+/** 启动期严格检查 DSH 兼容范围，不对未知版本静默降级。 */
+export function assertSupportedDshVersion(version) {
+    if (!isDshVersionCompatible(version)) {
+        throw new CodingNsDshError(CODINGNS_DSH_ERROR_CODES.DSH_VERSION_UNSUPPORTED, `不支持的 DSH 版本: ${version}；当前插件兼容范围为 ${SUPPORTED_DSH_COMPATIBILITY}`);
+    }
+}
+//# sourceMappingURL=errors.js.map