@deepseek-ai/dsh-llm-deepseek-api-key 0.1.7-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,46 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/llm/llm-deepseek-api-key/README.md
+/:
+  en: 3bc991d01c87c9c6
+  zh: ba63ebb46b72bc3e
+/deepseek-ai-dsh-llm-deepseek-api-key:
+  en: b6871195e386cc64
+  zh: 742b05a3ca80883c
+/deepseek-ai-dsh-llm-deepseek-api-key/summary:
+  en: ad5a00f16f233d42
+  zh: 743d55599144836b
+/deepseek-ai-dsh-llm-deepseek-api-key/table-of-contents:
+  en: 23386452a66b2fbd
+  zh: 4cf93c4bf17b3da2
+/deepseek-ai-dsh-llm-deepseek-api-key/use-this-package:
+  en: ab3d8cc5be370482
+  zh: 8a8b9871d5afe1df
+/deepseek-ai-dsh-llm-deepseek-api-key/understand-the-implementation:
+  en: a2a213e5629a569f
+  zh: eb23478d0081270a
+/deepseek-ai-dsh-llm-deepseek-api-key/further-exploration:
+  en: e8bf99d78aa7035f
+  zh: e4a74d2d48b6d271
+/deepseek-ai-dsh-llm-deepseek-api-key/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/deepseek-ai-dsh-llm-deepseek-api-key/model-experience/authenticated-model-requests:
+  en: 5cf024f0d3370159
+  zh: ed480db8f348a42f
+/deepseek-ai-dsh-llm-deepseek-api-key/model-experience/authenticated-model-requests/what-the-model-sees:
+  en: e5624a2c7bb26e90
+  zh: 44da0286a548f24a
+/deepseek-ai-dsh-llm-deepseek-api-key/model-experience/authenticated-model-requests/token-effect:
+  en: fecefb75b719c317
+  zh: f0c2322f657c5914
+/deepseek-ai-dsh-llm-deepseek-api-key/model-experience/authenticated-model-requests/kv-cache-effect:
+  en: 2004df60d997da79
+  zh: a215a6586b44746b
+/deepseek-ai-dsh-llm-deepseek-api-key/known-limitations-and-deferred-work:
+  en: d5880c883b1b678f
+  zh: bf7a4da24ba75280
+/deepseek-ai-dsh-llm-deepseek-api-key/known-limitations-and-deferred-work/dev-note:
+  en: 0525041e573e96b6
+  zh: b05ed8d852498e6b

package/README.md

@@ -0,0 +1,78 @@
+---
+description: "DeepSeek api-key authentication and model discovery."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-llm-deepseek-api-key
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Register authentication and model discovery for `deepseek-official`. This plugin shares the [Messages transport](../llm-deepseek/README.md) and owns credential resolution and catalog availability.
+
+Authentication resolution returns the validated API key in `x-api-key` for both Messages and Files requests.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+<a id="use-this-package"></a>
+## Use this package
+
+`apiKeyEnv` defaults to `DEEPSEEK_API_KEY` and resolves per request. When the credentials service exists, its precedence applies; only compositions without that service read the launch environment directly. Requests with missing credentials fail with `MISSING_CREDENTIAL`; malformed credentials fail with `INVALID_CREDENTIAL`. Model discovery returns the configured catalog regardless of credentials.
+
+```yaml
+- id: llm-deepseek
+  name: '@deepseek-ai/dsh-llm-deepseek-api-key'
+  config:
+    reasoningEffort: high
+    apiKeyEnv: DEEPSEEK_API_KEY
+```
+
+The endpoint and credential reference come from one configuration resolution. In-flight requests retain that snapshot; subsequent updates affect subsequent calls. Account login state cannot change this route’s credential.
+
+`models` is an independently configurable catalog for this provider; defaults and protocol capabilities come from the shared transport. Discovery does not probe inference endpoints. The settings namespace is the Cordis entry id, or the plugin name without an entry. Product profiles retain the official entry id `llm-deepseek` and use `llm-deepseek-account` for the account route.
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+Registrations and listeners dispose with the plugin. Shared Host wiring supplies attachments, request extensions, anonymous identity, and atomic retry-policy updates; this plugin registers only its own route. No invariant companion is published: discovery derives directly from configuration without an independent copy.
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+[LLM streaming](../../../docs/subsystems/llm-streaming.md) · [Messages](../llm-deepseek/README.md)
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Authenticated model requests
+
+#### What the model sees
+
+Requests on `deepseek-official` add no model-visible text from this plugin; the shared Messages transport serializes requests.
+
+#### Token effect
+
+Authentication and discovery add no input tokens; the selected model and request content determine actual usage.
+
+#### KV Cache effect
+
+Credentials and catalog availability do not enter model input; the protocol transport owns request-prefix serialization.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- The catalog is configuration metadata, not remote validation that a model is accepted; actual calls can still fail.
+
+<a id="dev-note"></a>
+### Dev Note
+
+Registration and authentication tests also cover the Loader composition in the shared transport package.

package/README.zh.md

@@ -0,0 +1,78 @@
+---
+description: "DeepSeek API key authentication and model discovery."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-llm-deepseek-api-key
+
+[English](README.md) | 中文
+
+## 概述
+
+为 `deepseek-official` 注册独立的鉴权和模型发现插件。通过 [llm-deepseek](../llm-deepseek/README.zh.md) 共用 Messages 请求实现；本包拥有凭据解析和目录可用性判断。
+
+鉴权解析将验证后的 API key 放入 `x-api-key`，供 Messages 和 Files 请求共同使用。
+
+## 目录
+
+- [使用此包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与后续工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+<a id="use-this-package"></a>
+## 使用此包
+
+`apiKeyEnv` 默认为 `DEEPSEEK_API_KEY`，在每次请求时解析凭据。已组合 credentials 服务时，按其优先级解析；只有未组合该服务时才直接读取启动环境。请求时凭据缺失以 `MISSING_CREDENTIAL` 失败；格式错误以 `INVALID_CREDENTIAL` 失败。模型发现始终返回配置的目录，不依赖凭据。
+
+```yaml
+- id: llm-deepseek
+  name: '@deepseek-ai/dsh-llm-deepseek-api-key'
+  config:
+    reasoningEffort: high
+    apiKeyEnv: DEEPSEEK_API_KEY
+```
+
+端点和凭据引用来自同一次配置解析；进行中的请求保留该快照，后续配置更新仅影响后续请求。账号登录态不影响该路由使用的凭据。
+
+`models` 是该 provider 独立的可配置目录；默认值和协议能力来自共享传输包。目录判断不探测推理端点。设置命名空间采用 Cordis entry id，没有 entry 时采用插件名。产品保留 official 的 `llm-deepseek` entry id，账号使用 `llm-deepseek-account`。
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+注册和监听随插件生命周期释放。共享 Host 绑定提供附件访问、请求扩展、匿名标识和重试策略的原子更新；本包只注册自己的路由。无需 invariant companion：目录直接由配置派生，不维护独立副本。
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+[LLM streaming](../../../docs/subsystems/llm-streaming.zh.md) · [Messages](../llm-deepseek/README.zh.md)
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 已鉴权的模型请求
+
+#### What the model sees
+
+`deepseek-official` 请求不包含本插件添加的模型可见文本；请求由共享 Messages 传输序列化。
+
+#### Token effect
+
+鉴权和目录过滤不增加输入 token；实际调用的 token 由所选模型与请求内容决定。
+
+#### KV Cache effect
+
+凭据与目录可用性不进入模型输入；协议传输拥有请求前缀的序列化。
+
+## 已知限制与后续工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- 目录是配置元数据，不验证远端是否接受模型；实际调用仍可能失败。
+
+<a id="dev-note"></a>
+### 开发备注
+
+注册与鉴权的测试也覆盖共享传输包中的 Loader 组合场景。

package/lib/index.js

@@ -0,0 +1,69 @@
+import { LlmError, assertUsableApiKey } from "@deepseek-ai/dsh-llm";
+import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
+import { catalogModelInfo, deepSeekConfigFields, plainOptions as plainOptions$1, registerDeepSeekProvider, resolveAdapterOptions as resolveAdapterOptions$1 } from "@deepseek-ai/dsh-llm-deepseek";
+import z from "@deepseek-ai/schemastery";
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
+//#region lib/types/config.js
+const Config = z.object({
+	...deepSeekConfigFields,
+	apiKeyEnv: z.string().role("credential-ref").default("DEEPSEEK_API_KEY").volatile()
+});
+/** Read one validated provider configuration.
+* @param config - live plugin configuration.
+* @returns detached resolver inputs.
+*/
+function plainOptions(config) {
+	return {
+		...plainOptions$1(config),
+		apiKeyEnv: config.apiKeyEnv.get()
+	};
+}
+/** Resolve API-key and protocol settings together.
+* @param config - raw deployment settings.
+* @param environment - application launch environment.
+* @returns validated endpoint facts and the matching credential reference.
+*/
+function resolveAdapterOptions(config, environment) {
+	return {
+		...resolveAdapterOptions$1(config, environment),
+		apiKeyEnv: credentialRef(config.apiKeyEnv ?? "DEEPSEEK_API_KEY")
+	};
+}
+//#endregion
+//#region lib/types/index.js
+const name = "llm-deepseek-api-key";
+const inject = ["llm"];
+const PROVIDER = "deepseek-official";
+function apply(ctx, config) {
+	const options = () => resolveAdapterOptions(plainOptions(config), launchEnvironmentOf(ctx));
+	options();
+	const resolveApiKey = async (connection) => {
+		const ref = connection.apiKeyEnv;
+		const credentials = ctx.get("credentials");
+		if (credentials !== void 0) {
+			const hit = await credentials.resolve(ref);
+			if (hit !== void 0) return assertUsableApiKey(hit.value, "llm-deepseek", ref);
+		} else {
+			const ambient = launchEnvironmentOf(ctx).get(ref);
+			if (ambient !== void 0 && ambient.value.length > 0) return assertUsableApiKey(ambient.value, "llm-deepseek", ref);
+		}
+		throw new LlmError(`llm-deepseek: no API key for provider route "${PROVIDER}"; store ${ref} through the credentials service (the web Models page writes it), or export ${ref} in the launching environment`, "MISSING_CREDENTIAL");
+	};
+	ctx.llm.registerConfigurableProviders([{
+		provider: PROVIDER,
+		displayName: "DeepSeek",
+		settingsNs: ctx.fiber.entry?.options.id ?? "llm-deepseek-api-key",
+		settingsPath: []
+	}]);
+	registerDeepSeekProvider(ctx, PROVIDER, {
+		options,
+		providerName: "DeepSeek",
+		resolveAuth: async (connection) => ({ headers: { "x-api-key": await resolveApiKey(connection) } }),
+		discoverModels: (provider) => {
+			const connection = options();
+			return Promise.resolve(connection.models.map((model) => catalogModelInfo(provider, model)));
+		}
+	});
+}
+//#endregion
+export { Config, apply, inject, name, plainOptions, resolveAdapterOptions };

package/lib/types/config.d.ts

@@ -0,0 +1,74 @@
+/** API-key configuration resolved together with one Messages endpoint generation. */
+import type { Volatile } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { type CredentialRef } from '@deepseek-ai/dsh-credentials';
+import type { LaunchEnvironmentSnapshot } from '@deepseek-ai/dsh-launch-environment';
+import { type Config as ProtocolConfig } from '@deepseek-ai/dsh-llm-deepseek';
+import type { Options as ProtocolOptions, DeepSeekConnectionOptions } from '@deepseek-ai/dsh-llm-deepseek';
+/** Messages configuration with a per-request API-key reference. */
+export interface Config extends ProtocolConfig {
+    /** Credential reference resolved per request; defaults to DEEPSEEK_API_KEY. */
+    apiKeyEnv: Volatile<string>;
+}
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    apiKeyEnv: z<string, string, "volatile-defined">;
+    baseURL: z<string, string, "volatile">;
+    thinking: z<"enabled" | "disabled", "enabled" | "disabled", "volatile">;
+    reasoningEffort: z<"low" | "off" | "high" | "max", "low" | "off" | "high" | "max", "volatile">;
+    maxTokens: z<number, number, "volatile-defined">;
+    defaultContextWindow: z<number, number, "volatile-defined">;
+    models: z<NoInfer<import("@deepseek-ai/dsh-llm-deepseek").DeepSeekCatalogModel[]>, NoInfer<import("@deepseek-ai/dsh-llm-deepseek").DeepSeekCatalogModel[]>, "volatile-defined">;
+    streamIdleTimeoutMs: z<number, number, "volatile-defined">;
+    maxRequestFilesBytes: z<number, number, "volatile-defined">;
+    maxInlineRequestImageBytes: z<number, number, "volatile-defined">;
+    maxImagesPerRequest: z<number, number, "volatile-defined">;
+    imageOffloadByteQuantum: z<number, number, "volatile-defined">;
+    inlineImageOffloadByteQuantum: z<number, number, "volatile-defined">;
+    imageOffloadCountQuantum: z<number, number, "volatile-defined">;
+    filesApiTimeoutMs: z<number, number, "volatile-defined">;
+    fileExpiresAfterSeconds: z<number, number, "volatile-defined">;
+    fileRefreshMarginSeconds: z<number, number, "volatile-defined">;
+    fileQuotaCleanupBatch: z<number, number, "volatile-defined">;
+    retryPolicy: z<NoInfer<import("@deepseek-ai/dsh-llm").RetryPolicyConfig>, NoInfer<import("@deepseek-ai/dsh-llm").RetryPolicyConfig>, "volatile">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    apiKeyEnv: z<string, string, "volatile-defined">;
+    baseURL: z<string, string, "volatile">;
+    thinking: z<"enabled" | "disabled", "enabled" | "disabled", "volatile">;
+    reasoningEffort: z<"low" | "off" | "high" | "max", "low" | "off" | "high" | "max", "volatile">;
+    maxTokens: z<number, number, "volatile-defined">;
+    defaultContextWindow: z<number, number, "volatile-defined">;
+    models: z<NoInfer<import("@deepseek-ai/dsh-llm-deepseek").DeepSeekCatalogModel[]>, NoInfer<import("@deepseek-ai/dsh-llm-deepseek").DeepSeekCatalogModel[]>, "volatile-defined">;
+    streamIdleTimeoutMs: z<number, number, "volatile-defined">;
+    maxRequestFilesBytes: z<number, number, "volatile-defined">;
+    maxInlineRequestImageBytes: z<number, number, "volatile-defined">;
+    maxImagesPerRequest: z<number, number, "volatile-defined">;
+    imageOffloadByteQuantum: z<number, number, "volatile-defined">;
+    inlineImageOffloadByteQuantum: z<number, number, "volatile-defined">;
+    imageOffloadCountQuantum: z<number, number, "volatile-defined">;
+    filesApiTimeoutMs: z<number, number, "volatile-defined">;
+    fileExpiresAfterSeconds: z<number, number, "volatile-defined">;
+    fileRefreshMarginSeconds: z<number, number, "volatile-defined">;
+    fileQuotaCleanupBatch: z<number, number, "volatile-defined">;
+    retryPolicy: z<NoInfer<import("@deepseek-ai/dsh-llm").RetryPolicyConfig>, NoInfer<import("@deepseek-ai/dsh-llm").RetryPolicyConfig>, "volatile">;
+}>>, "plain">;
+/** Plain deployment inputs for the API-key provider. */
+export type Options = ProtocolOptions & {
+    apiKeyEnv?: string;
+};
+/** Endpoint and credential reference captured from the same configuration generation. */
+export interface ResolvedDeepSeekOptions extends DeepSeekConnectionOptions {
+    /** Credential reference used only for this connection snapshot. */
+    apiKeyEnv: CredentialRef;
+}
+/** Read one validated provider configuration.
+ * @param config - live plugin configuration.
+ * @returns detached resolver inputs.
+ */
+export declare function plainOptions(config: Config): Options;
+/** Resolve API-key and protocol settings together.
+ * @param config - raw deployment settings.
+ * @param environment - application launch environment.
+ * @returns validated endpoint facts and the matching credential reference.
+ */
+export declare function resolveAdapterOptions(config: Options, environment?: LaunchEnvironmentSnapshot): ResolvedDeepSeekOptions;
+//# sourceMappingURL=config.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,9 @@
+/** API-key authentication and discovery for the official DeepSeek route. */
+import type { Context } from '@deepseek-ai/cordis';
+import { Config } from './config.ts';
+export { Config, plainOptions, resolveAdapterOptions } from './config.ts';
+export type { Options, ResolvedDeepSeekOptions } from './config.ts';
+export declare const name = "llm-deepseek-api-key";
+export declare const inject: string[];
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@deepseek-ai/dsh-llm-deepseek-api-key",
+  "description": "DeepSeek api-key provider authentication and discovery",
+  "version": "0.1.7-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/llm/llm-deepseek-api-key"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-llm": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-llm-deepseek": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-launch-environment": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-credentials": "0.1.7-rc.2",
+    "@deepseek-ai/cordis-plugin-loader": "~1.0.5"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-llm": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-llm-deepseek": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-launch-environment": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-credentials": "0.1.7-rc.2",
+    "@deepseek-ai/cordis-plugin-loader": "~1.0.5"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis-plugin-loader": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.4"
+  }
+}