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

package/lib/codegraph/index.js

@@ -0,0 +1,97 @@
+import { SEMI2_RUNTIME_SERVICE } from "../contract.js";
+import { createCodegraphRunner } from "./cli.js";
+import { autoIndexEnabled, moduleDisabled, platformOf } from "./config.js";
+import { ensureIndex } from "./ensure.js";
+import { registerGuide } from "./guide.js";
+import { installTools } from "./tools.js";
+import { findGitRoot, findIndexRoot } from "./workspace.js";
+/** apply 期预热等契约的上限：适配器同步 provide；等不到按宿主直跑不预热。 */
+const PREWARM_CONTRACT_TIMEOUT_MS = 5_000;
+const PREWARM_CONTRACT_POLL_MS = 200;
+function makeWarn(ctx) {
+    try {
+        const logger = ctx.logger('semi2-codegraph');
+        return (message) => {
+            logger.warn(message);
+        };
+    }
+    catch {
+        return () => { };
+    }
+}
+/** 自动索引面 + 未索引 + git 仓库才预热；目标保持会话工作区 cwd。 */
+export function prewarmTarget(platform, cwd, env) {
+    if (!autoIndexEnabled(platform, env))
+        return null;
+    if (cwd === undefined || findIndexRoot(cwd) !== undefined)
+        return null;
+    return findGitRoot(cwd) === undefined ? null : cwd;
+}
+async function waitForPlatform(ctx, signal) {
+    const deadline = Date.now() + PREWARM_CONTRACT_TIMEOUT_MS;
+    for (;;) {
+        signal.throwIfAborted();
+        const runtime = ctx.get(SEMI2_RUNTIME_SERVICE, false);
+        if (runtime !== undefined)
+            return runtime.platform;
+        if (Date.now() >= deadline)
+            return 'host';
+        await new Promise((resolve, reject) => {
+            const timer = globalThis.setTimeout(resolve, PREWARM_CONTRACT_POLL_MS);
+            signal.addEventListener('abort', () => {
+                globalThis.clearTimeout(timer);
+                reject(signal.reason instanceof Error ? signal.reason : new Error('codegraph initialization aborted'));
+            }, { once: true });
+        });
+    }
+}
+export function installCodegraph(ctx) {
+    if (moduleDisabled(process.env))
+        return () => { };
+    const warn = makeWarn(ctx);
+    const run = createCodegraphRunner(ctx.subprocess);
+    const platform = () => platformOf(ctx);
+    const noDaemon = () => platform() !== 'host';
+    const lifetime = new AbortController();
+    const disposers = [
+        registerGuide(ctx, warn),
+        installTools(ctx, {
+            run,
+            lifecycleSignal: lifetime.signal,
+            autoIndex: () => autoIndexEnabled(platform(), process.env),
+            noDaemon,
+            warn,
+        }),
+    ];
+    void (async () => {
+        const currentPlatform = await waitForPlatform(ctx, lifetime.signal);
+        const root = prewarmTarget(currentPlatform, process.cwd(), process.env);
+        if (root !== null)
+            await ensureIndex(run, root, lifetime.signal);
+    })().catch((error) => {
+        if (!lifetime.signal.aborted)
+            warn(`codegraph prewarm failed: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    disposers.push(ctx.on('agent/created', ({ agent, signal }) => {
+        const root = prewarmTarget(platformOf(ctx), agent.session.header.cwd, process.env);
+        if (root === null)
+            return undefined;
+        const taskSignal = signal === undefined ? lifetime.signal : AbortSignal.any([lifetime.signal, signal]);
+        void ensureIndex(run, root, taskSignal).catch((error) => {
+            if (!taskSignal.aborted)
+                warn(`codegraph auto-index failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+        return undefined;
+    }));
+    return () => {
+        lifetime.abort(new Error('codegraph plugin disposed'));
+        for (const dispose of disposers) {
+            try {
+                dispose();
+            }
+            catch {
+                // 回收失败不阻断。
+            }
+        }
+    };
+}

package/lib/codegraph/tools.js

@@ -0,0 +1,227 @@
+import { HarnessError } from '@deepseek-ai/dsh-llm';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { ensureIndex } from "./ensure.js";
+import { ensureGitExclude, findIndexRoot, resolveProjectTarget } from "./workspace.js";
+const PATH_PARAM = {
+    type: 'string',
+    description: '项目目录。缺省取当前会话 cwd；相对路径按会话 cwd 解析，绝对路径原样使用；不向祖先借用索引。',
+};
+const SOURCE_NOTE = '数据源是本仓库的 .codegraph 结构索引。';
+export class CodegraphToolError extends HarnessError {
+}
+/** argv 文本收窄：参数按 schema 只会是 string/integer，其它形状按缺省处理。 */
+function argText(value, fallback) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number')
+        return String(value);
+    return fallback;
+}
+export function installTools(ctx, deps) {
+    const disposers = [];
+    const register = (name, description, parameters, argvOf, options = {}) => {
+        const tool = defineTool({
+            name,
+            description,
+            parameters: parameters,
+            output: {
+                schema: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        path: { type: 'string', required: true },
+                        text: { type: 'string', required: true },
+                    },
+                },
+                render: (_args, value) => [{ type: 'text', text: value.text }],
+                presentationMeta: (_args, value) => ({ path: value.path }),
+            },
+            ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+            isConcurrencySafe: () => options.concurrencySafe === true,
+            ...(options.presentCall === undefined ? {} : { presentCall: options.presentCall }),
+            execute: async (args, exec) => {
+                const sessionCwd = exec.agent?.session?.header?.cwd;
+                const given = args.path;
+                const cwd = typeof given === 'string' && given !== '' ? given : sessionCwd;
+                if (cwd === undefined) {
+                    throw new CodegraphToolError('CodeGraph needs a project directory. Pass path or call it from an agent session with a workspace cwd.', 'CODEGRAPH_CWD_REQUIRED');
+                }
+                try {
+                    const root = resolveProjectTarget(cwd, sessionCwd);
+                    if (options.init === true && args.force !== true) {
+                        await ensureIndex(deps.run, root, deps.lifecycleSignal);
+                        return { path: root, text: 'CodeGraph index is ready.' };
+                    }
+                    if (options.query === true && findIndexRoot(root) === undefined) {
+                        if (!deps.autoIndex()) {
+                            throw new CodegraphToolError('This workspace has no CodeGraph index. Run codegraph_init once, then retry the query.', 'CODEGRAPH_NOT_INDEXED');
+                        }
+                        await ensureIndex(deps.run, root, deps.lifecycleSignal);
+                    }
+                    exec.signal?.throwIfAborted();
+                    const out = await deps.run(argvOf(args, root), {
+                        cwd: root,
+                        ...(exec.signal !== undefined ? { signal: exec.signal } : {}),
+                        noDaemon: deps.noDaemon(),
+                    });
+                    if (options.after !== undefined)
+                        options.after(root);
+                    return { path: root, text: out };
+                }
+                catch (error) {
+                    if (error instanceof CodegraphToolError)
+                        throw error;
+                    const message = error instanceof Error ? error.message : String(error);
+                    deps.warn(`codegraph tool ${name} failed: ${message}`);
+                    throw new CodegraphToolError(`CodeGraph ${name} failed: ${message}`, 'CODEGRAPH_FAILED', { cause: error });
+                }
+            },
+        });
+        disposers.push(ctx.tools.register(tool));
+    };
+    // ---- 索引维护 ----
+    register('codegraph_status', `返回项目 CodeGraph 索引的初始化状态、版本、文件数、节点数、边数和待同步变更。${SOURCE_NOTE}`, { path: PATH_PARAM }, (_args, root) => ['status', '--json', root], {
+        timeoutMs: 60_000,
+        concurrencySafe: true,
+        presentCall: args => ({
+            card: 'generic',
+            title: 'Check CodeGraph index status',
+            kind: 'search',
+            ...(typeof args.path === 'string' ? { locations: [{ path: args.path }] } : {}),
+        }),
+    });
+    register('codegraph_init', '在指定项目中初始化 CodeGraph 并建立完整索引；索引完成后返回。', { path: PATH_PARAM, force: { type: 'boolean', description: '路径是家目录/文件系统根时也强制初始化。' } }, (args, root) => (args.force === true ? ['init', '--yes', '--force', root] : ['init', '--yes', root]), {
+        timeoutMs: 600_000,
+        init: true,
+        after: ensureGitExclude,
+        presentCall: args => ({
+            card: 'generic',
+            title: 'Initialize CodeGraph index',
+            kind: 'execute',
+            ...(typeof args.path === 'string' ? { locations: [{ path: args.path }] } : {}),
+        }),
+    });
+    register('codegraph_sync', '将指定项目的文件变化增量同步到已有 CodeGraph 索引。', { path: PATH_PARAM }, (_args, root) => ['sync', root], {
+        timeoutMs: 300_000,
+        presentCall: args => ({
+            card: 'generic',
+            title: 'Sync CodeGraph index',
+            kind: 'execute',
+            ...(typeof args.path === 'string' ? { locations: [{ path: args.path }] } : {}),
+        }),
+    });
+    register('codegraph_index', '对指定项目执行全量索引；force 为 true 时丢弃已有索引并重建。', { path: PATH_PARAM, force: { type: 'boolean', description: '丢弃旧索引强制重建。' } }, (args, root) => (args.force === true ? ['index', '--force', root] : ['index', root]), { timeoutMs: 600_000 });
+    register('codegraph_uninit', '删除指定项目的 .codegraph 索引数据。', {
+        path: PATH_PARAM,
+        confirm: { type: 'boolean', required: true, description: '是否确认删除索引；必须为 true。' },
+    }, (args, root) => {
+        if (args.confirm !== true) {
+            throw new CodegraphToolError('CodeGraph index removal requires confirm=true.', 'CODEGRAPH_FAILED');
+        }
+        return ['uninit', '--force', root];
+    }, { timeoutMs: 120_000 });
+    register('codegraph_unlock', '删除指定项目中阻塞索引操作的陈旧 CodeGraph 锁文件。', { path: PATH_PARAM }, (_args, root) => ['unlock', root], { timeoutMs: 60_000 });
+    // ---- 查询与探索 ----
+    register('codegraph_explore', `返回与自然语言查询相关的符号源码及其调用或依赖路径，包含动态派发关系。${SOURCE_NOTE}`, {
+        query: { type: 'string', required: true, description: '自然语言区域描述或符号/文件名。' },
+        path: PATH_PARAM,
+        maxFiles: { type: 'integer', description: '最多包含源码的文件数。' },
+    }, (args, root) => {
+        const argv = ['explore', '--path', root];
+        if (args.maxFiles !== undefined)
+            argv.push('--max-files', argText(args.maxFiles, ''));
+        argv.push(argText(args.query, ''));
+        return argv;
+    }, 
+    // 自动索引面的首个调用可能内嵌一次 init（容器 2–4 分钟），预算必须盖住两段。
+    {
+        timeoutMs: 600_000,
+        query: true,
+        concurrencySafe: true,
+        presentCall: args => ({
+            card: 'generic',
+            title: `Explore code: ${argText(args.query, '')}`,
+            kind: 'search',
+            ...(typeof args.path === 'string' ? { locations: [{ path: args.path }] } : {}),
+        }),
+    });
+    register('codegraph_query', '按名称或子串搜索索引中的符号，返回类型、签名、文件、行号和匹配得分。', {
+        search: { type: 'string', required: true, description: '符号名或部分名。' },
+        path: PATH_PARAM,
+        limit: { type: 'integer', description: '结果上限（默认 10）。' },
+        kind: { type: 'string', description: '按节点类型过滤（function/class/method/interface/…）。' },
+    }, (args, root) => {
+        const argv = ['query', '--json', '--path', root, '-l', argText(args.limit, '10')];
+        if (args.kind !== undefined)
+            argv.push('-k', argText(args.kind, ''));
+        argv.push(argText(args.search, ''));
+        return argv;
+    }, { timeoutMs: 120_000, query: true });
+    register('codegraph_node', '返回单个符号的源码与调用关系；文件模式返回带行号的文件内容和依赖信息。', {
+        name: { type: 'string', required: true, description: '符号名（如 multiply）或文件路径（如 src/math.ts）。' },
+        path: PATH_PARAM,
+        file: { type: 'boolean', description: '把 name 当文件路径。' },
+        offset: { type: 'integer', description: '文件模式：1 起始行。' },
+        limit: { type: 'integer', description: '文件模式：最大行数。' },
+        symbolsOnly: { type: 'boolean', description: '文件模式：只给符号图与依赖，不含源码。' },
+    }, (args, root) => {
+        const argv = ['node', '--path', root];
+        if (args.file === true)
+            argv.push('--file', argText(args.name, ''));
+        else
+            argv.push(argText(args.name, ''));
+        if (args.offset !== undefined)
+            argv.push('--offset', argText(args.offset, ''));
+        if (args.limit !== undefined)
+            argv.push('--limit', argText(args.limit, ''));
+        if (args.symbolsOnly === true)
+            argv.push('--symbols-only');
+        return argv;
+    }, { timeoutMs: 120_000, query: true });
+    register('codegraph_files', '返回索引中的文件结构、语言和符号数量，可按目录、glob 和深度过滤。', {
+        path: PATH_PARAM,
+        filter: { type: 'string', description: '只看该目录下。' },
+        pattern: { type: 'string', description: 'glob 过滤（如 src/**/*.ts）。' },
+        format: { type: 'string', description: '输出：tree / flat / grouped。' },
+        maxDepth: { type: 'integer', description: 'tree 格式最大深度。' },
+    }, (args, root) => {
+        const argv = ['files', '--json', '--path', root];
+        if (args.filter !== undefined)
+            argv.push('--filter', argText(args.filter, ''));
+        if (args.pattern !== undefined)
+            argv.push('--pattern', argText(args.pattern, ''));
+        if (args.format !== undefined)
+            argv.push('--format', argText(args.format, ''));
+        if (args.maxDepth !== undefined)
+            argv.push('--max-depth', argText(args.maxDepth, ''));
+        return argv;
+    }, { timeoutMs: 120_000, query: true });
+    // ---- 关系查询 ----
+    register('codegraph_callers', '返回直接调用指定符号的节点及其名称、类型、文件和行号。', { symbol: { type: 'string', required: true, description: '目标符号。' }, path: PATH_PARAM, limit: { type: 'integer', description: '上限（默认 20）。' } }, (args, root) => ['callers', '--json', '--path', root, '-l', argText(args.limit, '20'), argText(args.symbol, '')], { timeoutMs: 120_000, query: true });
+    register('codegraph_callees', '返回指定符号直接调用的节点。', { symbol: { type: 'string', required: true, description: '目标符号。' }, path: PATH_PARAM, limit: { type: 'integer', description: '上限（默认 20）。' } }, (args, root) => ['callees', '--json', '--path', root, '-l', argText(args.limit, '20'), argText(args.symbol, '')], { timeoutMs: 120_000, query: true });
+    register('codegraph_impact', '返回从指定符号沿反向依赖关系传播得到的影响节点。', { symbol: { type: 'string', required: true, description: '目标符号。' }, path: PATH_PARAM, depth: { type: 'integer', description: '遍历深度（默认 2）。' } }, (args, root) => ['impact', '--json', '--path', root, '-d', argText(args.depth, '2'), argText(args.symbol, '')], { timeoutMs: 120_000, query: true });
+    register('codegraph_affected', '根据变更文件和依赖关系返回可能受影响的测试文件。', {
+        files: { type: 'array', required: true, items: { type: 'string' }, description: '变更的源文件路径（相对项目根）。' },
+        path: PATH_PARAM,
+        depth: { type: 'integer', description: '依赖遍历深度（默认 5）。' },
+        filter: { type: 'string', description: '测试文件 glob 覆盖。' },
+    }, (args, root) => {
+        const argv = ['affected', '--json', '--path', root, '-d', argText(args.depth, '5')];
+        if (args.filter !== undefined)
+            argv.push('--filter', argText(args.filter, ''));
+        if (Array.isArray(args.files))
+            for (const file of args.files)
+                argv.push(argText(file, ''));
+        return argv;
+    }, { timeoutMs: 120_000, query: true });
+    return () => {
+        for (const dispose of disposers) {
+            try {
+                dispose();
+            }
+            catch {
+                // 回收失败不阻断。
+            }
+        }
+    };
+}

package/lib/codegraph/workspace.js

@@ -0,0 +1,52 @@
+// @fa-software/semi2-dsh/codegraph/workspace —— 工作区索引检测与索引卫生（纯函数，可单测）。
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+/** 向上找目录的步数上限：再深的嵌套也不该离开项目树。 */
+const MAX_WALK = 12;
+function walkUp(start, marker) {
+    let dir = start;
+    for (let i = 0; i < MAX_WALK && dir !== ''; i++) {
+        if (marker(dir))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+/** 工作区 cwd 自身已建立索引时返回该目录；不向祖先目录借用索引。 */
+export function findIndexRoot(cwd) {
+    return existsSync(join(cwd, '.codegraph', 'codegraph.db')) ? cwd : undefined;
+}
+/** 最近的 git 根：自动索引只在 git 仓库里做，防止在任意目录（如 ~）建索引。 */
+export function findGitRoot(cwd) {
+    return walkUp(cwd, dir => existsSync(join(dir, '.git')));
+}
+/** 显式绝对路径原样使用；相对路径按当前会话工作区解析，与 dsh 文件工具一致。 */
+export function resolveProjectTarget(path, sessionCwd) {
+    if (isAbsolute(path))
+        return path;
+    return resolve(sessionCwd ?? process.cwd(), path);
+}
+/** `.codegraph/` 进 `.git/info/exclude`（本地忽略，不动已跟踪文件，`git status` 保持干净）；幂等、best-effort。 */
+export function ensureGitExclude(root) {
+    try {
+        const gitRoot = findGitRoot(root);
+        if (gitRoot === undefined)
+            return;
+        const infoDir = join(gitRoot, '.git', 'info');
+        const excludePath = join(infoDir, 'exclude');
+        mkdirSync(infoDir, { recursive: true });
+        let current = '';
+        if (existsSync(excludePath))
+            current = readFileSync(excludePath, 'utf8');
+        if (!current.split('\n').includes('.codegraph/')) {
+            const next = current === '' ? '.codegraph/\n' : current.endsWith('\n') ? `${current}.codegraph/\n` : `${current}\n.codegraph/\n`;
+            writeFileSync(excludePath, next, 'utf8');
+        }
+    }
+    catch {
+        // 排除写不进不致命：大不了 git status 多一个未跟踪目录。
+    }
+}

package/lib/configuration/compile.js

@@ -0,0 +1,177 @@
+/** 路由键 hex 对人无意义：用 `displayName` 覆盖显示名（`llm-pi-ai` 语义：`displayName ?? 路由键`）。 */
+export const CONSOLE_PROVIDER_DISPLAY_NAME = 'semi2-hub';
+/** 路由键必须留 hex——协议路由与 `agent-default-model` 都引用它。 */
+export function connectionRoute(connectionId) {
+    return `semi2-${connectionId.replaceAll('-', '')}`;
+}
+/**
+ * 一条连接在 dsh 里的路由键。
+ *
+ * 预设连接直接用**预设 id**（= dsh 的提供方路由 id）：`llm-pi-ai` 只在路由名能对上已装目录时
+ * 才复用那份目录条目（compat / headers / cost / thinkingLevelMap），换个名字这些全丢。
+ * 自定义连接没有可对应的目录条目，用自铸的 hex 路由 + 显式 `api` / `baseURL`。
+ *
+ * DEEPSEEK 协议走内置原生适配器（独立于 pi-ai 目录），与预设/自定义无关。
+ */
+export function connectionProviderName(connection) {
+    if (connection.protocol === 'DEEPSEEK')
+        return 'deepseek-official';
+    return connection.provider ?? connectionRoute(connection.id);
+}
+/** 密钥的进程 env 名（= dsh credentials 引用名）。 */
+export function connectionApiKeyEnv(connectionId) {
+    return `SEMI2_MODEL_KEY_${connectionId.replaceAll('-', '').toUpperCase()}`;
+}
+export function protocolApi(protocol) {
+    return protocol === 'ANTHROPIC'
+        ? 'anthropic-messages'
+        : protocol === 'OPENAI_RESPONSES'
+            ? 'openai-responses'
+            : 'openai-completions';
+}
+export function modelName(model) {
+    return model.displayName ?? model.upstreamId;
+}
+/** 写入 settings 的 profile：预设路由省略 `api` / `baseURL`，其余按需带上。 */
+export function providerProfile(compiled) {
+    return {
+        ...(compiled.preset ? {} : { api: compiled.api, baseURL: compiled.baseURL }),
+        apiKeyEnv: compiled.apiKeyEnv,
+        displayName: compiled.displayName,
+        models: compiled.models,
+    };
+}
+/**
+ * 按实际落地的路由表改写选择。路由让位（同名用户 profile）后，编译期算出的
+ * 路由键已不是最终值，默认模型与项目 plan/execute 都必须跟着换。
+ */
+export function remapSelections(compiled, routes) {
+    const rewrite = (selection) => {
+        const route = routes.get(selection.provider);
+        return route === undefined || route === selection.provider
+            ? selection
+            : { provider: route, model: selection.model };
+    };
+    return {
+        ...compiled,
+        defaultModel: compiled.defaultModel === null ? null : rewrite(compiled.defaultModel),
+        selections: new Map([...compiled.selections].map(([id, selection]) => [id, rewrite(selection)])),
+    };
+}
+function modality(value) {
+    return value === 'IMAGE' ? 'image' : 'text';
+}
+function level(value) {
+    return value.toLowerCase();
+}
+/** llm-pi-ai：全 off → `false`（不支持推理档），档位里的 `off` 表示不可用 → null。 */
+function reasoningEfforts(levels) {
+    if (levels === null)
+        return undefined;
+    const lowered = levels.map(level);
+    if (lowered.every(entry => entry === 'off'))
+        return false;
+    return Object.fromEntries(lowered.map(entry => [entry, entry === 'off' ? null : entry]));
+}
+function selectionOf(model) {
+    return {
+        provider: connectionProviderName(model.connection),
+        model: model.upstreamId,
+    };
+}
+/**
+ * 预设连接的 profile：路由键 = 预设 id，模型清单来自 hub 的内置目录。
+ *
+ * `preset: true` 让写入侧省略 `api` / `baseURL`：
+ * · 不写 `api` —— `llm-pi-ai` 只在 profile 不覆盖线协议时才复用目录 provider，
+ *   写死协议会把多协议提供方（openrouter）压成一种；
+ * · 不写 `baseURL` —— 一个路由的模型可能分属不同 base（openrouter 的 anthropic 模型在
+ *   `/api`、其余在 `/api/v1`）；hub 的预设地址就是目录地址，交给目录逐模型给。
+ * 于是 compat / headers / cost / thinkingLevelMap 全部沿用 dsh 目录里的值。
+ */
+function presetProvider(route, connection, models) {
+    return {
+        preset: true,
+        connectionId: connection.id,
+        api: protocolApi(connection.protocol),
+        baseURL: connection.baseUrl,
+        apiKeyEnv: connectionApiKeyEnv(connection.id),
+        displayName: route,
+        models: models.map(model => ({
+            id: model.upstreamId,
+            name: modelName(model),
+            ...(model.metadata.contextWindow === null
+                ? {}
+                : { contextWindow: model.metadata.contextWindow }),
+            ...(model.metadata.maxTokens === null
+                ? {}
+                : { maxTokens: model.metadata.maxTokens }),
+            ...(model.metadata.input === null
+                ? {}
+                : { input: model.metadata.input.map(modality) }),
+        })),
+    };
+}
+export function compileBoot(models, defaultModelId) {
+    const providers = {};
+    const deepseekModels = [];
+    let deepseek = null;
+    const selections = new Map();
+    const presetConnections = new Map();
+    for (const model of models) {
+        const { contextWindow, maxTokens, input } = model.metadata;
+        selections.set(model.id, selectionOf(model));
+        if (model.connection.protocol === 'DEEPSEEK') {
+            deepseek ??= {
+                apiKeyEnv: connectionApiKeyEnv(model.connection.id),
+                baseURL: model.connection.baseUrl,
+                models: deepseekModels,
+            };
+            deepseekModels.push({
+                id: model.upstreamId,
+                name: modelName(model),
+                ...(contextWindow === null ? {} : { contextWindow }),
+                ...(maxTokens === null ? {} : { maxTokens }),
+                ...(input === null ? {} : { inputModalities: input.map(modality) }),
+            });
+            continue;
+        }
+        // 预设连接：按提供方 id 聚合，最后交给目录 provider（hub 保证一个预设只需一条连接）。
+        // `?? null` 收口：契约里 provider 可空，hub 未下发该字段时按自定义连接处理。
+        const preset = model.connection.provider ?? null;
+        if (preset !== null) {
+            const bucket = presetConnections.get(preset);
+            if (bucket === undefined)
+                presetConnections.set(preset, {
+                    connection: model.connection,
+                    models: [model],
+                });
+            else
+                bucket.models.push(model);
+            continue;
+        }
+        const route = connectionRoute(model.connection.id);
+        const efforts = reasoningEfforts(model.metadata.reasoningLevels);
+        const provider = (providers[route] ??= {
+            preset: false,
+            connectionId: model.connection.id,
+            api: protocolApi(model.connection.protocol),
+            baseURL: model.connection.baseUrl,
+            apiKeyEnv: connectionApiKeyEnv(model.connection.id),
+            displayName: CONSOLE_PROVIDER_DISPLAY_NAME,
+            models: [],
+        });
+        provider.models.push({
+            id: model.upstreamId,
+            name: modelName(model),
+            ...(contextWindow === null ? {} : { contextWindow }),
+            ...(maxTokens === null ? {} : { maxTokens }),
+            ...(input === null ? {} : { input: input.map(modality) }),
+            ...(efforts === undefined ? {} : { reasoningEfforts: efforts }),
+        });
+    }
+    for (const [route, bucket] of presetConnections)
+        providers[route] = presetProvider(route, bucket.connection, bucket.models);
+    const defaultModel = defaultModelId === null ? null : (selections.get(defaultModelId) ?? null);
+    return { providers, deepseek, defaultModel, selections };
+}

package/lib/configuration/credentials.js

@@ -0,0 +1,104 @@
+import { credentialRef, } from '@deepseek-ai/dsh-credentials';
+import { ConfigurationError } from './graphql.js';
+export const CONFIG_URL_REF = 'SEMI2_CONFIG_URL';
+export const ACCESS_TOKEN_REF = 'SEMI2_ACCESS_TOKEN';
+const URL_REF = credentialRef(CONFIG_URL_REF);
+const TOKEN_REF = credentialRef(ACCESS_TOKEN_REF);
+function provider(ctx) {
+    try {
+        return ctx.get('credentials');
+    }
+    catch {
+        return undefined;
+    }
+}
+function text(value) {
+    const trimmed = value?.trim();
+    return trimmed === undefined || trimmed === '' ? undefined : trimmed;
+}
+async function resolveField(credentials, ref, explicit, fallback) {
+    const contractValue = text(explicit);
+    if (contractValue !== undefined)
+        return { value: contractValue, source: 'runtime' };
+    if (credentials !== undefined) {
+        const resolved = await credentials.resolve(ref);
+        const value = text(resolved?.value);
+        return value === undefined
+            ? undefined
+            : { value, source: resolved?.source ?? 'credentials' };
+    }
+    const value = text(fallback);
+    return value === undefined ? undefined : { value, source: 'env' };
+}
+/** 两条腿齐备才算可连；只有地址时调用方用 `url.value` 预填登录表单。 */
+export function connectionOf(fields) {
+    if (fields.url === undefined || fields.token === undefined)
+        return null;
+    return {
+        url: fields.url.value,
+        token: fields.token.value,
+        source: fields.token.source,
+    };
+}
+/** 分别解析地址与令牌（不做齐备性判定）：`resolveConnection` 与状态回报共用这条路。 */
+export async function resolveConnectionFields(ctx, runtimeContract, environment = process.env) {
+    const credentials = provider(ctx);
+    const contract = runtimeContract?.credentials ?? {};
+    const [url, token] = await Promise.all([
+        resolveField(credentials, URL_REF, contract.configUrl, environment.SEMI2_CONFIG_URL),
+        resolveField(credentials, TOKEN_REF, contract.accessToken, environment.SEMI2_ACCESS_TOKEN),
+    ]);
+    // 启动环境层（`source: env`）的令牌只属 CNB 面：`runtimeFromCnbEnv` 从 secret imports 注入的 env 取值。
+    // 宿主 / 容器面认这一层等于自锁——该层只读（dsh 拒绝 set/unset）又排在临时存储之前，设置页会只剩只读状态
+    // （没有登录入口），登录写进去的令牌也读不回来（`runtime.ts` 另在启动时把它从进程 env 摘掉）。
+    // 地址不是密钥、还是登录表单的预填来源，任何面都保留；契约与登录存储的令牌一律照收。
+    const usable = token !== undefined &&
+        (token.source !== 'env' || runtimeContract?.platform === 'cnb')
+        ? token
+        : undefined;
+    return {
+        ...(url === undefined ? {} : { url }),
+        ...(usable === undefined ? {} : { token: usable }),
+    };
+}
+/** 解析当前连接凭据；缺任一项返回 null（调用方据此不注入）。 */
+export async function resolveConnection(ctx, runtimeContract, environment = process.env) {
+    return connectionOf(await resolveConnectionFields(ctx, runtimeContract, environment));
+}
+function sameUrl(left, right) {
+    const normalize = (value) => (value ?? '').trim().replace(/\/+$/, '');
+    return normalize(left) === normalize(right);
+}
+/**
+ * 部署面常用 env 钉死地址，credentials-local 会拒绝被 env 遮蔽的 `set`：来源一致时跳过写入、
+ * 不一致时抛 CREDENTIAL_SOURCE_READONLY（登录不改写部署面钉死的地址）。
+ */
+async function storeUrl(credentials, url) {
+    const info = await credentials.describe(URL_REF);
+    if (info.writable) {
+        await credentials.set(URL_REF, url);
+        return;
+    }
+    const current = await credentials.resolve(URL_REF);
+    if (!sameUrl(current?.value, url))
+        throw new ConfigurationError('CREDENTIAL_SOURCE_READONLY');
+}
+/** 写入登录凭据；env 遮蔽 token 时 dsh 会拒绝——由调用方转成可读错误。 */
+export async function storeConnection(ctx, input) {
+    const credentials = provider(ctx);
+    if (credentials === undefined)
+        throw new Error('CREDENTIAL_STORE_UNAVAILABLE');
+    await storeUrl(credentials, input.url);
+    await credentials.set(TOKEN_REF, input.token);
+}
+/** 清除登录凭据（不触碰运行面契约/env 提供的凭据）。 */
+export async function clearConnection(ctx) {
+    const credentials = provider(ctx);
+    if (credentials === undefined)
+        return;
+    await credentials.unset(TOKEN_REF);
+    // URL 非密钥且可能由 env 钉死（unset 会被拒）：只清可写来源，避免登出半途失败。
+    const info = await credentials.describe(URL_REF);
+    if (info.writable)
+        await credentials.unset(URL_REF);
+}

package/lib/configuration/generated/graphql.js

@@ -0,0 +1 @@
+export {};