@siliconflow-official/dsh-llm-siliconflow 0.1.0-rc.5

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+Copyright (c) 2026 SiliconFlow
+
+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.md

@@ -0,0 +1,168 @@
+# @siliconflow-official/dsh-llm-siliconflow
+
+面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) LLM 接缝的 SiliconFlow chat-completions 适配器插件：用直接 `fetch` + SSE（由 `eventsource-parser` 分帧）把 SiliconFlow 的 OpenAI 兼容线上格式翻译成 `StreamChunk` 协议。SiliconFlow 托管着广泛的开源模型目录，其中包含 delta 携带 `reasoning_content` 的推理模型（DeepSeek-R1、QwQ、Kimi-K2-Thinking）——适配器把该通道翻译成 harness reasoning 块，并在工具调用轮次按这些模型的要求将其回传。
+
+本包拥有 `siliconflow` 提供方路由，因此部署只需提供一个 SiliconFlow API key 即可使用。其模型选择器从实时 `GET /models?sub_type=chat` 列表按端点顺序填充；配置的 `models` 列表是在没有 key 或发现失败时展示的回退目录。这是一个纯 OpenAI 兼容端点，没有 `thinking`/`reasoning_effort` 开关，因此适配器不暴露任何推理档位元数据、也不序列化任何推理档位字段：推理模型通过其目录 id 选择，请求上显式指定 `reasoningEffort` 会在网络 I/O 前以 `UNSUPPORTED_REASONING_EFFORT` 被拒绝。为 `siliconflow` 注册另一个适配器会抛出 `LlmError('DUPLICATE_ADAPTER')`。
+
+包根导出 Cordis 插件契约与 `SiliconFlowAdapter`；线上序列化、SSE 解析、chunk 翻译与发现辅助函数不属于该根契约。
+
+本项目由 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 dsh agent 开发完成——实现、单元测试与覆盖率、工程化质量门禁、GitHub 仓库与 CI、文档，均在一个 dsh 会话内完成。
+
+## 安装
+
+一行命令装进任意 profile：
+
+```sh
+dsh plugin --profile <name> add @siliconflow-official/dsh-llm-siliconflow
+```
+
+该命令由 `dsh plugin` 转发给 pnpm，把本包装进 profile 并把它声明的 bundle patch（`cordis.patch.yml`，自动挂载 `siliconflow` 路由）合并进 `dsh.profile.bundles`。`@deepseek-ai/dsh-*` 以 peerDependencies 声明，由 harness 安装闭包在运行时提供，无需重复打包。
+
+装完后运行随包发布的配置向导，交互式地填 key、拉取实时模型列表并把它设为默认渠道：
+
+```sh
+dsh-siliconflow-setup
+```
+
+向导依次：询问是否把 SiliconFlow 设为默认渠道 → 未找到 `SILICONFLOW_API_KEY` 时引导填写并写入 `$DSH_HOME/.credentials.yaml` → 用 key 做 live discovery 拉取 `/models?sub_type=chat` 列表（失败则回退到内置目录）→ 选择默认模型 → 写入 `$DSH_HOME/settings.yaml` 的 `agent-default-model`。它只读 `$DSH_HOME`（缺省 `~/.dsh`），不改动 harness 本体。
+
+不想用向导时，装完填一个 key 即可使用：
+
+```sh
+export SILICONFLOW_API_KEY=sk-...   # 或写入 $DSH_HOME/.credentials.yaml
+```
+
+在包发布到 npm 之前，先用 `pnpm install && pnpm build` 构建出 `lib/`，再从本地路径安装：
+
+```sh
+dsh plugin --profile <name> add /path/to/dsh-llm-siliconflow
+```
+
+本代码派生自 MIT 许可的 DeepSeek Harness `llm-deepseek` 适配器；见 [LICENSE](LICENSE)。
+
+## 启动
+
+插件随 profile 挂载，启动方式不影响其可用性——`npx`、本地或全局安装的 `dsh` 都读同一个 `$DSH_HOME`（缺省 `~/.dsh`）下的 profile。
+
+### 用 npx 启动（无需本地安装 dsh）
+
+```sh
+npx @deepseek-ai/dsh plugin --profile web add @siliconflow-official/dsh-llm-siliconflow  # 装到 web profile
+npx @siliconflow-official/dsh-llm-siliconflow                                            # 交互式 setup
+npx @deepseek-ai/dsh web                                                        # 打开 http://127.0.0.1:3080
+```
+
+`npx @siliconflow-official/dsh-llm-siliconflow` 运行本包唯一 bin（`dsh-siliconflow-setup`），与被装进哪个 profile 无关——setup 只读写 `$DSH_HOME` 下的 credentials 与 settings。
+
+### 后台启动
+
+后台只是进程脱离终端，不影响插件加载；唯一要求是 `dsh-siliconflow-setup` 是交互式向导，须先前台、在有 TTY 的环境跑一次。
+
+```sh
+# web UI 常驻后台（默认 http://127.0.0.1:3080；远程访问需把 host 配成 0.0.0.0）
+nohup npx @deepseek-ai/dsh web > ~/.dsh/web.log 2>&1 &
+
+# headless 后台跑一次性任务
+nohup npx @deepseek-ai/dsh --profile headless "任务" > ~/.dsh/task.log 2>&1 &
+```
+
+## 配置
+
+```yaml
+- id: llm-siliconflow
+  name: '@siliconflow-official/dsh-llm-siliconflow'
+  config:
+    apiKeyEnv: SILICONFLOW_API_KEY # default; resolved per request via ctx.credentials, then the environment
+    baseURL: https://api.siliconflow.cn/v1 # optional; $SILICONFLOW_BASE_URL then the public API when omitted
+    maxTokens: 8192         # optional positive per-request output cap; this is the default
+    streamIdleTimeoutMs: 300000 # optional; positive finite Node timer delay; five-minute default
+    retryPolicy:            # optional; omission uses bounded normal defaults
+      mode: normal          # normal | always
+      backoff:
+        initialDelayMs: 500
+        maxDelayMs: 10000
+        jitterRatio: 0.1
+    defaultContextWindow: 32768 # optional positive-integer fallback; this is the default
+    models:                 # optional; the fallback catalog shown when discovery cannot run
+      - id: zai-org/GLM-5.2
+      - id: deepseek-ai/DeepSeek-V4-Flash
+```
+
+插件把单个提供方路由 `siliconflow` 连同其已解析的 `retryPolicy` 一并注册。请求用 `provider: siliconflow` 选中它；其 `model` 原样作为线上 `model` 字符串透传，因此更换 SiliconFlow 模型不需要生命周期级重新注册。线上模型 id 是 SiliconFlow 的 `org/model` 写法（如 `deepseek-ai/DeepSeek-V4-Flash`），绝不是短别名。省略 `models` 时保留一份由六个当前托管对话模型组成的小回退目录；显式列表会替换这些默认值，而 `models: []` 则一个都不通告。目录条目通过 `ctx.llm.listModels('siliconflow')` 暴露给 ACP 编辑器与 Web 选择器这类客户端，但始终是建议性的：未列出的模型 id 依然原样透传。省略的条目名默认等于其 id。
+
+`contextWindow` 按模型可选。`ctx.llm.resolveModelInfo('siliconflow', model).context` 先返回精确值——来自配置条目或温热的发现缓存——再对未被任何来源定容的模型回退到 `defaultContextWindow`。适配器默认值是 32,768；SiliconFlow 目录大致横跨 8k 到 1M 上下文（GLM-5.2、DeepSeek-V4-Pro/Flash 均支持 1M），因此披露了上下文的发现列表是权威值，回退值仅在没有任何来源披露时使用。对压力敏感的插件由此获得部署自有的容量，而不把模型选择器当作权威。
+
+`maxTokens` 是对话请求的适配器级输出上限，默认 8,192。目录条目可携带自己的 `maxTokens`，对该模型优先生效；没有该字段的条目以及任何未列出的透传 id 解析为配置值。精确模型解析把胜出者暴露为 `defaultMaxTokens`；`LlmRuntime` 在 agent 循环写 `request/header` 之前把该值物化进 `GenerateOptions.maxTokens`，因此线上请求可重建。显式请求或 `AgentOptions.maxTokens` 值优先，并被序列化为 `max_tokens`。适配器不会把该请求预算对照 `contextWindow` 裁剪；上下文更小或有提供方输出限制的部署必须配置兼容的 `maxTokens`。
+
+`streamIdleTimeoutMs` 约束每次未完成的提供方读取（包括首次 `fetch`），不计消费者在 chunk 之间花费的时间。SSE 注释会为未完成的读取重新计时作为传输活动，但永远不会成为 `StreamChunk` 值或会话日志事件。一次调用全程只有一个稳定的中止信号同时到达请求与响应体读取器；超时会停止传输并抛出 `LlmError('TIMEOUT')`，而更早的调用方中止抛出 `LlmError('ABORTED')`。适配器每次 `stream()` 调用只发一次提供方请求；它把配置的策略注册为提供方元数据，`dsh-llm-retry` 再在持久化的 agent 步骤边界单独执行它。
+
+## 动态模型发现
+
+`listModels` 通告实时对话列表而非手工维护的快照：它用已解析的 key 询问 `GET {baseURL}/models?sub_type=chat`，按**端点顺序**保留回复，并缓存五分钟。发现是建议性的、尽力而为的——缺少 key、端点不可达、凭据被拒、或回复不可读，都会回退到配置的 `models` 列表而非破坏选择器，因为空目录会整个隐藏该提供方。成功的列表同样服务于精确模型解析：静态目录未命名的模型仍能得到其列表披露的上下文窗口与输出上限。
+
+配置面的「获取可用模型」动作通过 `ctx.llm.discoverModels('llm-siliconflow', …)` 使用同一询问：表单里输入的 key 优先，否则探测已存凭据或环境变量；没有 key 的路由以未认证方式探测，因此配置面仍能回答「这个端点服务哪些模型」。
+
+## 动态配置（settings + credentials）
+
+连接事实不在加载时冻结。`resolveAdapterOptions` 是从原始配置到已校验事实的唯一显式解析步骤，适配器通过 thunk **每个操作一次** 重读它们：base URL、目录、请求默认值与空闲预算都在下一个请求生效，而进行中的流保留其启动时的事实。两个可选接缝为该 thunk 供料：
+
+- **`ctx.settings`** —— 插件用同样的 `Config` schema 注册 `llm-siliconflow` 命名空间，并把其 `cordis.yml` 条目作为组合 `base`，因此用户设置文档中的 `llm-siliconflow:` 段可以在不重启的情况下覆盖任意字段。未挂载 settings 服务时仅由条目配置驱动适配器，行为不变。一个通过 schema 但越过 schema 之外界限（如重复目录 id）的实时设置快照会保留最后的好事实并记录失败；条目配置本身仍会在插件加载时失败。
+- **`ctx.credentials`** —— API key 每个流调用解析一次，且来自提供端点的 *同一个* 已解析快照。配置只携带 `apiKeyEnv`，绝不携带明文 key：该引用通过凭证接缝解析，未挂载该接缝时通过受信任的环境层解析。由于凭证事实随连接事实一起传递，解析器拒绝的设置快照既不贡献其端点也不贡献其 key。每个解析出的 key 在使用前都做格式检查，因此 HTTP 头无法承载的值会以 `LlmError('INVALID_CREDENTIAL')` 被拒绝，并指出失败的入口点——绝不包含 key 的任何部分。任何地方都没有 key 的请求以 `MISSING_CREDENTIAL` 失败，并指出每个配置入口点，而路由保持注册、目录保持可浏览。
+
+唯一在注册时捕获的事实是重试策略：当其解析值变化时，插件原地重注册路由（同一适配器实例、一个同步区段），因此 `ctx.llm.providerRetryPolicy('siliconflow')` 始终报告当前策略。插件还会在可配置提供方目录（`ctx.llm.listConfigurableProviders()`）中声明其路由：提供方 `siliconflow`，settings 命名空间 `llm-siliconflow`，settings 路径为空。
+
+## 应用归属
+
+每个请求都携带 dsh-llm 的 `attributionHeaders()` 提供的共享归属头——标识 harness 的强制 `User-Agent` 基线。在凭证解析之后，每个提供方请求都携带 `x-siliconflow-harness-user-id`（来自 `@deepseek-ai/dsh-anonymous-user-id` 的稳定匿名 id）；携带 `GenerateOptions.sessionId` 的请求还会把该精确值作为 `x-siliconflow-harness-session-id` 发送，而没有会话的直接调用省略该会话头。`GenerateOptions.purpose` 为 `compaction` 的请求额外携带 `x-siliconflow-harness-compact: 1`。这三个头都发往已解析的 `baseURL`，并保持在请求体与模型可见内容之外。
+
+## 线上格式说明
+
+- 仅流式（`stream_options.include_usage` 始终开启）。`usage` 可能附在结束 chunk 上，也可能作为尾随的仅 usage chunk 出现——翻译器把两者都推迟到 `[DONE]`，因此 `usage` 始终先于 `finish`，且 `finish` 之后无内容。
+- 适配器从不发送 `thinking` 或 `reasoning_effort`；SiliconFlow 端点没有这些开关，推理模型通过 id 选择。
+- 推理模型首个 chunk 携带 `reasoning_content: ""` —— 已处理（不会产生多余 reasoning 块）。
+- **推理回传规则**：在携带工具调用的 assistant 轮次，`reasoning_content` 会被序列化回历史（托管的 DeepSeek-R1 类模型所要求）；无工具调用的轮次则丢弃（反正被忽略——省 token）。
+- 缓存记账：`cacheReadTokens` ← `prompt_cache_hit_tokens` / `prompt_tokens_details.cached_tokens`；SiliconFlow 不报告缓存写入指标。
+
+## 错误
+
+非 2xx 响应抛出带稳定码的 `LlmError`：`AUTH`（401/403）、`QUOTA`（提供方详情指明配额、余额或额度耗尽的响应）、`RATE_LIMIT`（其他 429）、`CONTEXT_WINDOW_EXCEEDED`（400 且其提供方 code、type 或 message 指明上下文溢出）、`INVALID_REQUEST`（其他 400）、`SERVER`（5xx）、其余 `HTTP_<status>`。其可序列化的 `failure` 保留 HTTP 状态，以及存在时的有效正 `Retry-After` 秒数/日期延迟和 `x-request-id`。响应前的传输失败（DNS、连接拒绝、TLS、代理）抛出 `TRANSPORT`，指明已配置端点并把原始拒绝链为 `cause`；调用方中止抛出 `ABORTED`，循环的取消信号保持权威。协议违规抛出 `STREAM_CLOSED`（无 `[DONE]`）或 `MALFORMED_RESPONSE`（坏 JSON payload）。未知的线上 `finish_reason`（如 `content_filter`、`insufficient_system_resource`）变为 `finish {kind: 'error', failure}` chunk；一个 `stop`（或缺省）结束但未打开任何内容块的已完成流变为 `finish {kind: 'error'}`，码为 `EMPTY_RESPONSE`（默认策略会重试）。
+
+## Model Experience
+
+### SiliconFlow 请求
+
+#### 模型看到什么
+
+选中的 SiliconFlow 模型收到 harness 系统提示、消息历史、工具 schema、停止序列与调用配置，不含适配器编写的提示文本。在先前携带工具调用的 assistant 轮次，其推理内容按要求回传；无工具调用轮次的推理被省略。
+
+#### Token 影响
+
+提供方分词决定精确输入。条件性推理回传增加工具往返上下文，而丢弃其他推理避免重复付费；缓存读取用量在可用时上报。
+
+#### KV Cache 影响
+
+未变化的组装前缀有资格被提供方缓存复用，本适配器在用量中上报。模型路由变更或任何上游提示、schema、前缀、历史变更都可能从第一个变化 token 起阻止复用；推理回传在工具往返期间追加。
+
+### SiliconFlow 响应
+
+#### 模型看到什么
+
+推理、文本与原始字符串工具参数被翻译成 harness chunk，供循环记录与组装。
+
+#### Token 影响
+
+生成 token 遵循请求记录的 `maxTokens`；只有循环保留的块影响后续输入。
+
+#### KV Cache 影响
+
+循环保留的响应块追加到下一个请求并保留其更早的可复用前缀；被丢弃的块没有后续缓存影响。更换提供方或模型会选择不同的缓存域。
+
+## Known Limitations and Deferred Work
+
+- **回退 `models` 列表是手工维护的** —— 六个默认值是一份小快照，仅在发现无法运行时展示；实时列表才是权威目录。
+- **发现不跨 baseURL 变化缓存** —— 缓存按端点键控，因此改指路由会在下一次 `listModels` 重新询问。
+- **settings 的 `models` 列表整体替换组合列表** —— settings 层合并在字段粒度进行，数组是一个字段；按条目合并目录需要键控结构。
+- **未映射 `tool_choice`** —— 不属于核心词汇表（MVP 裁剪，与 pi-ai 和 DeepSeek 双胞胎相同）。
+- **请求使用原始 `fetch`，而非 `@cordisjs/plugin-http`** —— 没有共享代理/拦截配置；待有第二个直接 fetch 适配器需要时再采用（`TODO(http)`）。
+- **序列化把 user 与 tool-result 内容扁平化为文本块** —— 插件添加的块类型被跳过，空工具输出以字面 `(no output)` 上线。
+- **图片内容被拒绝** —— 这里的 chat-completions 线上路由仅文本；多模态 SiliconFlow 路由需要自己的内容序列化器。

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# @siliconflow-official/dsh-llm-siliconflow bundle patch: mounts the SiliconFlow LLM
+# adapter into a dsh profile. Install with:
+#   dsh plugin --profile <name> add @siliconflow-official/dsh-llm-siliconflow
+# The plugin registers the `siliconflow` provider route; supply only
+# SILICONFLOW_API_KEY (or the credential store) and select a siliconflow model.
+- insert:
+    - id: llm-siliconflow
+      # Node-resolvable package name — kept in sync with package.json `name`.
+      # Quoted because `@` opens a reserved indicator in YAML.
+      name: '@siliconflow-official/dsh-llm-siliconflow'

package/lib/bin.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+import { a as PUBLIC_BASE_URL, h as discoverChatModels, i as PROVIDER, n as DEFAULT_API_KEY_ENV, r as DEFAULT_MODELS } from "./types-Bim1q3qs.js";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { parseDocument } from "yaml";
+//#region lib/types/setup.js
+/**
+* Interactive setup wizard core for {@link @siliconflow-official/dsh-llm-siliconflow}:
+* the pure steps (harness-home and document-path resolution, credential and
+* settings read/write, model-choice parsing) plus the orchestration over an
+* injected I/O face, so the thin bin entry stays untested glue and the whole
+* flow is unit-testable without a terminal.
+*
+* The wizard guides a fresh install to a working route: confirm the default
+* channel, obtain an API key, interrogate the live chat-model listing, pick a
+* default model, then persist `agent-default-model` into `settings.yaml`.
+* @module @siliconflow-official/dsh-llm-siliconflow/setup
+*/
+/** Directory name for the default DeepSeek Harness home under the OS home. */
+const DSH_HOME_DIR_NAME = ".dsh";
+/** Environment variable that overrides the default DeepSeek Harness home. */
+const DSH_HOME_ENV = "DSH_HOME";
+/** Settings namespace the wizard writes the default model into. */
+const DEFAULT_MODEL_NAMESPACE = "agent-default-model";
+/**
+* Resolve the DeepSeek Harness home: non-empty `$DSH_HOME`, else `~/.dsh`.
+* @param env - environment mapping; defaults to `process.env`.
+* @returns the normalized absolute home path.
+*/
+function resolveHome(env = process.env) {
+	const fromEnv = env[DSH_HOME_ENV];
+	return resolve(fromEnv !== void 0 && fromEnv.trim().length > 0 ? fromEnv : join(homedir(), DSH_HOME_DIR_NAME));
+}
+/** The managed credential document path under a harness home. */
+function credentialsPath(home) {
+	return join(home, ".credentials.yaml");
+}
+/** The settings document path under a harness home. */
+function settingsPath(home) {
+	return join(home, "settings.yaml");
+}
+function isEnoent(error) {
+	return error.code === "ENOENT";
+}
+/**
+* Read one credential reference from a comment-preserving document.
+* @param path - the credentials document path.
+* @param keyEnv - the top-level reference name (e.g. `SILICONFLOW_API_KEY`).
+* @returns the stored value, or `undefined` when absent or the file is missing.
+*/
+async function readCredential(path, keyEnv) {
+	let text;
+	try {
+		text = await readFile(path, "utf8");
+	} catch (error) {
+		if (isEnoent(error)) return void 0;
+		throw error;
+	}
+	const value = parseDocument(text).toJS()?.[keyEnv];
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+/**
+* Set one credential reference, preserving every other entry and comment.
+* @param path - the credentials document path; created when absent.
+* @param keyEnv - the top-level reference name to write.
+* @param key - the value.
+*/
+async function writeCredential(path, keyEnv, key) {
+	const doc = await loadDocument(path);
+	doc.set(keyEnv, key);
+	await persistDocument(path, doc);
+}
+/**
+* Replace the default-model section, preserving every other section and comment.
+* The replacement carries only `provider` and `model`, so a previous
+* `reasoningEffort` (unsupported by SiliconFlow) is dropped with the section.
+* @param path - the settings document path; created when absent.
+* @param selection - the provider/model pair to persist.
+*/
+async function writeDefaultModel(path, selection) {
+	const doc = await loadDocument(path);
+	doc.set(DEFAULT_MODEL_NAMESPACE, {
+		provider: selection.provider,
+		model: selection.model
+	});
+	await persistDocument(path, doc);
+}
+/**
+* Parse a 1-based model-choice answer.
+* @param raw - the user's answer.
+* @param count - the number of offered models.
+* @returns the 0-based index, or `undefined` when the answer is out of range.
+*/
+function parseModelIndex(raw, count) {
+	const value = Number(raw.trim());
+	if (!Number.isInteger(value) || value < 1 || value > count) return void 0;
+	return value - 1;
+}
+async function loadDocument(path) {
+	try {
+		return parseDocument(await readFile(path, "utf8"));
+	} catch (error) {
+		if (isEnoent(error)) return parseDocument("");
+		throw error;
+	}
+}
+async function persistDocument(path, doc) {
+	await mkdir(dirname(path), {
+		recursive: true,
+		mode: 448
+	});
+	await writeFile(path, doc.toString(), { mode: 384 });
+}
+/** Render one model row as a display label. */
+function labelOf(model) {
+	return model.name ?? model.id;
+}
+/** Convert a discovery listing to wizard rows, keeping endpoint order. */
+function rowsOf(entries) {
+	return entries.map((entry) => ({
+		id: entry.id,
+		...entry.name === void 0 ? {} : { name: entry.name }
+	}));
+}
+/**
+* Run the wizard: confirm the default channel, obtain a key, list models,
+* pick the default, and persist the selection. Never throws for an unroutable
+* endpoint — discovery falls back to the static catalog — but a malformed
+* existing document or an unwritable one fails loud.
+* @param deps - home, terminal face, and discovery function.
+*/
+async function runSetup(deps) {
+	const { home, io, discover } = deps;
+	const credentials = credentialsPath(home);
+	const settings = settingsPath(home);
+	if ((await io.question("是否将 SiliconFlow 设为默认渠道？ [Y/n] ")).trim().toLowerCase() === "n") {
+		io.log("已跳过。之后可在 web 的 Models 页配置，或手动编辑 settings.yaml。");
+		return;
+	}
+	let key = await readCredential(credentials, DEFAULT_API_KEY_ENV);
+	if (key === void 0) {
+		const answer = (await io.question(`未找到 ${DEFAULT_API_KEY_ENV}，请输入 API key（sk-...）：`)).trim();
+		if (answer.length === 0) io.log("未提供 key，将以未认证方式探测模型列表（列表可能受限）。");
+		else {
+			key = answer;
+			await writeCredential(credentials, DEFAULT_API_KEY_ENV, key);
+			io.log(`已写入 ${credentials}`);
+		}
+	} else io.log(`已找到 ${DEFAULT_API_KEY_ENV}。`);
+	let models;
+	try {
+		const listed = await discover(key);
+		models = listed.length > 0 ? rowsOf(listed) : DEFAULT_MODELS;
+		if (listed.length > 0) io.log(`从端点获取到 ${String(listed.length)} 个模型。`);
+	} catch (error) {
+		models = DEFAULT_MODELS;
+		io.log(`实时获取模型列表失败，回退到默认目录（${error instanceof Error ? error.message : String(error)}）。`);
+	}
+	io.log("选择默认模型：");
+	models.forEach((model, index) => {
+		io.log(`  ${String(index + 1)}) ${labelOf(model)}`);
+	});
+	let index = 0;
+	for (;;) {
+		const answer = (await io.question(`请选择 [1-${String(models.length)}]（默认 1）：`)).trim();
+		if (answer.length === 0) break;
+		const parsed = parseModelIndex(answer, models.length);
+		if (parsed === void 0) {
+			io.log(`请输入 1-${String(models.length)} 之间的编号。`);
+			continue;
+		}
+		index = parsed;
+		break;
+	}
+	const model = models[index];
+	/* v8 ignore next 3 -- models is non-empty here: discovery rows or the non-empty static catalog both supply entries */
+	if (model === void 0) throw new Error("setup: no model selected");
+	await writeDefaultModel(settings, {
+		provider: PROVIDER,
+		model: model.id
+	});
+	io.log(`已写入 ${settings}：agent-default-model = ${PROVIDER} / ${model.id}`);
+}
+//#endregion
+//#region lib/types/bin.js
+/**
+* Executable entry for the SiliconFlow setup wizard: wire the real terminal
+* and the public endpoint's live listing into {@link runSetup}. Kept as thin
+* glue so the wizard core is testable without a terminal.
+* @module @siliconflow-official/dsh-llm-siliconflow/bin
+*/
+async function main() {
+	const io = createInterface({
+		input: stdin,
+		output: stdout,
+		terminal: true
+	});
+	try {
+		await runSetup({
+			home: resolveHome(),
+			io: {
+				question: (prompt) => io.question(prompt),
+				log: (message) => stdout.write(`${message}\n`)
+			},
+			discover: (apiKey) => discoverChatModels(PUBLIC_BASE_URL, apiKey)
+		});
+	} finally {
+		io.close();
+	}
+}
+main().catch((error) => {
+	stdout.write(`setup failed: ${error instanceof Error ? error.message : String(error)}\n`);
+	process.exitCode = 1;
+});
+//#endregion
+export {};

package/lib/index.js

@@ -0,0 +1,2 @@
+import { _ as readListing, a as PUBLIC_BASE_URL, c as name, d as DEFAULT_MAX_TOKENS, f as DEFAULT_STREAM_IDLE_TIMEOUT_MS, g as listingUrl, h as discoverChatModels, i as PROVIDER, l as resolveAdapterOptions, m as SiliconFlowAdapter, n as DEFAULT_API_KEY_ENV, o as apply, p as DISCOVERY_TTL_MS, r as DEFAULT_MODELS, s as inject, t as Config, u as DEFAULT_CONTEXT_WINDOW } from "./types-Bim1q3qs.js";
+export { Config, DEFAULT_API_KEY_ENV, DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_TOKENS, DEFAULT_MODELS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DISCOVERY_TTL_MS, PROVIDER, PUBLIC_BASE_URL, SiliconFlowAdapter, apply, discoverChatModels, inject, listingUrl, name, readListing, resolveAdapterOptions };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@siliconflow-official/dsh-llm-siliconflow`.
+* @module @siliconflow-official/dsh-llm-siliconflow/invariant
+*/
+const PACKAGE_NAME = "@siliconflow-official/dsh-llm-siliconflow";
+/** Cordis companion plugin name. */
+const name = "llm-siliconflow-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this package exposes no independent event sequence or mutable data relation
+* beyond contracts enforced at its owning seam.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/adapter.d.ts

@@ -0,0 +1,114 @@
+/**
+ * `SiliconFlowAdapter`: fetch + SSE against a SiliconFlow (OpenAI-compatible)
+ * chat-completions endpoint, emitting harness StreamChunks. The adapter is
+ * transport-only: connection facts arrive through a thunk resolved once per
+ * operation and the bearer token through a per-request resolver, so the
+ * registering plugin owns validation, layering, and credential policy.
+ *
+ * @module dsh-llm-siliconflow/adapter
+ */
+import { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, ResolvedRetryPolicy, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { CredentialRef } from '@deepseek-ai/dsh-credentials';
+import type { AnonymousUserId } from '@deepseek-ai/dsh-anonymous-user-id';
+import type { WireError } from './types.ts';
+/** One optional model entry advertised by the direct-fetch adapter. */
+export interface SiliconFlowCatalogModel {
+    /** Wire model id accepted by the configured endpoint. */
+    id: string;
+    /** Selector label; defaults to {@link id}. */
+    name?: string;
+    /** Optional selector detail for deployments with similar model variants. */
+    description?: string;
+    /** Known combined request/response context capacity; omitted when deployment metadata is unavailable. */
+    contextWindow?: number;
+    /** Per-request output cap for this model; omission falls back to the profile's {@link SiliconFlowConnectionOptions.maxTokens}. */
+    maxTokens?: number;
+}
+/**
+ * Validated connection facts for one operation. The plugin's
+ * `resolveAdapterOptions` is the one explicit resolve step producing this
+ * shape; the adapter trusts it and re-reads it per operation, which is what
+ * makes a configuration change reach the next request without re-registration.
+ */
+export interface SiliconFlowConnectionOptions {
+    /** Endpoint base; `/chat/completions` is appended. */
+    baseURL: string;
+    /**
+     * Credential reference of this same resolution, resolved per request.
+     * Travelling with the endpoint is the point: a request can never pair one
+     * generation's URL with another generation's secret. Configuration carries
+     * only this name — a literal key is not a configuration value.
+     */
+    apiKeyEnv: CredentialRef;
+    /** Default per-request output cap; explicit request values win. */
+    maxTokens: number;
+    /** Positive context capacity used when the selected model has no exact value. */
+    defaultContextWindow: number;
+    /** Advisory models exposed to discovery consumers; requests remain unrestricted. */
+    models: readonly SiliconFlowCatalogModel[];
+    /** Maximum provider idle time while one stream read is outstanding. */
+    streamIdleTimeoutMs: number;
+    /** Provider-owned model-request retry policy, already resolved. */
+    retryPolicy: ResolvedRetryPolicy;
+}
+/** Constructor options for {@link SiliconFlowAdapter}: the operation-local resolution hooks the plugin owns. */
+export interface SiliconFlowAdapterOptions {
+    /** Current validated connection facts; called once per operation. */
+    options: () => SiliconFlowConnectionOptions;
+    /**
+     * Resolve the bearer token for the connection facts of one request. The
+     * snapshot is passed in — never re-read — so the key can only ever come
+     * from the same resolution as the endpoint it is sent to. Throws `LlmError`
+     * `MISSING_CREDENTIAL` when no key is available anywhere.
+     */
+    resolveApiKey: (connection: SiliconFlowConnectionOptions) => Promise<string>;
+    /** Resolve the harness-home anonymous id shared with telemetry and feedback. */
+    resolveUserId: () => AnonymousUserId;
+}
+/** Default maximum idle interval while an adapter stream read is outstanding. */
+export declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300000;
+/** Default combined request/response context capacity. */
+export declare const DEFAULT_CONTEXT_WINDOW = 32768;
+/** Default per-request output-token cap. */
+export declare const DEFAULT_MAX_TOKENS = 8192;
+/** How long a cached model-listing discovery stays fresh before the next `listModels` re-interrogates. */
+export declare const DISCOVERY_TTL_MS: number;
+/**
+ * Map an HTTP status to a stable LlmError code.
+ * @param status - status of a non-2xx provider response.
+ * @param error - parsed provider error body, when available.
+ * @returns the normalized harness error code.
+ */
+export declare function httpErrorCode(status: number, error?: WireError['error']): string;
+/**
+ * A direct-fetch `LlmAdapter` for SiliconFlow's OpenAI-compatible
+ * chat-completions endpoint. One instance serves every model name it was
+ * registered under (the harness model name IS the wire model name).
+ *
+ * One stable signal reaches both initial fetch and body reads. Caller aborts
+ * map to `ABORTED`; the configured per-read idle watchdog maps to `TIMEOUT`.
+ */
+export declare class SiliconFlowAdapter extends LlmAdapter {
+    private readonly config;
+    /** Cached listing result, keyed by the baseURL it was read from. */
+    private discovery;
+    constructor(config: SiliconFlowAdapterOptions);
+    providerInfo(provider: string): LlmProviderInfo;
+    providerRetryPolicy(_provider: string): ResolvedRetryPolicy;
+    /** The cached listing for `connection` when it is still fresh; never re-interrogates. */
+    private freshDiscovery;
+    /**
+     * The models this adapter currently advertises: the live chat listing when a
+     * key and a reachable endpoint can supply one, else the configured catalog.
+     * Discovery is advisory and best-effort — a missing key or any interrogation
+     * failure falls back to the configured `models` rather than breaking the
+     * picker, because an absent catalog would hide the provider entirely.
+     */
+    private discover;
+    listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+    resolveModel(provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    private request;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/lib/types/bin.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Executable entry for the SiliconFlow setup wizard: wire the real terminal
+ * and the public endpoint's live listing into {@link runSetup}. Kept as thin
+ * glue so the wizard core is testable without a terminal.
+ * @module @siliconflow-official/dsh-llm-siliconflow/bin
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/lib/types/discovery.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Interrogate the SiliconFlow (OpenAI-compatible) `GET /models` listing for
+ * the chat models an endpoint serves, filtered with `sub_type=chat` and kept
+ * in the endpoint's own order — SiliconFlow's listing is already ordered by
+ * its own preference, so the adapter must not re-sort it.
+ *
+ * This module is transport-only: it takes the endpoint and bearer token for
+ * one interrogation and returns the entries it read. The registering plugin
+ * owns credential policy, and the adapter owns caching and the fallback to its
+ * configured catalog.
+ *
+ * @module dsh-llm-siliconflow/discovery
+ */
+/** One chat model the listing endpoint reports. Structural subset of the adapter's catalog entry. */
+export interface SiliconFlowListingEntry {
+    /** Model id the endpoint accepts. */
+    id: string;
+    /** Human-readable name when the endpoint supplies one; selectors default to the id. */
+    name?: string;
+    /** Maximum combined request/response context in tokens, when disclosed. */
+    contextWindow?: number;
+    /** Maximum output tokens, when disclosed. */
+    maxTokens?: number;
+}
+/**
+ * Join the endpoint base with the chat-filtered listing path. The base is a
+ * prefix, not a URL to resolve against, so a gateway path such as
+ * `https://gateway.example/openai/v1` keeps its segments.
+ * @param baseURL - the chat-completions base.
+ * @returns the `GET /models?sub_type=chat` URL.
+ */
+export declare function listingUrl(baseURL: string): string;
+/**
+ * Map one listing reply into entries, preserving endpoint order. A row without
+ * a usable id is skipped rather than failing the whole interrogation: a single
+ * malformed row should not hide the rest of a working endpoint's catalog.
+ * @param body - the parsed reply body.
+ * @returns the entries in arrival order.
+ */
+export declare function readListing(body: unknown): SiliconFlowListingEntry[];
+/**
+ * Interrogate one endpoint for the chat models it advertises.
+ * @param baseURL - the chat-completions base; `/models?sub_type=chat` is appended.
+ * @param apiKey - bearer token, or `undefined` to probe unauthenticated.
+ * @param signal - caller cancellation; the fetch and body read honor it.
+ * @returns the advertised models in endpoint order.
+ * @throws LlmError when the endpoint is unreachable, refuses the request, or
+ *   the reply is not a readable listing.
+ */
+export declare function discoverChatModels(baseURL: string, apiKey: string | undefined, signal?: AbortSignal): Promise<readonly SiliconFlowListingEntry[]>;
+//# sourceMappingURL=discovery.d.ts.map