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

package/lib/configuration/runtime.js

@@ -0,0 +1,1100 @@
+import { credentialRef } from '@deepseek-ai/dsh-credentials';
+import z from '@deepseek-ai/schemastery';
+import { setTimeout as delay } from 'node:timers/promises';
+import { SEMI2_RUNTIME_SERVICE, } from '../contract.js';
+import { compileBoot, connectionApiKeyEnv, connectionRoute, providerProfile, remapSelections, } from './compile.js';
+import { clearConnection, connectionOf, resolveConnectionFields, storeConnection, } from './credentials.js';
+import { ConfigurationError, consoleEndpoint, postGraphql, RUNTIME_BOOT_DOCUMENT, RUNTIME_SKILL_FILES_DOCUMENT, RUNTIME_WORKSPACE_PROJECTS_DOCUMENT, } from './graphql.js';
+import { exchangeCnbToken, loginToConsole } from './login.js';
+import { STATUS_FIELDS, statusFields } from './status.js';
+import { matchProject, workspaceSlug } from './workspace.js';
+import { canonicalPath, installWorkspaceFeed, pendingEntry, persistedWorkspaces, trackedWorkspaces, WorkspaceBook, } from './workspaces.js';
+/** 等运行面契约出现的上限；超时按宿主直跑（无适配器）处理。 */
+const CONTRACT_TIMEOUT_MS = 5_000;
+const CONTRACT_POLL_MS = 25;
+const CREDENTIAL_TRIES = 10;
+const CREDENTIAL_INTERVAL_MS = 150;
+const NAMESPACE_TRIES = 40;
+const NAMESPACE_INTERVAL_MS = 50;
+/** 自铸路由的键形状（semi2-<32 hex>）：归属表里没有记录时按名字兜底认领。 */
+const LEGACY_OWNED_PROVIDER = /^semi2-[\da-f]{32}$/;
+/** 设置页 Semi2 分区的命名空间：reload 由 UI 写（触发重载），status 由本插件写（展示）。 */
+const SETTINGS_NAMESPACE = 'semi2';
+/**
+ * 本插件写过什么的归属表。预设连接的路由键就是 dsh 的提供方 id（anthropic / zai …），
+ * 光看名字分不清是插件的还是用户自己写的 profile；密钥与 llm-deepseek 覆盖同理。
+ * 服务端撤掉的本地要跟着撤，而「撤」的前提是知道哪几条是自己写的，所以这些事实单独存一份。
+ * 单列命名空间而不是塞进 `semi2`：后者由 publishStatus 走 replace 整体覆盖。
+ */
+const OWNED_NAMESPACE = 'semi2-providers';
+/**
+ * 工作区 → git 项目映射的持久化命名空间。映射是本地事实（换台机器要重解析），
+ * 只存目录与解析结果；单列命名空间的理由同归属表——`semi2` 由 publishStatus 整体覆盖。
+ */
+const WORKSPACES_NAMESPACE = 'semi2-workspaces';
+const OWNED_SCHEMA = z.object({
+    routes: z.array(z.string()).default([]),
+    credentials: z.array(z.string()).default([]),
+    deepseek: z.boolean().default(false),
+});
+/** 工作区映射的 settings schema（空值统一落空串，读侧再归一为 null）。 */
+const WORKSPACES_SCHEMA = z.object({
+    entries: z
+        .array(z.object({
+        path: z.string().default(''),
+        title: z.string().default(''),
+        slug: z.string().default(''),
+        projectId: z.string().default(''),
+        name: z.string().default(''),
+        syncedAt: z.string().default(''),
+    }))
+        .default([]),
+});
+/** 本插件在 `llm-deepseek` 段写过的键：撤销只删这几个，不碰同段里用户自己加的键。 */
+const DEEPSEEK_OWNED_KEYS = ['apiKeyEnv', 'baseURL', 'models'];
+/** 从既有 provider profile 上取密钥引用名（回收归属表外的自铸路由时连带清理其密钥）。 */
+function apiKeyEnvOf(profile) {
+    const value = profile?.apiKeyEnv;
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+/** 状态字段的 settings schema（键集 = status.ts 的 STATUS_FIELDS）。 */
+const STATUS_SCHEMA = Object.fromEntries(STATUS_FIELDS.map(key => [key, z.string().default('')]));
+function initialState(connect, consoleUrl, workspaces = []) {
+    return {
+        status: connect ? 'loading' : 'local',
+        loadedAt: null,
+        error: null,
+        consoleUrl,
+        identity: null,
+        model: null,
+        // null = 没拿到权威技能目录（≠ 空目录）：provider 据此不得谎报权威空。
+        skills: null,
+        projects: [],
+        workspaces,
+    };
+}
+function text(value) {
+    const trimmed = value?.trim();
+    return trimmed === undefined || trimmed === '' ? undefined : trimmed;
+}
+/** 持久化段 → 工作区条目；形状不合的行直接丢弃，不让坏数据拖垮启动。 */
+function readWorkspaces(settings) {
+    const value = settings.describe().find(entry => entry.ns === WORKSPACES_NAMESPACE)?.value ??
+        {};
+    const rows = Array.isArray(value.entries) ? value.entries : [];
+    const entries = [];
+    for (const row of rows) {
+        if (row === null || typeof row !== 'object' || Array.isArray(row))
+            continue;
+        const record = row;
+        const path = typeof record.path === 'string' ? record.path.trim() : '';
+        if (path === '')
+            continue;
+        entries.push({
+            path,
+            title: text(typeof record.title === 'string' ? record.title : undefined) ?? path,
+            slug: text(typeof record.slug === 'string' ? record.slug : undefined) ?? null,
+            projectId: text(typeof record.projectId === 'string' ? record.projectId : undefined) ??
+                null,
+            name: text(typeof record.name === 'string' ? record.name : undefined) ?? null,
+            syncedAt: text(typeof record.syncedAt === 'string' ? record.syncedAt : undefined) ??
+                null,
+            implicit: false,
+        });
+    }
+    return entries;
+}
+/** 契约是否自带连接凭据（自带即只读：宿主不可用登录覆盖）。 */
+function hasContractCredentials(credentials) {
+    return (text(credentials?.configUrl) !== undefined ||
+        text(credentials?.accessToken) !== undefined);
+}
+function codeOf(error) {
+    return error instanceof ConfigurationError
+        ? error.code
+        : 'CONFIG_APPLY_FAILED';
+}
+/**
+ * 附件清单：字段类型刻意放宽成可选——codegen 出来的节点声明它是非空数组，读取侧写不出判空，
+ * 而 hub 未下发这个字段时必须退化成空清单，不能因为附件缺席就抹掉整条技能。
+ */
+function fileFactsOf(node) {
+    const files = node.files;
+    if (files === null || files === undefined)
+        return [];
+    return files.map(file => ({ ...file }));
+}
+export class Semi2ConfigRuntime {
+    ctx;
+    current;
+    settled;
+    /** 构造时冻结的进程 env：用于项目反解兜底（CNB_REPO_SLUG）与回环 http 判定（NODE_ENV）。 */
+    environment;
+    /** 当前连接凭据（契约或 dsh credentials 存储）；未配置为 null。 */
+    connection = null;
+    /** 运行面契约：适配器 provide 优先，缺席 = 宿主直跑；未解析为 undefined。 */
+    contract;
+    contractResolved = false;
+    contractTimeoutMs;
+    settings;
+    /** 最近一次成功编译的模型目录（headless 角色选择按它解析）。 */
+    compiled = null;
+    defaultModelId = null;
+    reloadToken = '';
+    /** 工作区登记表（dsh 工作区 → git 项目映射）。 */
+    book = new WorkspaceBook();
+    /** hub 明确没有的 slug（不在可读范围内）：负缓存，免得每次会话都去问一遍。 */
+    missingProjects = new Set();
+    /** 工作区同步串行队列：feed 帧与「同步」可能并发，串起来才不会互相覆盖。 */
+    workspaceTail = Promise.resolve();
+    resolveSettled;
+    constructor(ctx, environment, options = {}) {
+        this.ctx = ctx;
+        this.current = initialState(false, null);
+        this.environment = { ...environment };
+        this.contractTimeoutMs = options.contractTimeoutMs ?? CONTRACT_TIMEOUT_MS;
+        const settled = Promise.withResolvers();
+        this.settled = settled.promise;
+        this.resolveSettled = settled.resolve;
+    }
+    get state() {
+        return this.current;
+    }
+    get ready() {
+        return this.settled;
+    }
+    /**
+     * 解析连接凭据；非 CNB 面先把启动环境的连接令牌摘掉再解析。
+     * 那枚令牌只属 CNB 面（`runtimeFromCnbEnv` 从 secret imports 注入的 env 取），宿主 / 容器面认了它
+     * 就再没有登录入口：dsh 的启动环境层只读（set/unset 都被拒）又排在临时存储之前，登录写进去的令牌
+     * 也读不回来。地址不是密钥、还是登录表单的预填来源，照旧留给 `SEMI2_CONFIG_URL`。
+     */
+    async connectionFields() {
+        await this.ensureContract();
+        if (this.contract?.platform !== 'cnb') {
+            delete process.env.SEMI2_ACCESS_TOKEN;
+            delete this.environment.SEMI2_ACCESS_TOKEN;
+        }
+        return resolveConnectionFields(this.ctx, this.contract, this.environment);
+    }
+    /** 契约解析完成后才给出答案；缺席即宿主直跑。 */
+    get platform() {
+        if (!this.contractResolved)
+            return null;
+        return this.contract?.platform ?? 'host';
+    }
+    async reload() {
+        // 只在无凭据时重解析：令牌已从进程 env 删除，this.connection 才是权威副本（登录/登出显式重解析）。
+        const fields = await this.connectionFields();
+        if (this.connection === null)
+            this.connection = await this.exchangeCnbCredential(connectionOf(fields));
+        if (this.connection === null) {
+            this.publish(initialState(false, fields.url?.value ?? null, this.trackedWorkspaces()));
+            this.ctx.emit('semi2/config-updated', this.current);
+            await this.publishStatus();
+            return this.current;
+        }
+        return this.load();
+    }
+    async projectFor(session) {
+        return this.projectForCwd(session.header?.cwd);
+    }
+    /**
+     * 两层解析：已登记工作区按其解析结果取项目；未登记目录回落 git slug，并**按需**问一次
+     * 那一个项目（不拉全量项目表）。未就绪时项目表是空的，答了也是错的。
+     */
+    async projectForCwd(cwd) {
+        if (this.current.status !== 'ready')
+            return null;
+        const directory = cwd?.trim();
+        if (directory !== undefined && directory !== '') {
+            const entry = this.book.get(await canonicalPath(directory));
+            if (entry !== undefined && entry.projectId !== null) {
+                const matched = this.current.projects.find(project => project.id === entry.projectId);
+                if (matched !== undefined)
+                    return matched;
+            }
+        }
+        const slug = await workspaceSlug(directory, this.environment);
+        if (slug === null)
+            return null;
+        const known = matchProject(this.current.projects, slug);
+        if (known !== null)
+            return known;
+        await this.fetchProjects([slug]);
+        return matchProject(this.current.projects, slug);
+    }
+    /** 已登记工作区命中的项目（按 id 去重）：状态展示与技能作用域按它取，没工作区的项目不进这个集合。 */
+    workspaceProjects() {
+        const known = new Map(this.current.projects.map(project => [project.id, project]));
+        const projects = [];
+        const seen = new Set();
+        for (const entry of this.book.entries()) {
+            if (entry.projectId === null || seen.has(entry.projectId))
+                continue;
+            const project = known.get(entry.projectId);
+            if (project === undefined)
+                continue;
+            seen.add(entry.projectId);
+            projects.push(project);
+        }
+        return projects;
+    }
+    /** 状态展示与持久化的工作区集合：未成 git 项目的目录直接忽略（簿记里仍留着等重解析）。 */
+    trackedWorkspaces() {
+        return trackedWorkspaces(this.book.entries());
+    }
+    /**
+     * 技能附件字节：boot 文档只有清单，字节在真正加载该技能时按需取。
+     * 三次降级口径与其余领域一致——可空根字段为 null（领域失败）、传输异常、没连 hub 都返回 null，
+     * 由调用方放弃物化；只有「字段在场且为数组」才算权威答案（空数组 = 没有附件）。
+     */
+    async skillFiles(skillId) {
+        try {
+            const outcome = await this.requestDomain('RuntimeSkillFiles', RUNTIME_SKILL_FILES_DOCUMENT, { skillId });
+            if (outcome.errorCode !== null) {
+                this.warn(`技能附件读取失败（runtimeSkillFiles，${outcome.errorCode}）`);
+                return null;
+            }
+            const files = outcome.data?.runtimeSkillFiles;
+            if (files === null || files === undefined) {
+                this.warn('技能附件读取失败（runtimeSkillFiles 降级），本次不物化资源');
+                return null;
+            }
+            return files.map(file => ({ ...file }));
+        }
+        catch (error) {
+            this.warn(`技能附件读取异常（${codeOf(error)}），本次不物化资源`);
+            return null;
+        }
+    }
+    async selectHeadlessModel(input) {
+        const compiled = this.compiled;
+        if (compiled === null || this.current.status !== 'ready')
+            return;
+        const project = await this.projectFor(input.cwd === undefined ? {} : { header: { cwd: input.cwd } });
+        const roleId = input.workmode
+            ? project?.executeModelId
+            : project?.planModelId;
+        const modelId = roleId ?? this.defaultModelId;
+        const selection = modelId === null ? undefined : compiled.selections.get(modelId);
+        if (selection === undefined)
+            return;
+        const defaultModel = this.ctx.get('agentDefaultModel');
+        if (defaultModel === undefined)
+            return;
+        await defaultModel.saveSelection(selection);
+    }
+    /**
+     * 首次加载；未配凭据或失败只落到 state.error，绝不 throw，也不注入任何配置。
+     * 未登录（只有地址、没有令牌）时仍回报地址：登录表单靠它预填。
+     */
+    async start() {
+        try {
+            const settings = await this.settingsService();
+            this.settings = settings;
+            if (settings !== undefined) {
+                this.installStatusSection(settings);
+                // 上次的映射先恢复：headless 面无 dsh 工作区服务，这份本地事实就是全部列表。
+                this.book.restore(readWorkspaces(settings));
+            }
+            this.installWorkspaceSubscription();
+            await this.ensureContract();
+            this.ensureImplicitWorkspace();
+            const { connection, consoleUrl } = await this.resolveConnectionWithRetry();
+            this.connection = await this.exchangeCnbCredential(connection);
+            if (this.connection === null)
+                this.publish(initialState(false, consoleUrl, this.trackedWorkspaces()));
+            else
+                await this.load(settings);
+            await this.publishStatus();
+        }
+        finally {
+            this.resolveSettled();
+        }
+    }
+    async service(key) {
+        return new Promise((resolve) => {
+            this.ctx.inject([key], (injected) => {
+                resolve(injected.get(key));
+            });
+        });
+    }
+    /** settings 服务缺失（非 web/headless 宿主）时不阻塞启动，5s 后放弃。 */
+    async settingsService() {
+        const { promise, resolve } = Promise.withResolvers();
+        const timer = globalThis.setTimeout(() => { resolve(undefined); }, 5_000);
+        this.ctx.inject(['settings'], (injected) => {
+            globalThis.clearTimeout(timer);
+            resolve(injected.get('settings'));
+        });
+        return promise;
+    }
+    /** 运行面契约只解析一次（适配器在 apply 里同步 provide）。 */
+    async ensureContract() {
+        if (this.contractResolved)
+            return;
+        this.contract = await this.resolveContract();
+        this.contractResolved = true;
+    }
+    async resolveContract() {
+        const deadline = Date.now() + this.contractTimeoutMs;
+        for (;;) {
+            // 适配器 apply 是长跑 async（等配置 settle），其 fiber 尚未 active：严格查找一直 undefined，
+            // 故不用 ctx.inject 而直接 ctx.get(strict=false) 轮询（服务注册本身是同步的）。
+            const contract = this.ctx.get(SEMI2_RUNTIME_SERVICE, false);
+            if (contract !== undefined)
+                return contract;
+            if (Date.now() >= deadline)
+                return undefined;
+            await delay(CONTRACT_POLL_MS);
+        }
+    }
+    /** credentials 存储首次读盘可能晚于插件启动：有界窗口内重试，仍无凭据即按「未配置」处理。 */
+    async resolveConnectionWithRetry() {
+        let consoleUrl = null;
+        for (let attempt = 0; attempt < CREDENTIAL_TRIES; attempt += 1) {
+            const fields = await this.connectionFields();
+            consoleUrl = fields.url?.value ?? consoleUrl;
+            const connection = connectionOf(fields);
+            if (connection !== null)
+                return { connection, consoleUrl };
+            if (attempt < CREDENTIAL_TRIES - 1)
+                await delay(CREDENTIAL_INTERVAL_MS);
+        }
+        return { connection: null, consoleUrl };
+    }
+    /**
+     * CNB 面：把平台注入的短期 CNB_TOKEN 换成 hub 用户密钥（一次兑换，之后一律用换来的密钥）。
+     * 兑换失败按现有降级口径：本次不注入配置，不阻断会话。其它面 / 登录态原样返回。
+     */
+    async exchangeCnbCredential(connection) {
+        if (connection === null ||
+            this.contract?.platform !== 'cnb' ||
+            connection.source !== 'runtime')
+            return connection;
+        try {
+            const exchanged = await exchangeCnbToken({
+                url: connection.url,
+                token: connection.token,
+            });
+            return {
+                url: connection.url,
+                token: exchanged.token,
+                source: 'cnb-exchange',
+            };
+        }
+        catch (error) {
+            this.warn(`CNB 令牌兑换失败（${codeOf(error)}），本次不注入配置`);
+            return null;
+        }
+    }
+    installStatusSection(settings) {
+        // 用户写入只触发 onChange（setSource 是组合层），故在 onChange 里读有效值比较。
+        this.reloadToken = this.readReloadToken();
+        settings.installSection(this.ctx, SETTINGS_NAMESPACE, z.object({
+            reload: z.string().default(''),
+            ...STATUS_SCHEMA,
+        }), Object.fromEntries(['reload', ...STATUS_FIELDS].map(key => [key, ''])), {
+            setSource: () => { },
+            onChange: () => {
+                const token = this.readReloadToken();
+                if (token === this.reloadToken)
+                    return;
+                this.reloadToken = token;
+                void this.reload();
+            },
+        });
+        // 归属表由插件自己写、自己读，不暴露给用户；没有它就无法区分
+        // 「上次注入的条目」与「用户自己写的同名条目」。
+        settings.installSection(this.ctx, OWNED_NAMESPACE, OWNED_SCHEMA, {
+            routes: [],
+            credentials: [],
+            deepseek: false,
+        }, { setSource: () => { }, onChange: () => { } });
+        // 工作区映射同理：纯本地事实，用户不编辑（工作区增删在 dsh 自己的工作区面板）。
+        settings.installSection(this.ctx, WORKSPACES_NAMESPACE, WORKSPACES_SCHEMA, {
+            entries: [],
+        }, { setSource: () => { }, onChange: () => { } });
+    }
+    /**
+     * 工作区登记 = dsh 工作区列表变化即同步：新增/改名解析该项目并落库，移除即撤下。
+     * 服务缺席（headless 面）时回调不执行，由隐式条目兜底；配置未就绪时只记列表、不解析。
+     */
+    installWorkspaceSubscription() {
+        installWorkspaceFeed(this.ctx, {
+            baseline: items => this.enqueueWorkspace(async () => {
+                this.book.applyBaseline(items);
+                if (this.current.status !== 'ready') {
+                    this.publishWorkspaces(false);
+                    return;
+                }
+                await this.syncWorkspaces(true);
+            }),
+            upsert: view => this.enqueueWorkspace(async () => {
+                this.book.upsertWorkspace(view);
+                if (this.current.status !== 'ready') {
+                    this.publishWorkspaces(false);
+                    return;
+                }
+                await this.syncWorkspace(view.path, true);
+            }),
+            remove: workspaceId => this.enqueueWorkspace(async () => {
+                this.book.removeWorkspace(workspaceId);
+                await this.persistWorkspaces();
+                this.publishWorkspaces(true);
+            }),
+        }, (message) => {
+            this.warn(message);
+        });
+    }
+    /**
+     * headless 面（NPC / 无 web 服务的宿主）没有 dsh 工作区服务：启动目录就是唯一工作区。
+     * 有服务时不播——基线帧稍后给出权威列表，多一条隐式条目反而会被状态与技能作用域当成真工作区。
+     */
+    ensureImplicitWorkspace() {
+        if (this.ctx.get('workspaceController', false) !== undefined)
+            return;
+        this.book.ensureImplicit(process.cwd());
+    }
+    /** 工作区同步串行：feed 帧与「同步」交错时按到达顺序逐条落定。 */
+    enqueueWorkspace(work) {
+        const next = this.workspaceTail.then(work, work);
+        this.workspaceTail = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    /** 全量工作区解析（启动、「同步」、基线帧共用）：一个都不在列表里时什么都不做。 */
+    async syncWorkspaces(notify) {
+        // 用**簿记全量**解析：忽略过滤是展示/落库口径，拿它当入口会把待解析条目也滤掉。
+        const entries = this.book.entries();
+        if (entries.length === 0)
+            return;
+        await this.applyResolved(entries);
+        await this.persistWorkspaces();
+        this.publishWorkspaces(notify);
+    }
+    /** 单个工作区解析（upsert 帧）：映射失败也要写回 error，UI 才看得出「为什么没同步」。 */
+    async syncWorkspace(path, notify) {
+        const entry = this.book.get(path) ?? pendingEntry(path, path);
+        await this.applyResolved([entry]);
+        await this.persistWorkspaces();
+        this.publishWorkspaces(notify);
+    }
+    async applyResolved(entries) {
+        const slugs = await Promise.all(entries.map(entry => this.lookupSlug(entry.path)));
+        // 只为「本地还没有的 slug」问一次 hub：请求里不会出现没用到的工作区项目。
+        const wanted = [];
+        for (const slug of slugs) {
+            if (slug === null || matchProject(this.current.projects, slug) !== null)
+                continue;
+            wanted.push(slug);
+        }
+        await this.fetchProjects(wanted);
+        entries.forEach((entry, index) => {
+            this.book.set(this.resolveEntry(entry, slugs[index] ?? null));
+        });
+    }
+    /** 反解失败与非 git 目录一样不可映射：只 warn（诊断留日志），条目按未命中处理。 */
+    async lookupSlug(path) {
+        try {
+            return await workspaceSlug(path, this.environment);
+        }
+        catch (error) {
+            this.warn(`工作区 ${path} 反解失败（${codeOf(error)}）`);
+            return null;
+        }
+    }
+    /**
+     * 反解不出 slug（非 git / 无 origin）与 hub 里查无此项目都不算失败：该目录不归
+     * semi2-hub 管——只落 slug 供诊断，项目三件套留空，由 `trackedWorkspaces` 挡在状态外。
+     */
+    resolveEntry(entry, slug) {
+        const base = {
+            ...entry,
+            slug,
+            projectId: null,
+            name: null,
+            syncedAt: new Date().toISOString(),
+        };
+        if (slug === null)
+            return base;
+        const project = matchProject(this.current.projects, slug);
+        if (project === null)
+            return base;
+        return {
+            ...base,
+            projectId: project.id,
+            name: project.name,
+        };
+    }
+    /**
+     * 按 slug 取项目绑定并并入缓存（幂等）：只问点名的 slug，hub 那边再叠一层读范围过滤。
+     * 结果空 = 该 slug 确实不在可读范围内，记进负缓存免得每次会话都重问。
+     */
+    async fetchProjects(slugs) {
+        const wanted = [
+            ...new Set(slugs.map(slug => slug.trim().toLowerCase())),
+        ].filter(slug => slug !== '' && !this.missingProjects.has(slug));
+        if (wanted.length === 0 || this.connection === null)
+            return;
+        try {
+            const outcome = await this.requestDomain('RuntimeWorkspaceProjects', RUNTIME_WORKSPACE_PROJECTS_DOCUMENT, { slugs: wanted });
+            const projects = outcome.data?.runtimeProjects;
+            if (projects === null || projects === undefined) {
+                this.warn('工作区项目读取失败（runtimeProjects），本次按未命中处理');
+                return;
+            }
+            const merged = new Map(this.current.projects.map(project => [project.id, project]));
+            const hit = new Set();
+            for (const project of projects) {
+                merged.set(project.id, project);
+                hit.add(project.slug.toLowerCase());
+            }
+            for (const slug of wanted)
+                if (!hit.has(slug))
+                    this.missingProjects.add(slug);
+            this.publish({ ...this.current, projects: [...merged.values()] });
+        }
+        catch (error) {
+            this.warn(`工作区项目读取失败（${codeOf(error)}）`);
+        }
+    }
+    async persistWorkspaces() {
+        const settings = this.settings;
+        if (settings === undefined)
+            return;
+        try {
+            await this.replaceNamespace(settings, WORKSPACES_NAMESPACE, {
+                entries: persistedWorkspaces(this.trackedWorkspaces()),
+            });
+        }
+        catch (error) {
+            this.warn(`工作区登记写入失败（${codeOf(error)}）`);
+        }
+    }
+    publishWorkspaces(notify) {
+        this.publish({ ...this.current, workspaces: this.trackedWorkspaces() });
+        if (notify)
+            this.ctx.emit('semi2/workspaces-updated', this.current);
+    }
+    readSetting(key) {
+        const entry = this.settings
+            ?.describe()
+            .find(candidate => candidate.ns === SETTINGS_NAMESPACE);
+        const value = entry?.value?.[key];
+        return typeof value === 'string' ? value : '';
+    }
+    readReloadToken() {
+        return this.readSetting('reload');
+    }
+    async publishStatus() {
+        if (this.settings === undefined)
+            return;
+        // 权威写入（replace）：合并 update 无法把字段写回空值；
+        // reload 令牌由 UI 持有，必须原样保留。
+        const section = {
+            ...statusFields(this.current, {
+                credentialSource: this.connection?.source ?? null,
+                platform: this.platform,
+            }),
+            reload: this.readReloadToken(),
+        };
+        try {
+            if (this.settings.replace !== undefined)
+                await this.settings.replace(SETTINGS_NAMESPACE, section);
+            else
+                await this.settings.update(SETTINGS_NAMESPACE, section);
+        }
+        catch {
+            this.warn('设置页状态写入失败');
+        }
+    }
+    async updateNamespace(settings, ns, patch) {
+        await this.writeNamespace(settings, ns, () => settings.update(ns, patch));
+    }
+    /**
+     * 权威写入：把用户段整体替换成给定内容。
+     * `update` 是**递归合并**（dsh-settings 的 mergeLayers），只增不减——服务端撤掉的条目
+     * 会在本地留成残渣，provider 路由尤其致命：目录里已不存在的模型继续可选。
+     * 所以凡是本插件全权决定的段（`llm-pi-ai` 只此一个键）都走替换。
+     */
+    async replaceNamespace(settings, ns, section) {
+        const replace = settings.replace?.bind(settings);
+        if (replace === undefined) {
+            this.warn(`宿主 settings 无 replace，${ns} 退回合并写入：服务端已撤下的条目可能残留`);
+            await this.updateNamespace(settings, ns, section);
+            return;
+        }
+        await this.writeNamespace(settings, ns, () => replace(ns, section));
+    }
+    /** 按路径删除本插件写过的键（合并写入删不掉）。 */
+    async clearKeys(settings, ns, keys) {
+        const mutate = settings.mutate?.bind(settings);
+        if (mutate === undefined) {
+            this.warn(`宿主 settings 无 mutate，${ns} 无法按路径删除：服务端已撤销的覆盖可能残留`);
+            return;
+        }
+        const ops = keys.map(key => ({ op: 'unset', path: [key] }));
+        await this.writeNamespace(settings, ns, () => mutate(ns, ops));
+    }
+    /** 等命名空间注册完成再写（settings 服务与各 bundle 的注册有先后）。 */
+    async writeNamespace(settings, ns, write) {
+        for (let attempt = 0; attempt < NAMESPACE_TRIES; attempt += 1) {
+            if (settings.describe().some(entry => entry.ns === ns)) {
+                await write();
+                return;
+            }
+            await delay(NAMESPACE_INTERVAL_MS);
+        }
+        throw new ConfigurationError('CONFIG_APPLY_FAILED');
+    }
+    /** 读取一次运行配置；整体失败只落 state.error，绝不 throw（start/reload 均可重试）。 */
+    async load(settings) {
+        this.publish({ ...this.current, status: 'loading', error: null });
+        // 重新装配 = 重新问项目：服务端可能刚把这几个项目放回可读范围。
+        this.missingProjects.clear();
+        try {
+            const outcome = await this.fetchBoot();
+            const boot = outcome.data;
+            if (boot === null) {
+                const code = outcome.errorCode ?? 'CONFIG_REQUEST_FAILED';
+                this.warn(`运行配置读取失败（${code}），不做任何注入，dsh 按自身配置运行`);
+                // 连不上 semi2-hub 时一切照旧，失败码留 state.error 供诊断、可重载重试。
+                this.publish({
+                    ...this.current,
+                    status: 'failed',
+                    error: code,
+                    workspaces: this.trackedWorkspaces(),
+                });
+                this.ctx.emit('semi2/config-updated', this.current);
+                // 失败也必须回写设置页：登录成功但同步失败时，错误码是唯一提示（客户端按 error 渲染「最近失败」）。
+                await this.publishStatus();
+                return this.current;
+            }
+            const target = settings ?? (await this.service('settings'));
+            const failures = outcome.errorCode === null ? [] : [outcome.errorCode];
+            const owned = this.readOwned(target);
+            let compiled = null;
+            let next = owned;
+            let staleCredentials = [];
+            try {
+                const applied = await this.applyModels(boot, target, owned);
+                if (applied !== null) {
+                    compiled = applied.compiled;
+                    staleCredentials = applied.staleCredentials;
+                    next = { ...next, routes: applied.routes, deepseek: applied.deepseek };
+                }
+            }
+            catch (error) {
+                failures.push(this.noteFailure('模型目录', error));
+            }
+            try {
+                const refs = await this.applyModelCredentials(boot, compiled !== null, owned, staleCredentials);
+                if (refs !== null)
+                    next = { ...next, credentials: refs };
+            }
+            catch (error) {
+                failures.push(this.noteFailure('模型密钥', error));
+            }
+            // 归属表 = 本轮实际写入的事实；某领域降级时保持上次的值（不动即不回收）。
+            try {
+                await this.updateNamespace(target, OWNED_NAMESPACE, { ...next });
+            }
+            catch (error) {
+                failures.push(this.noteFailure('注入归属表', error));
+            }
+            // 令牌只用于读取，不留给会话子进程；权威副本是 this.connection（reload 复用）。
+            delete process.env.SEMI2_ACCESS_TOKEN;
+            this.compiled = compiled;
+            this.defaultModelId = boot.runtimeDefaultModelId ?? null;
+            this.publish(this.applied(boot, compiled, failures[0] ?? null));
+            // 工作区映射依赖项目表：全局事实先入状态再解析；不发 workspaces 事件——
+            // 紧接着的 config-updated 已会让技能目录缓存失效，两次下发只会白丢两遍缓存。
+            await this.syncWorkspaces(false);
+            this.ctx.emit('semi2/config-updated', this.current);
+            await this.publishStatus();
+            return this.current;
+        }
+        catch (error) {
+            const code = codeOf(error);
+            this.warn(`读取或应用失败（${code}），不做任何注入，dsh 按自身配置运行`);
+            this.publish({
+                ...this.current,
+                status: 'failed',
+                error: code,
+                workspaces: this.trackedWorkspaces(),
+            });
+            this.ctx.emit('semi2/config-updated', this.current);
+            // 同上：失败态不过设置页等于静默，用户只会看到「已登录」然后一片空白。
+            await this.publishStatus();
+            return this.current;
+        }
+    }
+    /** 启动装配：五个用户级领域问题一个文档（项目绑定按工作区另行按需取）。 */
+    fetchBoot() {
+        return this.requestDomain('RuntimeBoot', RUNTIME_BOOT_DOCUMENT);
+    }
+    /**
+     * 运行面读取：身份就是连接凭据换来的用户密钥本人；读取者事实由 `runtimeViewer`
+     * 领域下发（密码登录 / hub 接入密钥 / CNB 令牌兑换都返回服务器里同一账户），请求不带 subject。
+     * operation 名同时选中结果类型，调用侧不必再断言；`variables` 是本操作自己的入参。
+     */
+    async requestDomain(operationName, document, variables = {}) {
+        const connection = this.connection;
+        if (connection === null)
+            throw new ConfigurationError('MISSING_ACCESS_TOKEN');
+        // CNB 面带上环境创建者：hub 用它决定读取身份（密钥只证明来自 CNB 环境）。
+        const creator = text(this.environment.CNB_BUILD_USER_ID);
+        const client = {
+            endpoint: consoleEndpoint(connection.url, this.environment.NODE_ENV),
+            token: connection.token,
+            ...(creator === undefined ? {} : { creator }),
+        };
+        const outcome = await postGraphql(client, {
+            operationName,
+            document,
+            ...(Object.keys(variables).length === 0 ? {} : { variables }),
+        });
+        return {
+            data: outcome.data,
+            errorCode: outcome.errorCode,
+        };
+    }
+    /** `runtimeModels` 降级时返回 null：不动任何模型相关设置，其余领域照常。 */
+    async applyModels(boot, settings, owned) {
+        const models = boot.runtimeModels;
+        if (models === null || models === undefined) {
+            this.warn('模型目录读取失败（runtimeModels），跳过 provider 与默认模型注入');
+            return null;
+        }
+        const compiled = compileBoot(models, boot.runtimeDefaultModelId ?? null);
+        // 路由让位（同名用户 profile）会改路由键：`compiled` 里的选择必须跟着改写，
+        // 否则默认模型会指向不属于我们的 profile。
+        const applied = await this.applyProviders(settings, compiled.providers, owned);
+        const routes = applied.routes;
+        const remapped = remapSelections(compiled, routes);
+        // DEEPSEEK 协议覆盖内置原生适配器：key/endpoint/目录都来自 semi2-hub。
+        // 服务端不给 DEEPSEEK 连接时反向撤销自己写过的覆盖（用户手写的段不动），
+        // 否则会一直留着服务端已下线的 deepseek 模型清单。
+        if (remapped.deepseek !== null)
+            await this.updateNamespace(settings, 'llm-deepseek', {
+                apiKeyEnv: remapped.deepseek.apiKeyEnv,
+                baseURL: remapped.deepseek.baseURL,
+                models: remapped.deepseek.models,
+            });
+        else if (owned.deepseek)
+            await this.clearKeys(settings, 'llm-deepseek', DEEPSEEK_OWNED_KEYS);
+        const final = [...routes.values()];
+        await this.applyDefaultModel(settings, remapped, final, owned);
+        return {
+            compiled: remapped,
+            routes: final,
+            deepseek: remapped.deepseek !== null,
+            staleCredentials: applied.staleCredentials,
+        };
+    }
+    /**
+     * 默认模型：semi2-hub 是唯一来源，总是写（会话内的临时选择记在 session log，不受影响）。
+     *
+     * 服务端不给可用默认模型、且现行默认正指向**本轮被回收**的路由时必须把它让回组合层：
+     * 路由已从 `llm-pi-ai` 撤下，该选择就成了悬空引用，下一轮请求会以 `NO_ADAPTER` 失败
+     * （dsh-llm 的 registration 查不到适配器直接抛）。
+     */
+    async applyDefaultModel(settings, compiled, finalRoutes, owned) {
+        const defaultModel = this.ctx.get('agentDefaultModel', false);
+        if (compiled.defaultModel !== null) {
+            if (defaultModel !== undefined)
+                await defaultModel.saveSelection(compiled.defaultModel);
+            else
+                await this.updateNamespace(settings, 'agent-default-model', compiled.defaultModel);
+            return;
+        }
+        const current = this.currentSelection(settings);
+        const dropped = current !== null &&
+            owned.routes.includes(current.provider) &&
+            !finalRoutes.includes(current.provider);
+        if (!dropped)
+            return;
+        // replace({}) 重新继承组合层与 schema 默认：这里不能只删字段，
+        // 该段 schema 要求 provider/model 同时在场。
+        await this.replaceNamespace(settings, 'agent-default-model', {});
+    }
+    /**
+     * 现行默认模型选择：dsh 服务优先（它读到的是含用户层的有效值），
+     * 服务缺席或没有读口时回落 `agent-default-model` 段——插件自己写进去的那一份就在那里。
+     */
+    currentSelection(settings) {
+        const service = this.ctx.get('agentDefaultModel', false);
+        const live = service?.currentSelection?.();
+        if (live !== undefined)
+            return live;
+        const value = settings
+            .describe()
+            .find(entry => entry.ns === 'agent-default-model')?.value;
+        const provider = typeof value?.provider === 'string' ? value.provider : '';
+        const model = typeof value?.model === 'string' ? value.model : '';
+        return provider === '' || model === '' ? null : { provider, model };
+    }
+    /**
+     * 写入 `llm-pi-ai.providers`：本插件的路由完全对齐服务端现状（含回收），用户自己写的条目原样保留。
+     *
+     * 预设路由键就是 dsh 的提供方 id，与用户手写 profile 同名时以用户为准（改用自铸路由），
+     * 否则会把人家配置里的 `anthropic:` 段整段替换掉。
+     *
+     * @returns 实际落地的路由表（原路由键 → 最终路由键），调用侧据此改写默认模型与项目选择——
+     * 让位后若仍按原路由键选模型，`agent-default-model` 会指向一条属于用户的 profile。
+     */
+    async applyProviders(settings, compiled, facts) {
+        const existing = this.readProviders(settings);
+        const owned = new Set(facts.routes);
+        const injected = {};
+        const routes = new Map();
+        for (const [route, provider] of Object.entries(compiled)) {
+            const taken = Object.hasOwn(existing, route) && !owned.has(route);
+            if (!taken) {
+                injected[route] = providerProfile(provider);
+                routes.set(route, route);
+                continue;
+            }
+            // 让位：自铸路由没有目录兜底，必须自带 api / baseURL（providerProfile 会带上）。
+            const fallback = connectionRoute(provider.connectionId);
+            this.warn(`provider 路由 ${route} 已被本地配置占用，改用自铸路由 ${fallback}`);
+            injected[fallback] = providerProfile({ ...provider, preset: false });
+            routes.set(route, fallback);
+        }
+        // 归属表外的自铸路由一并回收，避免留下死路由（重载与登出都走这里）。
+        // 它们的密钥引用只能从被丢弃的 profile 上取——归属表里没有这条记录。
+        const staleCredentials = [];
+        const kept = Object.fromEntries(Object.entries(existing).filter(([id, profile]) => {
+            if (owned.has(id))
+                return false;
+            if (!LEGACY_OWNED_PROVIDER.test(id))
+                return true;
+            const env = apiKeyEnvOf(profile);
+            if (env !== undefined)
+                staleCredentials.push(env);
+            return false;
+        }));
+        // 整体替换而非合并：这个段只有 `providers` 一个键，替换后本表即服务端现状 + 用户自有条目，
+        // 上一轮注入、这一轮服务端已撤下的路由才会真的消失。
+        await this.replaceNamespace(settings, 'llm-pi-ai', {
+            providers: { ...kept, ...injected },
+        });
+        return { routes, staleCredentials };
+    }
+    readProviders(settings) {
+        const providers = settings
+            .describe()
+            .find(entry => entry.ns === 'llm-pi-ai')?.value?.providers;
+        return providers !== null &&
+            typeof providers === 'object' &&
+            !Array.isArray(providers)
+            ? providers
+            : {};
+    }
+    readOwned(settings) {
+        const value = settings.describe().find(entry => entry.ns === OWNED_NAMESPACE)?.value ??
+            {};
+        const strings = (input) => Array.isArray(input)
+            ? input.filter((item) => typeof item === 'string')
+            : [];
+        return {
+            routes: strings(value.routes),
+            credentials: strings(value.credentials),
+            deepseek: value.deepseek === true,
+        };
+    }
+    /**
+     * 连接级密钥 → dsh credentials；`runtimeModelCredentials` 降级时整体跳过（返回 null）。
+     *
+     * `reconcile`（模型目录同时读到了）时才回收服务端已撤下连接的密钥：此时「服务端没有它」
+     * 是确定的，否则与「这次没读到」不可区分，只能连归属表一起原样保留。
+     *
+     * @returns 归属表该记的密钥名（本轮写过 ∪ 上次写过）。
+     */
+    async applyModelCredentials(boot, reconcile, facts, staleCredentials) {
+        const entries = boot.runtimeModelCredentials;
+        if (entries === null || entries === undefined) {
+            this.warn('模型密钥读取失败（runtimeModelCredentials），跳过密钥写入');
+            return null;
+        }
+        const credentials = await this.service('credentials');
+        const written = new Set();
+        for (const entry of entries) {
+            const apiKeyEnv = connectionApiKeyEnv(entry.connectionId);
+            if (written.has(apiKeyEnv))
+                continue;
+            written.add(apiKeyEnv);
+            // dsh credentials 解析顺序是 env 先于存储：删掉同名 env 才能让 semi2-hub 密钥生效
+            //（该名字由 client 自铸，不与本地 key 撞名）。
+            Reflect.deleteProperty(process.env, apiKeyEnv);
+            await credentials.set(credentialRef(apiKeyEnv), entry.value);
+        }
+        if (!reconcile)
+            return [...new Set([...facts.credentials, ...written])];
+        const obsolete = new Set([...facts.credentials, ...staleCredentials]);
+        for (const ref of obsolete) {
+            if (written.has(ref))
+                continue;
+            try {
+                await credentials.unset(credentialRef(ref));
+            }
+            catch {
+                this.warn(`陈旧模型密钥 ${ref} 回收失败`);
+            }
+        }
+        return [...written];
+    }
+    /**
+     * 控制台技能目录：`runtimeSkills` 为 null/undefined 都算「没拿到权威目录」——返回 null 只降级该块，
+     * 状态里 null ≠ 空数组（provider 据此报 complete:false，dsh 才不把抖动缓存成空目录）。
+     */
+    applySkills(boot) {
+        const skills = boot.runtimeSkills;
+        if (skills === null || skills === undefined) {
+            this.warn('技能目录读取失败（runtimeSkills），本次不提供控制台技能');
+            return null;
+        }
+        return skills.map(skill => ({
+            id: skill.id,
+            projectId: skill.projectId,
+            name: skill.name,
+            description: skill.description,
+            whenToUse: skill.whenToUse,
+            content: skill.content,
+            version: skill.version,
+            files: fileFactsOf(skill),
+        }));
+    }
+    applied(boot, compiled, errorCode) {
+        const defaultModelId = boot.runtimeDefaultModelId ?? null;
+        const selection = compiled === null || defaultModelId === null
+            ? null
+            : (compiled.selections.get(defaultModelId) ?? null);
+        return {
+            ...this.current,
+            status: 'ready',
+            error: errorCode,
+            consoleUrl: this.connection?.url ?? this.current.consoleUrl,
+            loadedAt: new Date().toISOString(),
+            identity: boot.runtimeViewer ?? null,
+            model: selection === null
+                ? null
+                : { id: selection.model, provider: selection.provider },
+            skills: this.applySkills(boot),
+            // 项目缓存随本次装配作废：接着由工作区同步按 slug 重新取，服务端已撤下的项目不会残留。
+            projects: [],
+        };
+    }
+    async login(input) {
+        await this.ensureContract();
+        if (hasContractCredentials(this.contract?.credentials))
+            throw new ConfigurationError('CREDENTIAL_SOURCE_READONLY');
+        const outcome = await loginToConsole({
+            url: input.url,
+            username: input.username,
+            password: input.password,
+        });
+        await storeConnection(this.ctx, { url: outcome.url, token: outcome.token });
+        this.connection = await this.exchangeCnbCredential(connectionOf(await this.connectionFields()));
+        await this.load();
+        return { userName: outcome.userName };
+    }
+    async logout() {
+        await clearConnection(this.ctx);
+        // 登出后地址仍在（env 或契约给的），登录表单不该被清空。
+        const fields = await this.connectionFields();
+        this.connection = await this.exchangeCnbCredential(connectionOf(fields));
+        // 部署面凭据（契约 / CNB 面 env）不受登出影响：配置照旧可读，不回收。
+        if (this.connection !== null) {
+            await this.load();
+            return;
+        }
+        await this.reclaim();
+        this.publish(initialState(false, fields.url?.value ?? null, this.trackedWorkspaces()));
+        this.ctx.emit('semi2/config-updated', this.current);
+        await this.publishStatus();
+    }
+    /**
+     * 登出 = 回到「从未登录」：本地不留任何 semi2-hub 下发的运行配置。
+     * 残留不是显示问题——路由与密钥还在，会话就继续用着一个已登出账号的模型，
+     * 默认模型甚至指向目录里已不存在的条目（选中即 `NO_ADAPTER`）。
+     *
+     * 只删归属表记着的条目：用户自己写的 provider profile、`llm-deepseek` 键、
+     * 组合层默认模型都不属于我们。回收失败只 warn，登出本身必须成功。
+     */
+    async reclaim() {
+        this.compiled = null;
+        this.defaultModelId = null;
+        this.missingProjects.clear();
+        // 工作区簿记里的 hub 解析结果一并撤下（目录、标题、git slug 是本地事实，保留）。
+        for (const entry of this.book.entries())
+            this.book.set({
+                ...entry,
+                projectId: null,
+                name: null,
+                syncedAt: null,
+            });
+        const settings = this.settings;
+        if (settings === undefined)
+            return;
+        try {
+            const owned = this.readOwned(settings);
+            // 空目录 + 归属表 = 只撤自己写过的路由（连带归属表外的自铸路由与它们的密钥引用）。
+            const { staleCredentials } = await this.applyProviders(settings, {}, owned);
+            if (owned.deepseek)
+                await this.clearKeys(settings, 'llm-deepseek', DEEPSEEK_OWNED_KEYS);
+            // 默认模型正指向我们的路由时交还组合层：路由已撤，留着就是悬空引用。
+            const selection = this.currentSelection(settings);
+            if (selection !== null && owned.routes.includes(selection.provider))
+                await this.replaceNamespace(settings, 'agent-default-model', {});
+            await this.reclaimCredentials([...owned.credentials, ...staleCredentials]);
+            await this.updateNamespace(settings, OWNED_NAMESPACE, {
+                routes: [],
+                credentials: [],
+                deepseek: false,
+            });
+        }
+        catch (error) {
+            this.warn(`登出回收失败（${codeOf(error)}），本地可能留有上次注入的条目`);
+        }
+        await this.persistWorkspaces();
+    }
+    /** 回收模型密钥（按归属表、以及归属表外自铸路由自带的引用）；单条失败只 warn。 */
+    async reclaimCredentials(refs) {
+        const obsolete = [...new Set(refs)];
+        if (obsolete.length === 0)
+            return;
+        // 非严格查找：登出不能被一个缺席的服务卡住（登录 / 登出时该服务本就存在）。
+        const credentials = this.ctx.get('credentials', false);
+        if (credentials === undefined) {
+            this.warn('credentials 服务缺席，模型密钥回收跳过');
+            return;
+        }
+        for (const ref of obsolete) {
+            try {
+                await credentials.unset(credentialRef(ref));
+            }
+            catch {
+                this.warn(`模型密钥 ${ref} 回收失败`);
+            }
+        }
+    }
+    publish(next) {
+        this.current = next;
+    }
+    /** 记一条领域降级码并返回它（调用方收集，首个作为 state.error）。 */
+    noteFailure(area, error) {
+        const code = codeOf(error);
+        this.warn(`${area}应用失败（${code}），该领域降级，其余领域照常`);
+        return code;
+    }
+    warn(message) {
+        try {
+            this.ctx.logger('semi2-config').warn(message);
+        }
+        catch {
+            // 无 logger 的宿主（单测）忽略。
+        }
+    }
+}