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

package/lib/contract.js

@@ -0,0 +1,42 @@
+// @fa-software/semi2-dsh/contract —— 运行面契约（本包定义，三个运行面各自 provide）。
+// 适配器在 apply 里同步 provide（插件在首次领取前等它，见 runtime.ts），服务缺席 = 宿主直跑；headless/web 轴由 dsh 服务存在性决定，提示词段由适配器注入。
+/** cordis 服务名（适配器 provide / 插件 get 共用同一常量）。 */
+export const SEMI2_RUNTIME_SERVICE = 'semi2Runtime';
+function text(value) {
+    const trimmed = value?.trim();
+    return trimmed === undefined || trimmed === '' ? undefined : trimmed;
+}
+function credentialsFromEnv(env) {
+    const configUrl = text(env.SEMI2_CONFIG_URL);
+    // Hub 签发的 CNB 接入密钥（经 secret import 注入 SEMI2_ACCESS_TOKEN）优先：它由 Hub 自己校验，
+    // 直接作为 Bearer 使用。缺失时才回退平台短期 CNB_TOKEN（换用户密钥）。
+    const accessToken = text(env.SEMI2_ACCESS_TOKEN) === undefined ? text(env.CNB_TOKEN) : undefined;
+    return configUrl === undefined && accessToken === undefined
+        ? undefined
+        : {
+            ...(configUrl === undefined ? {} : { configUrl }),
+            ...(accessToken === undefined ? {} : { accessToken }),
+        };
+}
+function runtime(platform, fields) {
+    const contract = { platform };
+    if (fields.credentials !== undefined)
+        contract.credentials = fields.credentials;
+    return contract;
+}
+/**
+ * CNB 运行面：优先用 secret import 注入的 hub 接入密钥（`SEMI2_ACCESS_TOKEN`），
+ * 缺失时才回退平台短期 `CNB_TOKEN`（插件启动时换成 hub 用户密钥）。
+ */
+export function runtimeFromCnbEnv(env) {
+    return runtime('cnb', { credentials: credentialsFromEnv(env) });
+}
+/**
+ * 容器运行面：**只盖章，不给凭据也不给身份**——本地容器靠登录（设置页账号密码换用户密钥）。
+ * 契约一旦提供 `credentials`，插件的 `login()` 会以 `CREDENTIAL_SOURCE_READONLY` 拒绝登录
+ * （部署面地址不可被交互改写），所以这里刻意留空。
+ * CNB 面相反：身份取平台注入的触发 env、凭据取 secret 注入的 env，见 `runtimeFromCnbEnv`。
+ */
+export function runtimeFromContainerEnv(_env) {
+    return runtime('container', {});
+}

package/lib/index.js

@@ -0,0 +1,14 @@
+import z from '@deepseek-ai/schemastery';
+import { installCodegraph } from "./codegraph/index.js";
+import { installConfiguration } from './configuration/index.js';
+import { installWebSurface } from './web/index.js';
+export { SEMI2_RUNTIME_SERVICE, runtimeFromCnbEnv, runtimeFromContainerEnv, } from './contract.js';
+export const name = 'semi2-dsh';
+/** 三个运行面都存在（dsh-base 的 tools / skills 行）；其它服务一律走作用域注入。 */
+export const inject = ['tools', 'skills'];
+export const Config = z.object({});
+export function apply(ctx, _config) {
+    installConfiguration(ctx);
+    installWebSurface(ctx);
+    ctx.inject(['subprocess'], codegraphCtx => installCodegraph(codegraphCtx));
+}

package/lib/types/codegraph/cli.d.ts

@@ -0,0 +1,20 @@
+import type { SubprocessRuntime } from '@deepseek-ai/dsh-subprocess';
+export declare class CodegraphCliError extends Error {
+    readonly exitCode: number | null;
+    constructor(message: string, exitCode: number | null, options?: ErrorOptions);
+}
+export declare function stripAnsi(text: string): string;
+/** 仅供短诊断文本使用；模型结果不在插件内截断，交给 dsh spill policy。 */
+export declare function truncateText(text: string, max: number): string;
+/** 测试与诊断只判断显式覆盖或依赖自带 bin；PATH 由 subprocess 执行世界解析。 */
+export declare function resolveCodegraphBin(): string | undefined;
+export declare const CODEGRAPH_MISSING_HINT: string;
+export interface RunOptions {
+    cwd?: string;
+    signal?: AbortSignal;
+    /** 容器/一次性进程传 true：禁后台 daemon，保证进程随会话收口；宿主保留官方 watcher。 */
+    noDaemon?: boolean;
+}
+export type CodegraphRunner = (argv: readonly string[], options?: RunOptions) => Promise<string>;
+/** 创建绑定到 dsh 执行世界的 runner；取消和插件卸载均由 subprocess provider 管理进程范围。 */
+export declare function createCodegraphRunner(subprocess: SubprocessRuntime): CodegraphRunner;

package/lib/types/codegraph/config.d.ts

@@ -0,0 +1,10 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type Semi2Platform } from '../contract.ts';
+/** 插件自己认的平台：契约缺席（宿主直跑）= host。 */
+export type CodegraphPlatform = Semi2Platform | 'host';
+/** 契约平台**懒取**：apply 期适配器可能还没 provide（配置轮询同理），只在决策点读。 */
+export declare function platformOf(ctx: Context): CodegraphPlatform;
+/** 总开关：SEMI2_CODEGRAPH=0 整块能力 no-op（宿主不想用时的退出阀）。 */
+export declare function moduleDisabled(env: NodeJS.ProcessEnv): boolean;
+/** 自动索引默认值：运行面容器（cnb/container）= 开（无人可替它决定）；宿主 = 关（索引是用户的决定）。 */
+export declare function autoIndexEnabled(platform: CodegraphPlatform, env: NodeJS.ProcessEnv): boolean;

package/lib/types/codegraph/ensure.d.ts

@@ -0,0 +1,3 @@
+import type { CodegraphRunner } from './cli.ts';
+/** 确保目录已建索引；同一 runner/root 的并发初始化共享一次执行，signal 只接受插件生命周期所有者。 */
+export declare function ensureIndex(run: CodegraphRunner, root: string, signal?: AbortSignal): Promise<void>;

package/lib/types/codegraph/guide.d.ts

@@ -0,0 +1,4 @@
+import type { Context } from '@deepseek-ai/cordis';
+export declare const CODEGRAPH_GUIDE: string;
+/** 注册范围感知指引；工具在当前 agent 不可见时不向模型描述它。 */
+export declare function registerGuide(ctx: Context, warn: (message: string) => void): () => void;

package/lib/types/codegraph/index.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { type CodegraphPlatform } from './config.ts';
+/** 自动索引面 + 未索引 + git 仓库才预热；目标保持会话工作区 cwd。 */
+export declare function prewarmTarget(platform: CodegraphPlatform, cwd: string | undefined, env: NodeJS.ProcessEnv): string | null;
+export declare function installCodegraph(ctx: Context): () => void;

package/lib/types/codegraph/tools.d.ts

@@ -0,0 +1,17 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { HarnessError } from '@deepseek-ai/dsh-llm';
+import type { CodegraphRunner } from './cli.ts';
+export type CodegraphToolErrorCode = 'CODEGRAPH_CWD_REQUIRED' | 'CODEGRAPH_NOT_INDEXED' | 'CODEGRAPH_FAILED';
+export declare class CodegraphToolError extends HarnessError {
+    readonly code: CodegraphToolErrorCode;
+}
+export interface ToolsDeps {
+    run: CodegraphRunner;
+    lifecycleSignal: AbortSignal;
+    /** 自动索引开（运行面容器）：查询类工具在未索引项目上先 init 再执行。 */
+    autoIndex: () => boolean;
+    /** 容器面 true：spawn 禁 daemon，进程随会话收口；宿主保留官方 watcher。 */
+    noDaemon: () => boolean;
+    warn: (message: string) => void;
+}
+export declare function installTools(ctx: Context, deps: ToolsDeps): () => void;

package/lib/types/codegraph/workspace.d.ts

@@ -0,0 +1,8 @@
+/** 工作区 cwd 自身已建立索引时返回该目录；不向祖先目录借用索引。 */
+export declare function findIndexRoot(cwd: string): string | undefined;
+/** 最近的 git 根：自动索引只在 git 仓库里做，防止在任意目录（如 ~）建索引。 */
+export declare function findGitRoot(cwd: string): string | undefined;
+/** 显式绝对路径原样使用；相对路径按当前会话工作区解析，与 dsh 文件工具一致。 */
+export declare function resolveProjectTarget(path: string, sessionCwd?: string): string;
+/** `.codegraph/` 进 `.git/info/exclude`（本地忽略，不动已跟踪文件，`git status` 保持干净）；幂等、best-effort。 */
+export declare function ensureGitExclude(root: string): void;

package/lib/types/configuration/compile.d.ts

@@ -0,0 +1,81 @@
+import type { InputModality, ModelProtocol, ReasoningLevel, RuntimeBootQuery, RuntimeWorkspaceProjectsQuery } from './generated/graphql.js';
+/**
+ * 生效可用目录的一条（连接启用 ∧ 模型启用 ∧ 存在性 ∧ 密钥齐备）。
+ * 根字段可空：取数失败只让该字段为 null，故取 NonNullable 元素类型，null 由 runtime.ts 归一为空集合。
+ */
+export type RuntimeModel = NonNullable<RuntimeBootQuery['runtimeModels']>[number];
+export type RuntimeConnection = RuntimeModel['connection'];
+/** 本次可读项目 + 其生效绑定（模型引用已按可用目录校验，失效为 null）。 */
+export type RuntimeProject = NonNullable<RuntimeWorkspaceProjectsQuery['runtimeProjects']>[number];
+export type RuntimeModelCredential = NonNullable<RuntimeBootQuery['runtimeModelCredentials']>[number];
+export type { InputModality, ModelProtocol, ReasoningLevel };
+/** dsh 通用 provider 的 api 适配器（`llm-pi-ai.providers[].api`）。 */
+export type ProviderApi = 'openai-completions' | 'openai-responses' | 'anthropic-messages';
+/** 路由键 hex 对人无意义：用 `displayName` 覆盖显示名（`llm-pi-ai` 语义：`displayName ?? 路由键`）。 */
+export declare const CONSOLE_PROVIDER_DISPLAY_NAME = "semi2-hub";
+/** 路由键必须留 hex——协议路由与 `agent-default-model` 都引用它。 */
+export declare function connectionRoute(connectionId: string): string;
+/**
+ * 一条连接在 dsh 里的路由键。
+ *
+ * 预设连接直接用**预设 id**（= dsh 的提供方路由 id）：`llm-pi-ai` 只在路由名能对上已装目录时
+ * 才复用那份目录条目（compat / headers / cost / thinkingLevelMap），换个名字这些全丢。
+ * 自定义连接没有可对应的目录条目，用自铸的 hex 路由 + 显式 `api` / `baseURL`。
+ *
+ * DEEPSEEK 协议走内置原生适配器（独立于 pi-ai 目录），与预设/自定义无关。
+ */
+export declare function connectionProviderName(connection: RuntimeConnection): string;
+/** 密钥的进程 env 名（= dsh credentials 引用名）。 */
+export declare function connectionApiKeyEnv(connectionId: string): string;
+export declare function protocolApi(protocol: ModelProtocol): ProviderApi;
+export declare function modelName(model: RuntimeModel): string;
+/** provider = 路由键、model = 上游模型 id。 */
+export interface ModelSelection {
+    provider: string;
+    model: string;
+}
+/** `llm-pi-ai` 的单个 provider。 */
+export interface CompiledProvider {
+    /**
+     * true = 路由键是 dsh 的提供方 id，profile 交给目录 provider 解析
+     * （`api` / `baseURL` 留空，让目录逐模型给）。false = 自铸路由，必须自带这两项。
+     */
+    preset: boolean;
+    /** 来源连接：路由被本地配置占用时，用它的 id 生成自铸路由名。 */
+    connectionId: string;
+    api: ProviderApi;
+    baseURL: string;
+    apiKeyEnv: string;
+    displayName: string;
+    models: Array<Record<string, unknown>>;
+}
+/** 写入 settings 的 profile：预设路由省略 `api` / `baseURL`，其余按需带上。 */
+export declare function providerProfile(compiled: CompiledProvider): object;
+/**
+ * 按实际落地的路由表改写选择。路由让位（同名用户 profile）后，编译期算出的
+ * 路由键已不是最终值，默认模型与项目 plan/execute 都必须跟着换。
+ */
+export declare function remapSelections(compiled: CompiledConfiguration, routes: ReadonlyMap<string, string>): CompiledConfiguration;
+/** `llm-deepseek` settings 段（覆盖内置 deepseek-official 的连接事实）。 */
+export interface CompiledDeepSeek {
+    apiKeyEnv: string;
+    baseURL: string;
+    models: Array<{
+        id: string;
+        name: string;
+        contextWindow?: number;
+        maxTokens?: number;
+        inputModalities?: Array<'text' | 'image'>;
+    }>;
+}
+export interface CompiledConfiguration {
+    /** 非 DEEPSEEK 协议：注册到 llm-pi-ai 的 provider（键 = 路由 id）。 */
+    providers: Record<string, CompiledProvider>;
+    /** DEEPSEEK 协议：覆盖内置 llm-deepseek 的段（无 DEEPSEEK 连接为 null）。 */
+    deepseek: CompiledDeepSeek | null;
+    /** 全局默认模型的生效选择；未配/失效为 null。 */
+    defaultModel: ModelSelection | null;
+    /** semi2-hub 模型 id → 生效选择（项目 CNB 的 plan/execute 按它解析）。 */
+    selections: Map<string, ModelSelection>;
+}
+export declare function compileBoot(models: readonly RuntimeModel[], defaultModelId: string | null): CompiledConfiguration;

package/lib/types/configuration/credentials.d.ts

@@ -0,0 +1,35 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Semi2Runtime } from '../contract.js';
+export declare const CONFIG_URL_REF = "SEMI2_CONFIG_URL";
+export declare const ACCESS_TOKEN_REF = "SEMI2_ACCESS_TOKEN";
+/** 连接 semi2-hub 的凭据；两项齐备才算可连。 */
+export interface ConnectionCredentials {
+    url: string;
+    token: string;
+    /** 凭据来源层：`runtime`（运行面契约）/ dsh 提供的 `env`/`user-env`/`file` 等。 */
+    source: string;
+}
+/** 一条腿的解析结果。 */
+interface ResolvedField {
+    value: string;
+    source: string;
+}
+/** 连接凭据两条腿各自的解析结果：**可能只知道地址而还没有令牌**（本地容器未登录时就是这样）。 */
+export interface ConnectionFields {
+    url?: ResolvedField;
+    token?: ResolvedField;
+}
+/** 两条腿齐备才算可连；只有地址时调用方用 `url.value` 预填登录表单。 */
+export declare function connectionOf(fields: ConnectionFields): ConnectionCredentials | null;
+/** 分别解析地址与令牌（不做齐备性判定）：`resolveConnection` 与状态回报共用这条路。 */
+export declare function resolveConnectionFields(ctx: Context, runtimeContract: Semi2Runtime | undefined, environment?: NodeJS.ProcessEnv): Promise<ConnectionFields>;
+/** 解析当前连接凭据；缺任一项返回 null（调用方据此不注入）。 */
+export declare function resolveConnection(ctx: Context, runtimeContract: Semi2Runtime | undefined, environment?: NodeJS.ProcessEnv): Promise<ConnectionCredentials | null>;
+/** 写入登录凭据；env 遮蔽 token 时 dsh 会拒绝——由调用方转成可读错误。 */
+export declare function storeConnection(ctx: Context, input: {
+    url: string;
+    token: string;
+}): Promise<void>;
+/** 清除登录凭据（不触碰运行面契约/env 提供的凭据）。 */
+export declare function clearConnection(ctx: Context): Promise<void>;
+export {};

package/lib/types/configuration/generated/graphql.d.ts

@@ -0,0 +1,100 @@
+/** Internal type. DO NOT USE DIRECTLY. */
+type Exact<T extends {
+    [key: string]: unknown;
+}> = {
+    [K in keyof T]: T[K];
+};
+/** Internal type. DO NOT USE DIRECTLY. */
+export type Incremental<T> = T | {
+    [P in keyof T]?: P extends ' $fragmentName' | '__typename' ? T[P] : never;
+};
+export type InputModality = 'IMAGE' | 'TEXT';
+export type ModelProtocol = 'ANTHROPIC' | 'DEEPSEEK' | 'OPENAI_CHAT' | 'OPENAI_RESPONSES';
+export type ReasoningLevel = 'HIGH' | 'LOW' | 'MAX' | 'MEDIUM' | 'MINIMAL' | 'OFF' | 'XHIGH';
+/** 技能附件内容的编码：文本类用 UTF8，其余（图片 / 二进制）用 BASE64。 */
+export type SkillFileEncoding = 'BASE64' | 'UTF8';
+export type RuntimeBootQueryVariables = Exact<{
+    [key: string]: never;
+}>;
+export type RuntimeBootQuery = {
+    runtimeDefaultModelId: string | null;
+    runtimeViewer: {
+        id: string;
+        username: string;
+        displayName: string;
+    } | null;
+    runtimeModels: Array<{
+        id: string;
+        upstreamId: string;
+        displayName: string | null;
+        metadata: {
+            contextWindow: number | null;
+            maxTokens: number | null;
+            input: Array<InputModality> | null;
+            reasoningLevels: Array<ReasoningLevel> | null;
+        };
+        connection: {
+            id: string;
+            provider: string | null;
+            protocol: ModelProtocol;
+            baseUrl: string;
+        };
+    }> | null;
+    runtimeModelCredentials: Array<{
+        connectionId: string;
+        value: string;
+    }> | null;
+    runtimeSkills: Array<{
+        id: string;
+        projectId: string | null;
+        name: string;
+        description: string;
+        whenToUse: string | null;
+        content: string;
+        version: number;
+        fileCount: number;
+        filesBytes: number;
+        files: Array<{
+            path: string;
+            sizeBytes: number;
+            mimeType: string;
+            isExecutable: boolean;
+        }>;
+    }> | null;
+};
+export type RuntimeSkillFilesQueryVariables = Exact<{
+    skillId: string | number;
+}>;
+export type RuntimeSkillFilesQuery = {
+    runtimeSkillFiles: Array<{
+        path: string;
+        content: string;
+        encoding: SkillFileEncoding;
+        sizeBytes: number;
+        mimeType: string;
+        isExecutable: boolean;
+    }> | null;
+};
+export type RuntimeWorkspaceProjectsQueryVariables = Exact<{
+    slugs?: Array<string> | string | null | undefined;
+}>;
+export type RuntimeWorkspaceProjectsQuery = {
+    runtimeProjects: Array<{
+        id: string;
+        slug: string;
+        name: string;
+        enabled: boolean;
+        planModelId: string | null;
+        executeModelId: string | null;
+    }> | null;
+};
+export type RuntimeModelCredentialsQueryVariables = Exact<{
+    connectionIds?: Array<string | number> | string | number | null | undefined;
+}>;
+export type RuntimeModelCredentialsQuery = {
+    runtimeModelCredentials: Array<{
+        connectionId: string;
+        value: string;
+    }> | null;
+};
+export {};