@jingyi0605/codingns4dsh 0.1.0 → 0.1.1

package/data/build/dist/dsh-capabilities/registry.js

@@ -0,0 +1,196 @@
+import { createCapabilityProfile, } from './types.js';
+export class DshCapabilityRegistryError extends Error {
+    code;
+    capability;
+    constructor(code, message, capability = null, options) {
+        super(message, options);
+        this.name = 'DshCapabilityRegistryError';
+        this.code = code;
+        this.capability = capability;
+    }
+}
+/** 集中解析 DSH 能力路由；Profile 生成后不可变，避免运行期替换半初始化服务。 */
+export class DshCapabilityRegistry {
+    dshVersion;
+    runtime;
+    routes = new Map();
+    profile;
+    constructor(dshVersion, runtime) {
+        this.dshVersion = dshVersion;
+        this.runtime = runtime;
+    }
+    register(route) {
+        validateRoute(route);
+        if (route.runtime !== this.runtime)
+            return;
+        const list = this.routes.get(route.capability) ?? [];
+        if (list.some((entry) => entry.id === route.id)) {
+            throw new DshCapabilityRegistryError('CAPABILITY_INVALID_ROUTE', `重复的能力路由: ${route.id}`, route.capability);
+        }
+        list.push(route);
+        this.routes.set(route.capability, list);
+        this.profile = undefined;
+    }
+    registerMany(routes) {
+        for (const route of routes)
+            this.register(route);
+    }
+    resolve(context) {
+        if (this.profile !== undefined)
+            return this.profile;
+        const resolutions = new Map();
+        const diagnostics = [];
+        for (const [capability, routes] of this.routes) {
+            const candidates = routes
+                .filter((route) => isVersionInRange(this.dshVersion, route.supportedDsh))
+                .sort((left, right) => routeRank(right) - routeRank(left));
+            if (candidates.length === 0) {
+                const reason = `DSH ${this.dshVersion} 没有能力 ${capability} 的适配路由`;
+                resolutions.set(capability, unavailable(capability, this.dshVersion, reason));
+                diagnostics.push({ code: 'CAPABILITY_VERSION_UNSUPPORTED', capability, dshVersion: this.dshVersion, message: reason });
+                continue;
+            }
+            const topPriority = routeRank(candidates[0]);
+            const top = candidates.filter((route) => routeRank(route) === topPriority);
+            if (top.length > 1) {
+                throw new DshCapabilityRegistryError('CAPABILITY_ROUTE_CONFLICT', `能力 ${capability} 存在同优先级路由: ${top.map((route) => route.id).join(', ')}`, capability);
+            }
+            let selected;
+            for (const route of candidates) {
+                try {
+                    if (route.detect(context)) {
+                        selected = route;
+                        break;
+                    }
+                }
+                catch (error) {
+                    diagnostics.push({
+                        code: 'CAPABILITY_DETECT_FAILED',
+                        capability,
+                        routeId: route.id,
+                        dshVersion: this.dshVersion,
+                        message: `${route.id} 探测失败: ${errorMessage(error)}`,
+                        ...(route.replacement === undefined ? {} : { replacement: route.replacement }),
+                    });
+                }
+            }
+            if (selected === undefined) {
+                const reason = `DSH ${this.dshVersion} 的能力 ${capability} 没有可用运行时实现`;
+                resolutions.set(capability, unavailable(capability, this.dshVersion, reason));
+                diagnostics.push({ code: 'CAPABILITY_UNAVAILABLE', capability, dshVersion: this.dshVersion, message: reason });
+                continue;
+            }
+            try {
+                const value = selected.create(context);
+                const resolution = {
+                    capability,
+                    routeId: selected.id,
+                    dshVersion: this.dshVersion,
+                    status: selected.status === 'deprecated' ? 'degraded' : 'ready',
+                    value,
+                    ...(selected.replacement === undefined ? {} : { replacement: selected.replacement }),
+                };
+                resolutions.set(capability, resolution);
+                if (selected.status === 'deprecated') {
+                    diagnostics.push({
+                        code: 'CAPABILITY_DEPRECATED',
+                        capability,
+                        routeId: selected.id,
+                        dshVersion: this.dshVersion,
+                        message: `能力 ${capability} 使用已弃用路由 ${selected.id}`,
+                        ...(selected.replacement === undefined ? {} : { replacement: selected.replacement }),
+                    });
+                }
+            }
+            catch (error) {
+                const reason = `${selected.id} 创建失败: ${errorMessage(error)}`;
+                resolutions.set(capability, unavailable(capability, this.dshVersion, reason));
+                diagnostics.push({ code: 'CAPABILITY_CREATE_FAILED', capability, routeId: selected.id, dshVersion: this.dshVersion, message: reason });
+            }
+        }
+        this.profile = createCapabilityProfile(this.dshVersion, this.runtime, resolutions, diagnostics);
+        return this.profile;
+    }
+    getProfile(context) {
+        return this.resolve(context);
+    }
+    require(profile, capability) {
+        const resolution = profile.capabilities.get(capability);
+        if (resolution?.value === undefined || resolution.status === 'unavailable') {
+            throw new DshCapabilityRegistryError('CAPABILITY_UNAVAILABLE', resolution?.reason ?? `能力不可用: ${capability}`, capability);
+        }
+        return resolution.value;
+    }
+    explain(profile, capability) {
+        if (capability === undefined)
+            return profile.diagnostics;
+        return profile.diagnostics.filter((item) => item.capability === capability);
+    }
+}
+function validateRoute(route) {
+    if (route.id.trim() === '' || route.capability === undefined || route.supportedDsh.trim() === '') {
+        throw new DshCapabilityRegistryError('CAPABILITY_INVALID_ROUTE', '能力路由必须包含 id、capability 和 supportedDsh');
+    }
+    if (!Number.isFinite(route.priority))
+        throw new DshCapabilityRegistryError('CAPABILITY_INVALID_ROUTE', `能力路由优先级非法: ${route.id}`, route.capability);
+    if (typeof route.detect !== 'function' || typeof route.create !== 'function')
+        throw new DshCapabilityRegistryError('CAPABILITY_INVALID_ROUTE', `能力路由缺少探测或工厂: ${route.id}`, route.capability);
+}
+function routeRank(route) {
+    return route.priority + (route.status === 'supported' ? 1_000_000 : 0);
+}
+function unavailable(capability, dshVersion, reason) {
+    return { capability, dshVersion, status: 'unavailable', reason };
+}
+function isVersionInRange(version, range) {
+    const match = /^>=([^ ]+) <=([^ ]+)$/u.exec(range);
+    if (match === null)
+        return false;
+    const actual = parseVersion(version);
+    const minimum = parseVersion(match[1]);
+    const maximum = parseVersion(match[2]);
+    if (actual === undefined || minimum === undefined || maximum === undefined)
+        return false;
+    return compareVersions(actual, minimum) >= 0 && compareVersions(actual, maximum) <= 0;
+}
+function parseVersion(value) {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/u.exec(value);
+    if (match === null)
+        return undefined;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        pre: match[4] === undefined ? [] : match[4].split('.').map((part) => /^\d+$/u.test(part) ? Number(part) : part),
+    };
+}
+function compareVersions(left, right) {
+    for (const key of ['major', 'minor', 'patch']) {
+        if (left[key] !== right[key])
+            return left[key] - right[key];
+    }
+    if (left.pre.length === 0 && right.pre.length > 0)
+        return 1;
+    if (left.pre.length > 0 && right.pre.length === 0)
+        return -1;
+    for (let index = 0; index < Math.max(left.pre.length, right.pre.length); index += 1) {
+        const a = left.pre[index];
+        const b = right.pre[index];
+        if (a === undefined)
+            return -1;
+        if (b === undefined)
+            return 1;
+        if (a === b)
+            continue;
+        if (typeof a === 'number' && typeof b === 'string')
+            return -1;
+        if (typeof a === 'string' && typeof b === 'number')
+            return 1;
+        return a < b ? -1 : 1;
+    }
+    return 0;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=registry.js.map

package/data/build/dist/dsh-capabilities/routes.d.ts

@@ -0,0 +1,10 @@
+import { DshCapabilityRegistry } from './registry.js';
+import type { DshCapabilityRuntime } from './types.js';
+/**
+ * 注册 Codingns4DSH 当前实际消费的 DSH 服务能力。
+ *
+ * 探测只检查结构，不读取版本字符串；版本范围由 Registry 统一处理，避免
+ * 业务模块在运行时继续堆叠 if (version >= ...)。
+ */
+export declare function createDshCapabilityRegistry(dshVersion: string, runtime: DshCapabilityRuntime, context: unknown): DshCapabilityRegistry;
+//# sourceMappingURL=routes.d.ts.map

package/data/build/dist/dsh-capabilities/routes.js

@@ -0,0 +1,34 @@
+import { DshCapabilityRegistry } from './registry.js';
+/**
+ * 注册 Codingns4DSH 当前实际消费的 DSH 服务能力。
+ *
+ * 探测只检查结构，不读取版本字符串；版本范围由 Registry 统一处理，避免
+ * 业务模块在运行时继续堆叠 if (version >= ...)。
+ */
+export function createDshCapabilityRegistry(dshVersion, runtime, context) {
+    const registry = new DshCapabilityRegistry(dshVersion, runtime);
+    const value = context;
+    const rangeLegacy = '>=0.1.5-rc.3 <=0.1.6';
+    const rangeModern = '>=0.1.7-rc.2 <=0.1.7-rc.2';
+    const add = (route) => registry.register(route);
+    if (runtime === 'host') {
+        add({ id: 'settings-scope', capability: 'settings.store', supportedDsh: rangeLegacy, runtime, priority: 10, status: 'supported', introducedIn: '0.1.5-rc.3', detect: (ctx) => typeof ctx.settings?.register === 'function', create: (ctx) => ctx.settings });
+        add({ id: 'config-settings', capability: 'settings.store', supportedDsh: rangeModern, runtime, priority: 20, status: 'supported', introducedIn: '0.1.7-rc.2', detect: (ctx) => typeof ctx.settings?.describe === 'function' && typeof ctx.settings?.mutate === 'function', create: (ctx) => ctx.settings });
+        add({ id: 'connection-rpc', capability: 'connection.rpc', supportedDsh: rangeLegacy, runtime, priority: 10, status: 'supported', introducedIn: '0.1.5-rc.3', detect: (ctx) => ctx.connection !== undefined, create: (ctx) => ctx.connection });
+        add({ id: 'connection-rpc-peer-aware', capability: 'connection.rpc', supportedDsh: rangeModern, runtime, priority: 20, status: 'supported', introducedIn: '0.1.7-rc.2', detect: (ctx) => ctx.connection !== undefined, create: (ctx) => ctx.connection });
+        add({ id: 'connection-peer', capability: 'connection.peer', supportedDsh: rangeModern, runtime, priority: 20, status: 'supported', introducedIn: '0.1.7-rc.2', detect: (ctx) => ctx.connection?.peer !== undefined, create: (ctx) => ctx.connection.peer });
+        add({ id: 'remote-result', capability: 'typert.remote', supportedDsh: '>=0.1.5-rc.3 <=0.1.7-rc.2', runtime, priority: 10, status: 'supported', introducedIn: '0.1.5-rc.3', detect: (ctx) => ctx.remote !== undefined, create: (ctx) => ctx.remote });
+    }
+    else {
+        add({ id: 'settings-scope', capability: 'settings.store', supportedDsh: rangeLegacy, runtime, priority: 10, status: 'supported', introducedIn: '0.1.5-rc.3', detect: (ctx) => typeof ctx.settingsScope?.bind === 'function', create: (ctx) => ctx.settingsScope });
+        add({ id: 'config-form', capability: 'settings.store', supportedDsh: rangeModern, runtime, priority: 20, status: 'supported', introducedIn: '0.1.7-rc.2', detect: (ctx) => typeof ctx.configForms?.get === 'function', create: (ctx) => ctx.configForms });
+        add({ id: 'icon-primitives', capability: 'ui.icon.plus', supportedDsh: '>=0.1.5-rc.3 <=0.1.7-rc.2', runtime, priority: 10, status: 'supported', introducedIn: '0.1.5-rc.3', detect: () => value.primitives !== undefined, create: () => value.primitives });
+        add({ id: 'locale-runtime', capability: 'locale.runtime', supportedDsh: '>=0.1.5-rc.3 <=0.1.7-rc.2', runtime, priority: 10, status: 'supported', introducedIn: '0.1.5-rc.3', detect: (ctx) => ctx.locale !== undefined, create: (ctx) => ctx.locale });
+        add({ id: 'theme-runtime', capability: 'theme.runtime', supportedDsh: '>=0.1.5-rc.3 <=0.1.7-rc.2', runtime, priority: 10, status: 'supported', introducedIn: '0.1.5-rc.3', detect: (ctx) => ctx.theme !== undefined, create: (ctx) => ctx.theme });
+        add({ id: 'conversation-events', capability: 'conversation.tool-call', supportedDsh: '>=0.1.5-rc.3 <=0.1.7-rc.2', runtime, priority: 10, status: 'supported', introducedIn: '0.1.5-rc.3', detect: (ctx) => ctx.uiConversation !== undefined, create: (ctx) => ctx.uiConversation });
+        add({ id: 'sidebar-right', capability: 'sidebar.right', supportedDsh: '>=0.1.5-rc.3 <=0.1.7-rc.2', runtime, priority: 10, status: 'supported', introducedIn: '0.1.5-rc.3', detect: (ctx) => ctx.sidebarRight !== undefined, create: (ctx) => ctx.sidebarRight });
+        add({ id: 'remote-result', capability: 'typert.remote', supportedDsh: '>=0.1.5-rc.3 <=0.1.7-rc.2', runtime, priority: 10, status: 'supported', introducedIn: '0.1.5-rc.3', detect: (ctx) => ctx.remote !== undefined, create: (ctx) => ctx.remote });
+    }
+    return registry;
+}
+//# sourceMappingURL=routes.js.map

package/data/build/dist/dsh-capabilities/settings-store.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Codingns4DSH 内部设置存储契约。
+ *
+ * 业务模块只依赖这个最小接口，不直接依赖 DSH 的 SettingsScope 或未来的
+ * ConfigForm。不同 DSH 版本的读写、revision 和订阅语义都在边界适配器中收敛。
+ */
+export interface CodingNsSettingsSnapshot<T> {
+    readonly value: T | undefined;
+    readonly revision: number | undefined;
+    readonly writable: boolean;
+    readonly status: 'loading' | 'ready' | 'unavailable';
+}
+export interface CodingNsSettingsOperation {
+    readonly op: 'set' | 'unset';
+    readonly path: readonly string[];
+    readonly value?: unknown;
+}
+export interface CodingNsSettingsStore<T> {
+    getSnapshot(): CodingNsSettingsSnapshot<T>;
+    subscribe(listener: () => void): () => void;
+    mutate(operations: readonly CodingNsSettingsOperation[], expectedRevision?: number): Promise<boolean>;
+    set(field: string, value: unknown): Promise<boolean>;
+    unset(field: string): Promise<boolean>;
+    load?(): Promise<void>;
+    dispose?(): void | Promise<void>;
+}
+/** 将 DSH 两代写入结果统一成内部成功布尔值。 */
+export declare function accepted(write: Promise<void | boolean>): Promise<boolean>;
+//# sourceMappingURL=settings-store.d.ts.map

package/data/build/dist/dsh-capabilities/settings-store.js

@@ -0,0 +1,5 @@
+/** 将 DSH 两代写入结果统一成内部成功布尔值。 */
+export function accepted(write) {
+    return write.then((result) => result !== false);
+}
+//# sourceMappingURL=settings-store.js.map

package/data/build/dist/dsh-capabilities/types.d.ts

@@ -0,0 +1,50 @@
+/** DSH 宿主能力的稳定标识。业务模块只依赖这些标识，不直接依赖 DSH 版本。 */
+export type DshCapabilityId = 'settings.store' | 'connection.rpc' | 'connection.peer' | 'ui.icon.plus' | 'ui.icon.chevron' | 'locale.runtime' | 'theme.runtime' | 'conversation.tool-call' | 'sidebar.right' | 'typert.remote';
+export type DshCapabilityRuntime = 'host' | 'client';
+export type DshCapabilityRouteStatus = 'supported' | 'deprecated';
+export type DshCapabilityResolutionStatus = 'ready' | 'degraded' | 'unavailable';
+export interface DshCapabilityDiagnostic {
+    readonly code: string;
+    readonly capability: DshCapabilityId;
+    readonly routeId?: string;
+    readonly dshVersion: string;
+    readonly message: string;
+    readonly replacement?: DshCapabilityId;
+    readonly featureNames?: readonly string[];
+}
+export interface DshCapabilityRoute<T> {
+    readonly id: string;
+    readonly capability: DshCapabilityId;
+    readonly supportedDsh: string;
+    readonly runtime: DshCapabilityRuntime;
+    readonly priority: number;
+    readonly detect: (context: unknown) => boolean;
+    readonly create: (context: unknown) => T;
+    readonly status: DshCapabilityRouteStatus;
+    readonly introducedIn: string;
+    readonly removableAfter?: string;
+    readonly replacement?: DshCapabilityId;
+}
+export interface DshCapabilityResolution<T = unknown> {
+    readonly capability: DshCapabilityId;
+    readonly routeId?: string;
+    readonly dshVersion: string;
+    readonly status: DshCapabilityResolutionStatus;
+    readonly value?: T;
+    readonly reason?: string;
+    readonly replacement?: DshCapabilityId;
+}
+export interface DshCapabilityProfile {
+    readonly dshVersion: string;
+    readonly runtime: DshCapabilityRuntime;
+    readonly capabilities: ReadonlyMap<DshCapabilityId, DshCapabilityResolution>;
+    readonly diagnostics: readonly DshCapabilityDiagnostic[];
+    readonly frozenAt: number;
+}
+export interface FeatureCapabilityRequirement {
+    readonly capability: DshCapabilityId;
+    readonly required: boolean;
+    readonly fallback?: 'disable' | 'degrade' | 'error';
+}
+export declare function createCapabilityProfile(dshVersion: string, runtime: DshCapabilityRuntime, capabilities: ReadonlyMap<DshCapabilityId, DshCapabilityResolution>, diagnostics: readonly DshCapabilityDiagnostic[]): DshCapabilityProfile;
+//# sourceMappingURL=types.d.ts.map

package/data/build/dist/dsh-capabilities/types.js

@@ -0,0 +1,23 @@
+export function createCapabilityProfile(dshVersion, runtime, capabilities, diagnostics) {
+    return Object.freeze({
+        dshVersion,
+        runtime,
+        capabilities: freezeMap(capabilities),
+        diagnostics: Object.freeze([...diagnostics]),
+        frozenAt: Date.now(),
+    });
+}
+/** Map 的只读视图，避免 Object.freeze(Map) 仍可通过 set() 修改。 */
+function freezeMap(source) {
+    const map = new Map(source);
+    const view = new Proxy(map, {
+        get(target, property, receiver) {
+            if (property === 'set' || property === 'delete' || property === 'clear')
+                return undefined;
+            const value = Reflect.get(target, property, target);
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+    });
+    return Object.freeze(view);
+}
+//# sourceMappingURL=types.js.map

package/data/build/dist/features/registry.d.ts

@@ -1,5 +1,6 @@
 import type { FeatureDescriptor, FeatureDisposer, FeatureModule, FeatureResourceScope, FeatureState } from '../shared/contracts/feature.js';
-export type FeatureRegistryErrorCode = 'FEATURE_INVALID_DESCRIPTOR' | 'FEATURE_ALREADY_REGISTERED' | 'FEATURE_NOT_FOUND' | 'FEATURE_DEPENDENCY_MISSING' | 'FEATURE_DEPENDENCY_CYCLE' | 'FEATURE_START_FAILED' | 'FEATURE_DISPOSE_FAILED' | 'FEATURE_STATE_INVALID';
+import type { DshCapabilityDiagnostic, DshCapabilityProfile } from '../dsh-capabilities/types.js';
+export type FeatureRegistryErrorCode = 'FEATURE_INVALID_DESCRIPTOR' | 'FEATURE_ALREADY_REGISTERED' | 'FEATURE_NOT_FOUND' | 'FEATURE_DEPENDENCY_MISSING' | 'FEATURE_DEPENDENCY_CYCLE' | 'FEATURE_START_FAILED' | 'FEATURE_DISPOSE_FAILED' | 'FEATURE_STATE_INVALID' | 'FEATURE_CAPABILITY_MISSING';
 export declare class FeatureRegistryError extends Error {
     readonly code: FeatureRegistryErrorCode;
     readonly featureName: string | null;
@@ -12,6 +13,7 @@ export interface FeatureSnapshot {
     runtime: FeatureDescriptor['runtime'];
     dependencies: readonly string[];
     reason: string | null;
+    capabilities: readonly DshCapabilityDiagnostic[];
 }
 /**
  * 管理功能模块的依赖、状态和资源所有权。
@@ -35,10 +37,12 @@ export declare class FeatureResourceScopeImpl implements FeatureResourceScope {
  */
 export declare class FeatureRegistry<S = unknown, M extends FeatureModule<S> = FeatureModule<S>> {
     private readonly services;
+    private readonly capabilityProfile?;
     private readonly records;
     private readonly operations;
+    private reconcileOperation;
     /** @param services - 每个模块在 start 时通过 context.services 取用的服务集合。 */
-    constructor(services: S);
+    constructor(services: S, capabilityProfile?: DshCapabilityProfile | undefined);
     register(module: M): void;
     registerMany(modules: readonly M[]): void;
     has(name: string): boolean;
@@ -61,12 +65,14 @@ export declare class FeatureRegistry<S = unknown, M extends FeatureModule<S> = F
      * 并发调用按模块串行队列排队，最终状态由最后一次调用决定。
      */
     reconcile(enabledNames: readonly string[]): Promise<void>;
+    private reconcileInternal;
     drain(name: string): Promise<void>;
     dispose(name: string): Promise<void>;
     disable(name: string): Promise<void>;
     /** 把期望集合补齐为含依赖的闭包，避免依赖在停用阶段被误停。 */
     private resolveDesired;
     private startInternal;
+    private checkCapabilities;
     private activeDependents;
     private getRecord;
     private enqueue;

package/data/build/dist/features/registry.js

@@ -1,3 +1,4 @@
+import { debugInfo } from '../shared/debug.js';
 export class FeatureRegistryError extends Error {
     code;
     featureName;
@@ -57,11 +58,14 @@ export class FeatureResourceScopeImpl {
  */
 export class FeatureRegistry {
     services;
+    capabilityProfile;
     records = new Map();
     operations = new Map();
+    reconcileOperation = Promise.resolve();
     /** @param services - 每个模块在 start 时通过 context.services 取用的服务集合。 */
-    constructor(services) {
+    constructor(services, capabilityProfile) {
         this.services = services;
+        this.capabilityProfile = capabilityProfile;
     }
     register(module) {
         validateDescriptor(module?.descriptor);
@@ -76,6 +80,13 @@ export class FeatureRegistry {
             reason: null,
             resources,
             context: { descriptor: module.descriptor, resources, services: this.services },
+            capabilities: [],
+        });
+        traceFeature('registered', {
+            feature: name,
+            runtime: module.descriptor.runtime,
+            dependencies: module.descriptor.dependencies,
+            enabledByDefault: module.descriptor.enabledByDefault,
         });
     }
     registerMany(modules) {
@@ -130,6 +141,7 @@ export class FeatureRegistry {
         };
         for (const name of this.records.keys())
             visit(name);
+        traceFeature('validated', { features: [...this.records.keys()] });
     }
     async start(name) {
         return this.enqueue(name, async () => {
@@ -145,8 +157,18 @@ export class FeatureRegistry {
      * 并发调用按模块串行队列排队，最终状态由最后一次调用决定。
      */
     async reconcile(enabledNames) {
+        const operation = this.reconcileOperation.then(() => this.reconcileInternal(enabledNames), () => this.reconcileInternal(enabledNames));
+        this.reconcileOperation = operation.catch(() => undefined);
+        return operation;
+    }
+    async reconcileInternal(enabledNames) {
         this.validate();
         const desired = this.resolveDesired(enabledNames);
+        traceFeature('reconcile', {
+            requested: enabledNames,
+            desired: [...desired],
+            states: this.list().map((item) => ({ name: item.name, state: item.state, reason: item.reason })),
+        });
         for (const name of this.records.keys()) {
             if (desired.has(name))
                 await this.start(name);
@@ -243,6 +265,7 @@ export class FeatureRegistry {
         const record = this.getRecord(name);
         if (record.state === 'enabled')
             return;
+        traceFeature('start.begin', { feature: name, state: record.state, dependencies: record.module.descriptor.dependencies });
         if (record.state === 'enabling') {
             throw new FeatureRegistryError('FEATURE_STATE_INVALID', `Feature is already enabling: ${name}`, name);
         }
@@ -255,6 +278,13 @@ export class FeatureRegistry {
         starting.add(name);
         for (const dependency of record.module.descriptor.dependencies) {
             await this.enqueue(dependency, () => this.startInternal(dependency, starting));
+            const dependencyRecord = this.getRecord(dependency);
+            if (dependencyRecord.state !== 'enabled') {
+                record.state = 'disabled';
+                record.reason = `依赖模块 ${dependency} 未启用`;
+                traceFeature('start.blocked', { feature: name, dependency, dependencyState: dependencyRecord.state });
+                return;
+            }
         }
         starting.delete(name);
         if (record.resources.disposed) {
@@ -263,10 +293,33 @@ export class FeatureRegistry {
         }
         record.state = 'enabling';
         record.reason = null;
+        const capabilityCheck = this.checkCapabilities(record);
+        record.capabilities = capabilityCheck.diagnostics;
+        traceFeature('start.capabilities', {
+            feature: name,
+            action: capabilityCheck.action,
+            reason: capabilityCheck.reason ?? null,
+            diagnostics: capabilityCheck.diagnostics,
+        });
+        if (capabilityCheck.action === 'disable') {
+            record.state = 'disabled';
+            record.reason = capabilityCheck.reason ?? null;
+            traceFeature('start.disabled', { feature: name, reason: record.reason });
+            return;
+        }
+        if (capabilityCheck.action === 'error') {
+            record.state = 'failed';
+            record.reason = capabilityCheck.reason ?? '能力不可用';
+            traceFeature('start.failed', { feature: name, reason: record.reason });
+            throw new FeatureRegistryError('FEATURE_CAPABILITY_MISSING', record.reason, name);
+        }
+        record.context = { ...record.context, capabilityDiagnostics: record.capabilities };
         try {
+            traceFeature('start.module', { feature: name });
             const returned = await record.module.start(record.context);
             addReturnedDisposer(record.resources, returned);
             record.state = 'enabled';
+            traceFeature('start.enabled', { feature: name });
         }
         catch (error) {
             try {
@@ -277,9 +330,33 @@ export class FeatureRegistry {
             }
             record.state = 'failed';
             record.reason = errorMessage(error);
+            traceFeature('start.failed', { feature: name, reason: record.reason, error: serializeError(error) });
             throw new FeatureRegistryError('FEATURE_START_FAILED', `Failed to start feature ${name}`, name, { cause: error });
         }
     }
+    checkCapabilities(record) {
+        const requirements = record.module.descriptor.requires ?? [];
+        if (requirements.length === 0 || this.capabilityProfile === undefined)
+            return { action: 'start', diagnostics: [] };
+        const diagnostics = [];
+        for (const requirement of requirements) {
+            const resolution = this.capabilityProfile.capabilities.get(requirement.capability);
+            if (resolution?.status !== 'unavailable') {
+                if (resolution?.status === 'degraded')
+                    diagnostics.push(...this.capabilityProfile.diagnostics.filter((item) => item.capability === requirement.capability));
+                continue;
+            }
+            const diagnostic = this.capabilityProfile.diagnostics.find((item) => item.capability === requirement.capability)
+                ?? { code: 'CAPABILITY_UNAVAILABLE', capability: requirement.capability, dshVersion: this.capabilityProfile.dshVersion, message: resolution?.reason ?? `能力不可用: ${requirement.capability}` };
+            diagnostics.push(diagnostic);
+            const fallback = requirement.fallback ?? (requirement.required ? 'error' : 'disable');
+            if (requirement.required || fallback === 'error')
+                return { action: 'error', reason: `${record.module.descriptor.name} 缺少能力 ${requirement.capability}: ${diagnostic.message}`, diagnostics };
+            if (fallback === 'disable')
+                return { action: 'disable', reason: `能力 ${requirement.capability} 不可用，模块已禁用`, diagnostics };
+        }
+        return { action: 'start', diagnostics };
+    }
     activeDependents(name) {
         const result = [];
         for (const record of this.records.values()) {
@@ -308,6 +385,15 @@ export class FeatureRegistry {
         return next;
     }
 }
+function traceFeature(event, details) {
+    debugInfo(`codingns4dsh: feature.${event}`, details);
+}
+function serializeError(error) {
+    if (error instanceof Error) {
+        return { name: error.name, message: error.message, ...(error.stack === undefined ? {} : { stack: error.stack }) };
+    }
+    return { name: typeof error, message: String(error) };
+}
 function validateDescriptor(descriptor) {
     if (!descriptor || typeof descriptor.name !== 'string' || descriptor.name.trim() === '') {
         throw new FeatureRegistryError('FEATURE_INVALID_DESCRIPTOR', 'Feature descriptor requires a non-empty name');
@@ -328,6 +414,22 @@ function validateDescriptor(descriptor) {
         && (typeof descriptor.minimumDshVersion !== 'string' || descriptor.minimumDshVersion.trim() === '')) {
         throw new FeatureRegistryError('FEATURE_INVALID_DESCRIPTOR', `Feature ${descriptor.name} has invalid minimumDshVersion`, descriptor.name);
     }
+    if (descriptor.requires !== undefined) {
+        if (!Array.isArray(descriptor.requires))
+            throw new FeatureRegistryError('FEATURE_INVALID_DESCRIPTOR', `Feature ${descriptor.name} has invalid requires`, descriptor.name);
+        const seen = new Set();
+        for (const requirement of descriptor.requires) {
+            if (requirement === undefined || typeof requirement.capability !== 'string' || requirement.capability.trim() === '' || typeof requirement.required !== 'boolean') {
+                throw new FeatureRegistryError('FEATURE_INVALID_DESCRIPTOR', `Feature ${descriptor.name} has invalid capability requirement`, descriptor.name);
+            }
+            if (seen.has(requirement.capability))
+                throw new FeatureRegistryError('FEATURE_INVALID_DESCRIPTOR', `Feature ${descriptor.name} has duplicate capability requirement`, descriptor.name);
+            seen.add(requirement.capability);
+            if (requirement.fallback !== undefined && !['disable', 'degrade', 'error'].includes(requirement.fallback)) {
+                throw new FeatureRegistryError('FEATURE_INVALID_DESCRIPTOR', `Feature ${descriptor.name} has invalid capability fallback`, descriptor.name);
+            }
+        }
+    }
     if (!Array.isArray(descriptor.dependencies) || descriptor.dependencies.some((dependency) => typeof dependency !== 'string' || dependency.trim() === '')) {
         throw new FeatureRegistryError('FEATURE_INVALID_DESCRIPTOR', `Feature ${descriptor.name} has invalid dependencies`, descriptor.name);
     }
@@ -374,6 +476,7 @@ function snapshot(record) {
         runtime: record.module.descriptor.runtime,
         dependencies: [...record.module.descriptor.dependencies],
         reason: record.reason,
+        capabilities: [...record.capabilities],
     };
 }
 function errorMessage(error) {

package/data/build/dist/host/auth-session.d.ts

@@ -1,5 +1,5 @@
 import type { AuthDeviceManagementSnapshotDto, CodingNsAuthLoginResult, CodingNsAuthSessionSnapshot, HostBindRequest, LoginByEmailRequest, TunnelBindingSummary } from '../shared/contracts/auth.js';
-import type { CodingNsControlApiClient } from './control-api-client.js';
+import { type CodingNsControlApiClient } from './control-api-client.js';
 import type { RelaySignalingTicketResponse } from '../shared/contracts/signaling.js';
 import type { CodingNsCredentialStore } from './credential-store.js';
 /**
@@ -13,6 +13,7 @@ export declare class CodingNsAuthSession {
     private state;
     private accessToken;
     private credential;
+    private refreshPromise;
     constructor(client: CodingNsControlApiClient, credentials: CodingNsCredentialStore, controlBaseUrl: string);
     snapshot(): CodingNsAuthSessionSnapshot;
     /**
@@ -22,10 +23,16 @@ export declare class CodingNsAuthSession {
     getAccessToken(): string | null;
     /** 仅供 Host 内部设备运行时调用，Client 不会拿到控制面客户端。 */
     getControlClient(): CodingNsControlApiClient;
+    /**
+     * 执行需要 access token 的请求；服务端拒绝旧 token 时只续期一次并重试。
+     * refresh token 仍然只留在 Host，调用方无需复制认证恢复逻辑。
+     */
+    withAccessToken<T>(operation: (accessToken: string) => Promise<T>): Promise<T>;
     /** 使用保存的 refresh token 恢复会话；没有凭据时保持 logged_out。 */
     restore(): Promise<CodingNsAuthSessionSnapshot>;
     login(request: LoginByEmailRequest): Promise<CodingNsAuthLoginResult>;
     refresh(): Promise<CodingNsAuthSessionSnapshot>;
+    private refreshInternal;
     logout(): Promise<void>;
     getDevices(): Promise<AuthDeviceManagementSnapshotDto>;
     listHostBindings(): Promise<TunnelBindingSummary[]>;