@thincoder/core 0.10.1 → 0.10.2

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 All notable changes to the core package are documented here.
 Format: Keep a Changelog · 中文 · 号在发布时定（CalVer——见 `docs/RELEASE.md` §4）。
 
+## [0.10.2] — 2026-10-03
+
+> 0.10.1 → 0.10.2（月内 +1——发布时定号）
+
+### Added
+
+- **统一 provider 解析（#841 · 三端归一）**：核导出 `resolveProviderPlan`（回退链 = 槽渠道（持 key）→ `defaultModel` 渠道 → 首个持 key 渠道；模型面 = 槽模型 → `defaultModel`（同渠道）→ 渠道单值 → `null`；三态 = `ok` ∕ `fallback` ∕ `invalid` + `reason`）与 `resolveChannelModel`（单值转口面）。
+- **`providerState` ∕ `providerStateReason` 两键**：`loadConfig()` 落（`provider` = 解析入选渠道）+ 槽面 key 门（`applySession`——槽无 key ⇒ 跳过且不写槽）。
+
+### Changed
+
+- **「无效」语义收窄**：仅「无 provider ∥ 无 key」为 `invalid`（不可运行 ⇒ 引导配置）；「可运行而无有效 `defaultModel`」为 `fallback`（**可运行 + 必明示**——不再当无效拦下）。
+
 ## [0.10.1] — 2026-10-03
 
 > 0.9.5 → 0.10.1（月切换——十月首发，发布时定号）

package/config.mjs

@@ -13,7 +13,7 @@
 
 import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
 import { dirname, join } from "node:path"
-import { parseModelRef, resolveRuntimeProvider, defaultModelReason } from "./model-ref.mjs"
+import { parseModelRef, resolveChannelModel, resolveProviderPlan, resolveRuntimeProvider, defaultModelReason } from "./model-ref.mjs"
 // 老形态迁移核（M7 v2——纯函数零依赖——本文件超 500 行硬限拆分，VSC 同构文件）
 import { migrateLegacyModelFields } from "./config-migrate.mjs"
 import { expandHome } from "./expand-home.mjs"
@@ -23,7 +23,7 @@ import {
   _configPath, writeConfigAtomic,
 } from "./config-io.mjs"
 
-export { parseModelRef, resolveRuntimeProvider, defaultModelReason, migrateLegacyModelFields }
+export { parseModelRef, resolveChannelModel, resolveProviderPlan, resolveRuntimeProvider, defaultModelReason, migrateLegacyModelFields }
 export { PROVIDER_PRESETS, presetToEntry, configDir, configPath, _setConfigPathForTest, _resetConfigPathForTest }
 // 核内单一写盘执行体（已迁 `config-io.mjs`）——本档 re-export 保持既有导入面（§2.5 #131）。
 export { writeConfigAtomic }
@@ -325,14 +325,18 @@ export function loadConfig() {
   // 保证 agent.config.proxy 永远是规范形态或 undefined
   merged.proxy = normalizeProxy(merged.proxy)
 
-  // Runtime provider = config.defaultModel 复合解析（F-2——resolveRuntimeProvider）。
-  // 无效/未设 → {} + providerInvalidReason（D-S1 处置不 throw——make-agent 打 _providerInvalid
-  // 标记 → TUI 首帧弹选择 / headless 报可读错误；同 2026-09-02 Q1 语义——不复用 findProvider
-  // throw 契约——findProvider 保留给 advisor/run.mjs 等直接调用方）。
-  merged.provider = resolveRuntimeProvider(merged.providers, merged.defaultModel)
+  // Runtime provider = 统一解析（#841——resolveProviderPlan 单源：回退序 + 三态；PROVIDER.md §6.22）。
+  // 不可运行（渠表空 ∥ 全表无 key）⇒ {} + providerInvalidReason（D-S1 处置不 throw——make-agent 打
+  // _providerInvalid 标记 → TUI 首帧弹选择 / headless 报可读错误；同 2026-09-02 Q1 语义——不复用
+  // findProvider throw 契约——findProvider 保留给 advisor/run.mjs 等直接调用方）。
+  const plan = resolveProviderPlan({ providers: merged.providers, defaultModel: merged.defaultModel })
+  merged.provider = plan.provider
+  merged.providerState = plan.state // ok ∥ fallback ∥ invalid（三值闭集——KD-841-3 config 级）
+  merged.providerStateReason = plan.reason // state≠ok 时非空（语义源；消费者按 state 出词——禁串嗅探）
+  // providerInvalidReason 语义不变（provider 不完整时非空——装配校验 validateProvider 消费面照旧）
   merged.providerInvalidReason = merged.provider.name
     ? null
-    : defaultModelReason(merged.providers, merged.defaultModel)
+    : plan.reason ?? defaultModelReason(merged.providers, merged.defaultModel)
 
   // Compaction threshold follows the model (provider-level context override honored — providerSpec)
   const explicitThreshold = config.agent?.compactThreshold

package/model-ref.mjs

@@ -11,15 +11,23 @@
  * are gone with activeProvider/activeModel (F-1), so a bare provider or bare model is
  * invalid everywhere (裁定③——裸 provider 拒——显式 p:m)。
  *
- * Runtime model resolution:
+ * Runtime model resolution (#841 单源 = resolveProviderPlan——机制全文 PROVIDER.md §6.22):
  *   parseModelRef(ref, providers)      → { ok, provider, model } | { ok:false, reason }
+ *   resolveChannelModel(entry, defaultModel)
+ *                                      → 渠道模型面单值：defaultModel 属本渠道 ⇒ 其模型段 ∥
+ *                                        渠道单值 `entry.model` ∥ null（VSC 转口面）
+ *   resolveProviderPlan({ providers, defaultModel, slot })
+ *                                      → { state, source, channel, model, provider, reason }
+ *                                        统一回退解析（纯函数 · 零 I/O——三端消费同一函数）：
+ *                                        渠道面回退序三步 + 模型面四步 + 三态 ok ∥ fallback ∥ invalid
  *   resolveRuntimeProvider(providers, defaultModel)
  *                                      → provider object with `.model` set, or {} when
  *                                        defaultModel is null/invalid (D-S1: callers mark
  *                                        _providerInvalid — never throws)
  *   defaultModelReason(providers, defaultModel) → human reason for the D-S1 marker
  *
- * Consumers: config.mjs loadConfig (re-exported as the config hub), make-agent.mjs.
+ * Consumers: config.mjs loadConfig (re-exported as the config hub), make-agent.mjs,
+ * session-lifecycle.mjs applySession（槽面）, VSC panel-turn-stages ∥ presets（核转口）。
  */
 export function parseModelRef(ref, providers) {
   if (typeof ref !== "string" || !ref.trim()) {
@@ -47,7 +55,9 @@ export function parseModelRef(ref, providers) {
 /** Resolve the runtime provider object for config.defaultModel: provider clone carrying
  *  `.model` = the parsed concrete model (API/spec consumers read provider.model unchanged).
  *  Invalid/missing defaultModel → {} (D-S1 shape — name/model/baseURL absent so
- *  validateProvider flags it; TUI/headless surface the reason from defaultModelReason). */
+ *  validateProvider flags it; TUI/headless surface the reason from defaultModelReason).
+ *  #841 后：运行时取值 = `resolveProviderPlan`（回退序 + 三态）；本函数保留为**严格单发**解析面
+ *  （零回退——解析未过即 `{}`），新码勿调。 */
 export function resolveRuntimeProvider(providers, defaultModel) {
   const r = parseModelRef(defaultModel, providers)
   if (!r.ok) return {}
@@ -64,3 +74,86 @@ export function defaultModelReason(providers, defaultModel) {
   }
   return parseModelRef(defaultModel, list).reason ?? `defaultModel "${defaultModel}" 无效`
 }
+
+/** 「持 key」判据（#841——`providers[].apiKey` trim 后非空；env 变量不是密钥源，config.mjs 档头同判）。 */
+function hasKey(entry) {
+  return typeof entry?.apiKey === "string" && entry.apiKey.trim() !== ""
+}
+
+/** 渠道模型面单值（#841 模型面 ②③——VSC `resolveDefaultModel` 转口面 · 纯函数）：
+ *  ① `defaultModel` 解析通过 ∧ 其渠道 == `entry` ⇒ 其模型段（首冒号分割 · 双段非空 · name 相等）；
+ *  ② 渠道单值 `entry.model`（非空串）；③ `null`（合法——模型由运行期 `/models` 候选 ∥ 用户选择决定）。
+ *  @param {object|null} entry — providers[] 条目（或同形对象）
+ *  @param {string|null} defaultModel — 顶层复合串
+ *  @returns {string|null} */
+export function resolveChannelModel(entry, defaultModel) {
+  if (entry?.name) {
+    const ref = parseModelRef(defaultModel, [entry])
+    if (ref.ok) return ref.model
+  }
+  return typeof entry?.model === "string" && entry.model ? entry.model : null
+}
+
+/** 运行时渠道/模型统一解析（#841 核单源——机制全文 PROVIDER.md §6.22；纯函数 · 零 I/O）。
+ *  三端（CLI ∥ VSC ∥ 桌面）消费同一函数：`loadConfig` 运行时 provider 取值 = 本函数产物（CLI ∥ 桌面
+ *  经装配自动同源）；VSC 回合面直调（接入面自建链收正）。
+ *
+ *  **渠道面回退序**：① 会话槽渠道（`slot.provider` 在场 ∧ 在册 ∧ 持 key ⇒ `source="slot"`）；
+ *  ② defaultModel 渠道（解析通过 ∧ 该渠道持 key ⇒ `source="defaultModel"`）；③ 首个持 key 渠道
+ *  （按表序 ⇒ `source="registry"`）；④ 无 ⇒ `state="invalid"`（渠表空 ∥ 全表无 key）。
+ *  槽无 key ⇒ **跳过**（不把不可运行渠道钉进运行态）。
+ *  **模型面**：① 入选来源 = 槽 ∧ 槽带模型 ⇒ 槽模型；② defaultModel 属入选渠道 ⇒ 其模型段；
+ *  ③ 入选渠道单值；④ 无 ⇒ `null`（消费者沿既有「model 缺失」处置；明示词形随缺 = 仅渠道名）。
+ *  **三态（config 级——KD-841-3：槽改写「谁在跑」，不改「默认模型是否有效」）**：`ok` =
+ *  defaultModel 独立成立（解析通过 ∧ 该渠道持 key）⇒ 零明示；`fallback` =「无有效 defaultModel」类
+ *   ∧ 全局有可运行渠道 ⇒ 可运行 + 明示必达；`invalid` =「无 provider/key」类 ⇒ 真无效 + 引导配置。
+ *  `reason` = state≠ok 的语义源（消费者按 `state` 出词——**禁串嗅探**，非契约）。
+ *  @param {{providers?: object[], defaultModel?: string|null, slot?: {provider?: string|null, model?: string|null}|null}} [input]
+ *  @returns {{state: "ok"|"fallback"|"invalid", source: "slot"|"defaultModel"|"registry"|null, channel: string|null, model: string|null, provider: object, reason: string|null}} */
+export function resolveProviderPlan({ providers, defaultModel, slot } = {}) {
+  const list = Array.isArray(providers) ? providers : []
+  const slotName = typeof slot?.provider === "string" && slot.provider ? slot.provider : null
+  const slotModel = typeof slot?.model === "string" && slot.model ? slot.model : null
+
+  // ── 渠道面回退序（三步）──
+  let entry = null
+  let source = null
+  if (slotName) {
+    const hit = list.find((p) => p?.name === slotName)
+    if (hit && hasKey(hit)) { entry = hit; source = "slot" } // 槽无 key ⇒ 跳过（落下一档）
+  }
+  const ref = parseModelRef(defaultModel, list)
+  if (!entry && ref.ok && hasKey(ref.provider)) { entry = ref.provider; source = "defaultModel" }
+  if (!entry) {
+    const first = list.find((p) => hasKey(p))
+    if (first) { entry = first; source = "registry" }
+  }
+
+  // ── 模型面（四步；无入选渠道 ⇒ null）──
+  const model = entry ? (source === "slot" && slotModel ? slotModel : resolveChannelModel(entry, defaultModel)) : null
+
+  // ── 三态（config 级）──
+  const dmOk = ref.ok && hasKey(ref.provider)
+  const state = !entry ? "invalid" : dmOk ? "ok" : "fallback"
+
+  // ── reason（语义源 · 逐档）──
+  let reason = null
+  if (state === "invalid") {
+    reason = list.length === 0
+      ? "未配置任何 provider"
+      : "未配置 API 密钥（providers[].apiKey）——请先配置渠道密钥"
+  } else if (state === "fallback") {
+    reason = ref.ok
+      ? `defaultModel 渠道 "${ref.provider.name}" 无 API 密钥——已回退到可用渠道`
+      : defaultModelReason(list, defaultModel)
+  }
+
+  return {
+    state,
+    source,
+    channel: entry?.name ?? null,
+    model,
+    provider: entry ? { ...entry, model } : {},
+    reason,
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thincoder/core",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "ThinCoder shared core — shared mechanism modules + shared prompt content (CLI ↔ VS Code extension).",
   "keywords": [
     "ai",

package/session-lifecycle.mjs

@@ -19,6 +19,8 @@
 
 import { existsSync } from "node:fs"
 import { resolveCompactThreshold } from "./config.mjs"
+// 槽面判据单源（#841 KD-841-2：槽渠道 key 门 + 模型面序——PROVIDER.md §6.22）。
+import { resolveProviderPlan } from "./model-ref.mjs"
 import {
   slotPath, loadManifest, saveManifest, slotDigest, writeSessionFile, getSessionId,
   writeEndMarker, sessionEnd, ownerPid, ownerPids,
@@ -158,18 +160,25 @@ export function applySession(agent, data, opts = {}) {
   } else {
     unbindRecordStore(agent)
   }
-  // ── MODEL-MERGE-SESSION 恢复（F-4——两支）──
-  const slotProvider = data.activeProvider ? agent.providers?.find((pr) => pr.name === data.activeProvider) : null
-  if (slotProvider) {
-    // ① 槽 provider 存在 → 按槽值设（不看 config）：双字段恒非空——legacy 槽 activeModel
-    //    null/空串 = 无 override——回该渠道默认模型（`providers[].model` 单值——M3）。
-    //    F-2d（MODEL-400-FIX）：`||` 非 `??`——空串也兜（activeModel="" 的槽会让 `??` 不落链 →
-    //    空槽 model 恒有值，provider.model 键不缺失）
+  // ── MODEL-MERGE-SESSION 恢复（F-4——两支；#841：槽面判据单源 = 统一解析第 1 步）──
+  // 槽渠道（`activeProvider` 在册 ∧ 持 key）⇒ 槽值设；槽无 key ∥ 不在册 ⇒ 跳过（落 config 链——
+  // 不把不可运行渠道钉进运行态；**跳过不写槽**——原槽值保留（D-S3 / KD-841-2））。判定 + 模型面
+  // 同源 = `resolveProviderPlan`（PROVIDER.md §6.22——零第二判据）。
+  const slotPlan = resolveProviderPlan({
+    providers: agent.providers,
+    defaultModel: agent.config?.defaultModel,
+    slot: { provider: data.activeProvider ?? null, model: data.activeModel ?? null },
+  })
+  if (slotPlan.source === "slot") {
+    const slotProvider = agent.providers?.find((pr) => pr.name === slotPlan.channel)
+    // ① 槽 provider 存在 → 按槽值设（不看 config）：双字段恒非空。
+    //    模型面序（#841）：槽模型 → `defaultModel` 属本渠道 ⇒ 其模型段 → 渠道默认单值
+    //    （`providers[].model`）；三档皆无 ⇒ `null`（不落 model 键——下游沿既有「model 缺失」处置）。
+    //    F-2d（MODEL-400-FIX）径保留：空串 / 非串槽模型同样兜（#638 非串 = 未登记）——slotPlan.model
+    //    已按同归一出值（单源，无第二判据）。
     const prevName = agent.activeProvider
     const prevModel = agent.activeModel ?? null
-    // #638（adoption 边界归一）：非串 `data.activeModel`（外端脏载 / 手工档）= 未登记 ⇒ 回退渠道
-    // 模型——类型脏值不入两状态字段（镜下方阈值重算门 ∕ 档位块 ∕ VSC `panel-turn-stages.mjs:53` 同形门）。
-    const slotModel = (typeof data.activeModel === "string" && data.activeModel) ? data.activeModel : slotProvider.model
+    const slotModel = slotPlan.model
     const switched = prevName !== slotProvider.name || prevModel !== slotModel
     agent.activeProvider = slotProvider.name
     agent.activeModel = slotModel
@@ -200,8 +209,8 @@ export function applySession(agent, data, opts = {}) {
     }
     return switched
   }
-  // ② 槽 provider 没了 → D-S3 保留——静默保持现状（不报错不纠正——config 有效则静默用
-  //    config/defaultModel 运行时；两方都无效由调用侧复验 validateProvider 弹重选）
+  // ② 槽无 key ∥ 不在册 → D-S3 保留——静默保持现状（落 config 链：config 统一解析产物已是
+  //    `agent.provider`；不报错不纠正——两方都无效由调用侧复验 validateProvider 弹重选）
   return false
 }