thincoder 0.12.60 → 0.12.61

package/src/memory/code-sync.mjs

@@ -4,13 +4,30 @@
 import { readFile, stat } from "node:fs/promises"
 import { join, relative } from "node:path"
 import { embed, cosine, toBlob, fromBlob } from "../embedding.mjs"
-import { CODE_EXTS, DOC_EXTS, SKIP_DIRS, MAX_CODE_FILE_BYTES, MAX_DOC_FILE_BYTES } from "./schema.mjs"
+import { CODE_EXTS, DOC_EXTS, MAX_CODE_FILE_BYTES, MAX_DOC_FILE_BYTES } from "./schema.mjs"
 import { buildFtsQuery, ensureEmbeddings, EMBED_TEXT_MAX_LEN } from "./core.mjs"
 import { detectLanguage, _upsertCodeFile, _upsertDocFile, yieldTick } from "./code-index.mjs"
+import { walkProjectFiles, isSkippedRelPath, extensionOf, createUnlistedTally, MAX_WALK_FILES } from "./file-walk.mjs"
+import { loadConventions } from "../conventions.mjs"
+import { logEvent } from "../log.mjs"
 
 const DIFF_FULL_SYNC_THRESHOLD = 200
 const CODE_EMBED_BATCH = 64
 
+/**
+ * Index extension sets = built-in tables ∪ project declaration
+ * (`.thincoder/conventions.json` → index.codeExtensions / index.docExtensions;
+ * PORTABILITY PO-9/§3.7 — a project may declare extensions this product does not
+ * ship a default for). Declaration only ADDS (union), never removes.
+ */
+export function indexExtensions(dir) {
+  const conv = loadConventions(dir)
+  return {
+    code: new Set([...CODE_EXTS, ...conv.index.codeExtensions]),
+    doc: new Set([...DOC_EXTS, ...conv.index.docExtensions]),
+  }
+}
+
 /**
  * git-driven incremental indexing: use git diff to find files changed since
  * the last index, and only rebuild FTS5 chunks for those files (vectors are untouched).
@@ -19,6 +36,7 @@ const CODE_EMBED_BATCH = 64
  */
 export async function gitSync(memory, dir, { onProgress } = {}) {
   const { execFile: _execFile } = await import("node:child_process")
+  const { code: codeExts, doc: docExts } = indexExtensions(dir)
   const gitRun = (args) => new Promise((resolve, reject) => {
     _execFile("git", args, { cwd: dir, encoding: "utf8", timeout: 10000, windowsHide: true }, (err, stdout) => {
       if (err) reject(err); else resolve(stdout)
@@ -55,17 +73,16 @@ export async function gitSync(memory, dir, { onProgress } = {}) {
   for (let i = 0; i < diffOut.length; i++) {
     const rel = diffOut[i].replaceAll("\\", "/")
     const abs = join(dir, rel)
-    const ext = rel.slice(rel.lastIndexOf(".")).toLowerCase()
+    const ext = extensionOf(rel)
 
-    const pathDirs = rel.split("/")
-    if (pathDirs.some((d) => SKIP_DIRS.has(d) || d.startsWith("."))) continue
+    if (isSkippedRelPath(rel)) continue
 
-    if (!CODE_EXTS.has(ext) && !DOC_EXTS.has(ext)) { skipped++; continue }
+    if (!codeExts.has(ext) && !docExts.has(ext)) { skipped++; continue }
 
     try {
       const text = await readFile(abs, "utf8")
       const lines = text.split("\n")
-      if (CODE_EXTS.has(ext)) {
+      if (codeExts.has(ext)) {
         const lang = detectLanguage(abs)
         let mtimeMs = 0
         try { mtimeMs = Math.floor((await stat(abs)).mtimeMs) } catch { /* new file */ }
@@ -79,7 +96,7 @@ export async function gitSync(memory, dir, { onProgress } = {}) {
     } catch (e) {
       const isDeleted = e.code === "ENOENT"
       if (isDeleted) {
-        if (CODE_EXTS.has(ext)) memory.db.prepare(`DELETE FROM code_chunks WHERE origin = ? AND path = ?`).run(dir, rel)
+        if (codeExts.has(ext)) memory.db.prepare(`DELETE FROM code_chunks WHERE origin = ? AND path = ?`).run(dir, rel)
         else memory.db.prepare(`DELETE FROM doc_chunks WHERE origin = ? AND path = ?`).run(dir, rel)
         removed++
       } else {
@@ -104,16 +121,27 @@ export async function gitSync(memory, dir, { onProgress } = {}) {
 
 /**
  * List project files matching the given extensions.
- * Only indexes git repos — if dir isn't inside a git worktree, returns [].
- * Uses `git ls-files --cached --others --exclude-standard` to get the file list
- * (tracked + untracked-not-ignored, respecting .gitignore).
- * Returns an array of { abs, rel } pairs (abs = full path, rel = path relative to dir).
+ * Preferred source = git (`git ls-files --cached --others --exclude-standard`:
+ * tracked + untracked-not-ignored, .gitignore respected). Projects WITHOUT git
+ * fall back to a filesystem walk (PORTABILITY FR15/P8) — before, the index was
+ * silently empty there. The walk cannot honour .gitignore (no git → no such
+ * concept) and skips the shared SKIP_DIRS/dot-directory set instead.
+ * Returns { entries, unlisted }: `entries` = { abs, rel } pairs (rel relative to
+ * dir); `unlisted` = files whose extension is in NO index list (count + sample),
+ * the visible signal behind "my .xyz files are not searchable" (PORTABILITY PO-9).
+ * `truncated` = the non-git walk hit its file cap (capped trees are logged, never
+ * silently indexed-partial). opts.maxFiles = the walk cap (test seam).
  */
-export async function listProjectFiles(dir, exts) {
+export async function listProjectFiles(dir, exts, { maxFiles } = {}) {
   const { execFile: _execFile } = await import("node:child_process")
   const { join: joinPath } = await import("node:path")
+  const { code, doc } = indexExtensions(dir)
+  const tally = createUnlistedTally(new Set([...code, ...doc]))
 
-  // Only index git repos — if this isn't one, return empty
+  const files = []
+  const finish = (truncated = false) => ({ entries: files, unlisted: tally.result(), truncated })
+
+  // Git listing when available; a non-git project falls through to the walk.
   let gitTop
   try {
     gitTop = (await new Promise((resolve, reject) => {
@@ -121,10 +149,17 @@ export async function listProjectFiles(dir, exts) {
         (err, stdout) => { if (err) reject(err); else resolve(stdout.trim()) })
     })).replace(/\\/g, "/")
   } catch {
-    return [] // not a git repo → nothing to index
+    // Not a git repo → filesystem walk (FR15: the index must still be usable).
+    const walked = await walkProjectFiles(dir, exts, { knownExts: new Set([...code, ...doc]), ...(maxFiles !== undefined ? { maxFiles } : {}) })
+    files.push(...walked.files)
+    // The walk's cap must stay visible end-to-end (file-walk.mjs: "never silently
+    // dropped") — a capped listing says so in the log, not only in a discarded flag.
+    if (walked.truncated) {
+      logEvent("index:truncated", { dir, files: walked.files.length, maxFiles: maxFiles ?? MAX_WALK_FILES })
+    }
+    return { entries: files, unlisted: walked.unlisted, truncated: walked.truncated }
   }
 
-  const files = []
   try {
     const raw = await new Promise((resolve, reject) => {
       _execFile("git", ["ls-files", "--cached", "--others", "--exclude-standard"],
@@ -134,16 +169,15 @@ export async function listProjectFiles(dir, exts) {
     for (const line of raw.trim().split("\n")) {
       const p = line.trim()
       if (!p) continue
-      const ext = p.slice(p.lastIndexOf(".")).toLowerCase()
-      if (!exts.has(ext)) continue
-      const abs = joinPath(dir, p)
       const rel = p.replace(/\\/g, "/")
-      if (rel.split("/").some((seg) => SKIP_DIRS.has(seg) || seg.startsWith("."))) continue
-      files.push({ abs, rel })
+      if (isSkippedRelPath(rel)) continue
+      const ext = extensionOf(rel)
+      if (!ext || !exts.has(ext)) { tally.note(rel); continue }
+      files.push({ abs: joinPath(dir, rel), rel })
     }
   } catch { /* ls-files failed */ }
 
-  return files
+  return finish()
 }
 
 
@@ -152,7 +186,8 @@ export async function listProjectFiles(dir, exts) {
  * Incremental by mtime — only rebuilds chunks for files that have changed.
  */
 export async function codeSync(memory, dir, { onProgress } = {}) {
-  const entries = await listProjectFiles(dir, CODE_EXTS)
+  const { code: exts } = indexExtensions(dir)
+  const { entries, unlisted } = await listProjectFiles(dir, exts)
   const files = [] // { abs, rel, mtimeMs }
   let overSizeSkipped = 0
   for (const { abs, rel } of entries) {
@@ -206,7 +241,10 @@ export async function codeSync(memory, dir, { onProgress } = {}) {
 
   onProgress?.({ phase: "done", total: files.length, updated, removed, skipped, failed, overSizeSkipped })
   markIndexedCommit(memory, dir)
-  return { updated, removed, skipped, failed, errors, total: files.length, overSizeSkipped }
+  if (unlisted.count > 0) {
+    logEvent("index:unlisted", { dir, kind: "code", count: unlisted.count, exts: unlisted.exts.map((e) => e.ext) })
+  }
+  return { updated, removed, skipped, failed, errors, total: files.length, overSizeSkipped, unlistedExts: unlisted }
 }
 
 /** Record current HEAD as the index anchor (gitSync incremental diff baseline); silently skip non-git repos */
@@ -338,32 +376,33 @@ export function codeSearchTool(memory) {
  * Single-file incremental reindex: called after write/edit/delete, only rebuilds this one path.
  */
 export async function reindexFile(memory, cwd, absPath) {
-  const ext = absPath.slice(absPath.lastIndexOf(".")).toLowerCase()
+  const ext = extensionOf(absPath)
   const rel = relative(cwd, absPath).replaceAll("\\", "/")
   if (rel === ".." || rel.startsWith("../")) return
-  const dirs = rel.split("/").slice(0, -1)
-  if (dirs.some((d) => SKIP_DIRS.has(d) || d.startsWith("."))) return
+  if (isSkippedRelPath(rel)) return
+  // Declared extensions count for the single-file path too (union with built-ins).
+  const { code: codeExts, doc: docExts } = indexExtensions(cwd)
 
   // skip oversized files (minified bundles, test fixtures, generated code)
-  const maxBytes = CODE_EXTS.has(ext) ? MAX_CODE_FILE_BYTES : DOC_EXTS.has(ext) ? MAX_DOC_FILE_BYTES : 0
+  const maxBytes = codeExts.has(ext) ? MAX_CODE_FILE_BYTES : docExts.has(ext) ? MAX_DOC_FILE_BYTES : 0
   if (maxBytes > 0) {
     try { const st = await stat(absPath); if (st.size > maxBytes) return } catch { /* can't stat, proceed */ }
   }
 
   let text
   try { text = await readFile(absPath, "utf8") } catch {
-    if (CODE_EXTS.has(ext)) memory.db.prepare(`DELETE FROM code_chunks WHERE origin = ? AND path = ?`).run(cwd, rel)
-    else if (DOC_EXTS.has(ext)) memory.db.prepare(`DELETE FROM doc_chunks WHERE origin = ? AND path = ?`).run(cwd, rel)
+    if (codeExts.has(ext)) memory.db.prepare(`DELETE FROM code_chunks WHERE origin = ? AND path = ?`).run(cwd, rel)
+    else if (docExts.has(ext)) memory.db.prepare(`DELETE FROM doc_chunks WHERE origin = ? AND path = ?`).run(cwd, rel)
     return
   }
   const lines = text.split("\n")
 
-  if (CODE_EXTS.has(ext)) {
+  if (codeExts.has(ext)) {
     const lang = detectLanguage(absPath)
     let mtimeMs = 0
     try { mtimeMs = Math.floor((await stat(absPath)).mtimeMs) } catch { /* new file */ }
     _upsertCodeFile(memory, cwd, rel, lines, lang, mtimeMs)
-  } else if (DOC_EXTS.has(ext)) {
+  } else if (docExts.has(ext)) {
     let mtimeMs = 0
     try { mtimeMs = Math.floor((await stat(absPath)).mtimeMs) } catch { /* new file */ }
     _upsertDocFile(memory, cwd, rel, lines, mtimeMs)

package/src/memory/delete.mjs

@@ -155,6 +155,8 @@ export async function deleteByUid(memory, uid, { dirs = {} } = {}) {
   const norm = /^\d+$/.test(uid) ? `personal:${uid}` : String(uid)
   const [layer, ...rest] = norm.split(":")
   if (layer === "personal") {
+    // 畸形尾缀拒绝（2026-09-08 代码正确性批 2.2）：personal:5:extra 不得静默删 id=5
+    if (norm.split(":").length > 2) throw new Error(`invalid memory id: ${norm}`)
     const id = rest[0] ?? ""
     if (!/^\d+$/.test(id)) throw new Error(`invalid memory id: ${norm}`)
     const entry = fetchEntry(memory, norm)

package/src/memory/docs.mjs

@@ -3,14 +3,15 @@
  */
 
 import { readFile, stat } from "node:fs/promises"
-import { join } from "node:path"
+import { isAbsolute, join } from "node:path"
 import { embed, cosine, toBlob, fromBlob } from "../embedding.mjs"
 import { commitAndPush } from "../git/gitmem.mjs"
-import { DOC_EXTS, SKIP_DIRS, MAX_DOC_FILE_BYTES } from "./schema.mjs"
+import { MAX_DOC_FILE_BYTES } from "./schema.mjs"
 import { buildFtsQuery, put, search, putMarkdown, clearPersonal, EMBED_TEXT_MAX_LEN } from "./core.mjs"
 import { deleteByUid, matchMemoryRows, deleteWhere } from "./delete.mjs"
 import { _upsertDocFile, yieldTick } from "./code-index.mjs"
-import { markIndexedCommit, listProjectFiles } from "./code-sync.mjs"
+import { markIndexedCommit, listProjectFiles, indexExtensions } from "./code-sync.mjs"
+import { logEvent } from "../log.mjs"
 
 const DOC_EMBED_BATCH = 64
 
@@ -19,7 +20,7 @@ const DOC_EMBED_BATCH = 64
  * Incremental by mtime.
  */
 export async function docSync(memory, dir, { onProgress } = {}) {
-  const entries = await listProjectFiles(dir, DOC_EXTS)
+  const { entries, unlisted } = await listProjectFiles(dir, indexExtensions(dir).doc)
   const files = [] // { abs, rel, mtimeMs }
   let overSizeSkipped = 0
   for (const { abs, rel } of entries) {
@@ -72,7 +73,10 @@ export async function docSync(memory, dir, { onProgress } = {}) {
 
   onProgress?.({ phase: "done", total: files.length, updated, removed, skipped, failed, overSizeSkipped })
   markIndexedCommit(memory, dir)
-  return { updated, removed, skipped, failed, errors, total: files.length, overSizeSkipped }
+  if (unlisted.count > 0) {
+    logEvent("index:unlisted", { dir, kind: "doc", count: unlisted.count, exts: unlisted.exts.map((e) => e.ext) })
+  }
+  return { updated, removed, skipped, failed, errors, total: files.length, overSizeSkipped, unlistedExts: unlisted }
 }
 
 /**
@@ -233,7 +237,7 @@ const listRowLine = (r) => `[${r.layer}] ${r.id} [${r.type}] ${r.title}（${fmtD
  * opts: { cwd, projectDir, author, team: { dir, name } | null }
  */
 export function memoryTools(memory, opts = {}) {
-  const projectDir = opts.projectDir ? join(opts.cwd ?? process.cwd(), opts.projectDir) : null
+  const projectDir = opts.projectDir ? (isAbsolute(opts.projectDir) ? opts.projectDir : join(opts.cwd ?? process.cwd(), opts.projectDir)) : null
   const dirs = { project: projectDir, team: opts.team?.dir ?? null }
   return [
     {

package/src/memory/file-walk.mjs

@@ -0,0 +1,109 @@
+/**
+ * memory/file-walk.mjs — filesystem walk fallback + the shared file-listing predicates.
+ *
+ * Why this module (PORTABILITY FR15 / P8): the index was built from `git ls-files`
+ * only — on a project that is not a git repository the code and doc indexes came
+ * back EMPTY, silently (the reviewer/agent then "searched" an empty index). The
+ * fallback traverses the filesystem instead, and the skip predicate lives here so
+ * the git path, the walk and the single-file reindex cannot drift apart against
+ * each other (they were three copies before).
+ */
+import { readdir } from "node:fs/promises"
+import { join } from "node:path"
+import { SKIP_DIRS } from "./schema.mjs"
+
+/** Upper guard for the walk: stop after this many matched files (runaway trees). */
+export const MAX_WALK_FILES = 20000
+
+/**
+ * Shared skip predicate for project-relative paths: any SKIP_DIRS basename, or any
+ * dot-prefixed segment (`.git`, `.cache`, `.thincoder`…). Accepts both separators.
+ */
+export function isSkippedRelPath(rel) {
+  return String(rel ?? "")
+    .replace(/\\/g, "/")
+    .split("/")
+    .some((seg) => seg !== "" && (seg.startsWith(".") || SKIP_DIRS.has(seg)))
+}
+
+/** Lower-cased ".ext" of a path, or "" when it has no extension. */
+export function extensionOf(p) {
+  const s = String(p ?? "")
+  const base = s.slice(Math.max(s.lastIndexOf("/"), s.lastIndexOf("\\")) + 1)
+  const i = base.lastIndexOf(".")
+  return i > 0 ? base.slice(i).toLowerCase() : ""
+}
+
+/**
+ * Unlisted-extension tally (PORTABILITY PO-9 — visibility): counts files the index
+ * will NOT pick up because their extension is in no list, so "my .xyz files are not
+ * searchable" stops being invisible. `exts` is a capped sample (the count is the
+ * signal; the list is the hint).
+ * @param {Set<string>} knownExts — every extension that IS indexed (code ∪ doc ∪ declared)
+ */
+export function createUnlistedTally(knownExts) {
+  const counts = new Map()
+  let count = 0
+  return {
+    note(rel) {
+      const ext = extensionOf(rel)
+      if (!ext || knownExts.has(ext)) return
+      count++
+      counts.set(ext, (counts.get(ext) ?? 0) + 1)
+    },
+    result(limit = 12) {
+      const exts = [...counts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, limit)
+        .map(([ext, n]) => ({ ext, count: n }))
+      return { count, exts }
+    },
+  }
+}
+
+/**
+ * Recursive project walk — the no-git listing source. Symlinks are never followed
+ * (loop/escape guard); skipped directories are pruned; only files whose extension
+ * is in `exts` are returned. Hitting maxFiles is reported as `truncated`, never
+ * silently dropped.
+ * @param {string} dir — project root
+ * @param {Set<string>} exts — extensions to keep (lower-case, leading dot)
+ * @param {{maxFiles?: number, knownExts?: Set<string>|null}} [opts]
+ *   knownExts → also tally files whose extension is in NO index list
+ * @returns {Promise<{files: {abs: string, rel: string}[], truncated: boolean,
+ *   unlisted: {count: number, exts: {ext: string, count: number}[]}}>}
+ */
+export async function walkProjectFiles(dir, exts, { maxFiles = MAX_WALK_FILES, knownExts = null } = {}) {
+  const files = []
+  const tally = knownExts ? createUnlistedTally(knownExts) : null
+  let truncated = false
+  const stack = [{ abs: dir, rel: "" }]
+  while (stack.length > 0) {
+    const cur = stack.pop()
+    let entries
+    try {
+      entries = await readdir(cur.abs, { withFileTypes: true })
+    } catch { continue /* unreadable dir — skip, the walk must not fail the sync */ }
+    for (const ent of entries) {
+      const rel = cur.rel ? `${cur.rel}/${ent.name}` : ent.name
+      if (ent.isSymbolicLink()) continue // never follow symlinks
+      if (ent.isDirectory()) {
+        if (!isSkippedRelPath(rel)) stack.push({ abs: join(cur.abs, ent.name), rel })
+        continue
+      }
+      if (!ent.isFile() || isSkippedRelPath(rel)) continue
+      const ext = extensionOf(ent.name)
+      if (!ext || !exts.has(ext)) {
+        tally?.note(rel)
+        continue
+      }
+      if (files.length >= maxFiles) {
+        truncated = true
+        break
+      }
+      files.push({ abs: join(cur.abs, ent.name), rel })
+    }
+    if (truncated) break
+  }
+  return { files, truncated, unlisted: tally ? tally.result() : { count: 0, exts: [] } }
+}

package/src/memory/schema.mjs

@@ -14,10 +14,22 @@ export const VALID_TYPES = new Set(["rule", "knowledge", "decision", "pattern"])
 export const SCHEMA_VERSION = 9
 export const SQLITE_BUSY_TIMEOUT = 3000
 
-// Code index: source file extensions
-export const CODE_EXTS = new Set([".mjs", ".js", ".ts", ".tsx", ".jsx", ".py", ".rs", ".go", ".java", ".c", ".h", ".cpp", ".hpp", ".rb", ".swift", ".kt", ".sh", ".bash", ".sql", ".yaml", ".yml", ".toml", ".json", ".css", ".html", ".vue", ".svelte"])
+// Code index: source file extensions. Curated DEFAULTS — a project can declare
+// more (union) through .thincoder/conventions.json → index.codeExtensions
+// (PORTABILITY PO-9: an unlisted extension used to be invisible AND undeclarable).
+export const CODE_EXTS = new Set([
+  ".mjs", ".js", ".cjs", ".mts", ".cts", ".ts", ".tsx", ".jsx",
+  ".py", ".rs", ".go", ".java", ".c", ".h", ".cpp", ".hpp",
+  ".rb", ".swift", ".kt", ".dart", ".lua", ".cs", ".fs", ".fsx",
+  ".clj", ".cljs", ".ex", ".exs", ".erl", ".hrl", ".scala", ".groovy",
+  ".pl", ".pm", ".r", ".jl", ".zig", ".ps1",
+  ".sh", ".bash", ".sql", ".yaml", ".yml", ".toml", ".json",
+  ".proto", ".graphql", ".tf", ".hcl",
+  ".css", ".html", ".vue", ".svelte",
+])
 // Doc index: markdown / plain text (separate index makes it easier for LLM to distinguish "design specs" from "existing code")
-export const DOC_EXTS = new Set([".md", ".mdc", ".txt", ".rst", ".adoc"])
+// Same declaration rule as CODE_EXTS (index.docExtensions).
+export const DOC_EXTS = new Set([".md", ".mdc", ".mdx", ".txt", ".rst", ".adoc", ".org", ".wiki", ".tex"])
 // Directory names always skipped during code/doc indexing
 // NOTE: these are case-sensitive basename matches; add common platform-specific dirs
 export const SKIP_DIRS = new Set([

package/src/model-ref.mjs

@@ -0,0 +1,66 @@
+/**
+ * model-ref.mjs — composite model reference parser (MODEL-MERGE-SESSION; v2 2026-09-10).
+ * A model is an explicit "provider:model" composite — config.defaultModel (top level,
+ * new-session starting point) and session slots both speak this language. 有效域 = **provider 存在
+ * + 双段非空**：清单不再人工维护（模型清单由 provider 运行期 `GET /models` 拉取决定——
+ * PROVIDER.md §16），候选成员校验**已废除**——显式 `p:m` 一律放行（含多冒号首分割）。
+ * providers[].model 是渠道默认模型（单值）——候选清单字段 models[] 已整字段退场。
+ *
+ * Strict first-colon split — deliberately does NOT reuse resolveChildProvider's loose
+ * three-state resolution: ① legacy single-provider configs and ② model-name-only refs
+ * are gone with activeProvider/activeModel (F-1), so a bare provider or bare model is
+ * invalid everywhere (裁定③——裸 provider 拒——显式 p:m)。
+ *
+ * Runtime model resolution:
+ *   parseModelRef(ref, providers)      → { ok, provider, model } | { ok:false, reason }
+ *   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.
+ */
+export function parseModelRef(ref, providers) {
+  if (typeof ref !== "string" || !ref.trim()) {
+    return { ok: false, reason: 'model reference expected as "provider:model" (e.g. deepseek:deepseek-v4-pro)' }
+  }
+  // 首冒号分割——`a:b:c` → provider=a、model=`b:c`（`ollama:llama3:70b` 式模型名可用，M4）
+  const sep = ref.indexOf(":")
+  if (sep <= 0) {
+    return { ok: false, reason: `invalid model reference "${ref}" — expected provider:model (bare provider/model names are not accepted)` }
+  }
+  const providerName = ref.slice(0, sep)
+  const model = ref.slice(sep + 1)
+  if (!model) {
+    return { ok: false, reason: `invalid model reference "${ref}" — model part is empty (expected provider:model)` }
+  }
+  const list = Array.isArray(providers) ? providers : []
+  const provider = list.find((p) => p?.name === providerName)
+  if (!provider) {
+    const available = list.map((p) => p.name).join(", ") || "(none)"
+    return { ok: false, reason: `unknown provider "${providerName}" in model reference (available: ${available})` }
+  }
+  return { ok: true, provider, model }
+}
+
+/** 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). */
+export function resolveRuntimeProvider(providers, defaultModel) {
+  const r = parseModelRef(defaultModel, providers)
+  if (!r.ok) return {}
+  return { ...r.provider, model: r.model }
+}
+
+/** Human-readable reason behind an invalid/empty runtime resolution (D-S1 原因). */
+export function defaultModelReason(providers, defaultModel) {
+  const list = Array.isArray(providers) ? providers : []
+  if (!defaultModel) {
+    return list.length > 0
+      ? "defaultModel 未设置（config 顶层 defaultModel — 新会话起点；/config → 默认模型 设置）"
+      : "未配置任何 provider"
+  }
+  return parseModelRef(defaultModel, list).reason ?? `defaultModel "${defaultModel}" 无效`
+}

package/src/model-specs.mjs

@@ -25,10 +25,18 @@
  * tempRange:         valid temperature range [min, max] (if undeclared, no clamping)
  */
 const MODEL_SPECS = [
-  // DeepSeek V4 series
+  // DeepSeek V4.1 series (2026-09-11). `deepseek-flash` = DeepSeek-V4.1-Flash (in service):
+  // 1M ctx / 384K out, thinking on by default (effort low/high/max), Chat Prefix Completion
+  // beta, automatic disk cache, vision. The two legacy names below are RETIRED — the server
+  // still accepts them and serves them from V4.1-Flash today (no switch window), so their
+  // rows carry the V4.1-Flash parameters (v4-flash gains multimodal).
+  ["deepseek-flash",    { context: 1_000_000, maxOutput: 384_000, thinking: true,  prefixMode: true,  cacheMode: "auto", thinkApi: "type", reasoningEcho: "required", reasoningEffortEnum: ["low", "high", "max"], tempRange: [0, 2], multimodal: true }],
+  // deepseek-v4-pro (V4-Pro-0813): fields unchanged — vision capability NOT verified, so no
+  // multimodal (conservative). From 2026-09-14 12:00 Beijing all requests route to V4.1-Flash.
   ["deepseek-v4-pro",   { context: 1_000_000, maxOutput: 384_000, thinking: true,  prefixMode: true,  cacheMode: "auto", thinkApi: "type", reasoningEcho: "required", reasoningEffortEnum: ["low", "high", "max"], tempRange: [0, 2] }],
-  ["deepseek-v4-flash", { context: 1_000_000, maxOutput: 384_000, thinking: true,  prefixMode: true,  cacheMode: "auto", thinkApi: "type", reasoningEcho: "required", reasoningEffortEnum: ["low", "high", "max"], tempRange: [0, 2] }],
-  // DeepSeek V4 Flash Vision (experimental) — image input on top of the full V4-Flash stack
+  // deepseek-v4-flash: RETIRED name — still accepted, served by V4.1-Flash today → aligned row
+  ["deepseek-v4-flash", { context: 1_000_000, maxOutput: 384_000, thinking: true,  prefixMode: true,  cacheMode: "auto", thinkApi: "type", reasoningEcho: "required", reasoningEffortEnum: ["low", "high", "max"], tempRange: [0, 2], multimodal: true }],
+  // deepseek-v4-flash-vision-exp: retired experimental vision name — still accepted (V4.1-Flash)
   ["deepseek-v4-flash-vision-exp", { context: 1_000_000, maxOutput: 384_000, thinking: true,  prefixMode: true,  cacheMode: "auto", thinkApi: "type", reasoningEcho: "required", reasoningEffortEnum: ["low", "high", "max"], tempRange: [0, 2], multimodal: true }],
   // Kimi series
   ["kimi-k3",           { context: 1_000_000, maxOutput: 131_072, thinking: true,  partialMode: true, multimodal: true, cacheMode: "auto",  thinkApi: "effort", reasoningEcho: "required", reasoningEffortEnum: ["low", "high", "max"] }],
@@ -95,11 +103,15 @@ const DEFAULT_SPEC = { context: 128_000, maxOutput: 32_000, cacheMode: "none" }
  * 且含 "/" 时，剥掉第一个 "/" 前的 namespace 再按前缀匹配一次——ZHIPU/GLM-5.3 → glm-5.3 命中
  * 真实规格，不再降级 128K 默认。kimi/kimi-k3 的显式 alias 行保留为文档锚（发送路径
  * provider.core isRouter 依赖含 "/" 判定），通用机制已覆盖同类。 */
-const warnedModels = new Set() // warn once per model name — specForModel is a hot path (every request)
-// Pre-sorted once at module scope — specForModel runs on every request (agent, provider core,
+const warnedModels = new Set() // warn once per model name — spec lookup runs on every request (hot path)
+// Pre-sorted once at module scope — spec lookup runs on every request (agent, provider core,
 // context, auto-think, TUI rendering); re-sorting per call was wasteful.
 const SORTED_SPECS = [...MODEL_SPECS].sort((a, b) => b[0].length - a[0].length)
-export function specForModel(model) {
+
+/** Single table lookup shared by specForModel / specMatch — prefix match (case-insensitive)
+ *  with vendor-namespace stripping. Returns null on a miss (DEFAULT_SPEC is the caller-side
+ *  fallback and is deliberately NOT returned here — `matched` needs the miss itself). */
+function lookupSpec(model) {
   const m = (model ?? "").toLowerCase()
   for (const [prefix, spec] of SORTED_SPECS) {
     if (m.startsWith(prefix.toLowerCase())) return spec
@@ -112,15 +124,37 @@ export function specForModel(model) {
       if (bare.startsWith(prefix.toLowerCase())) return spec
     }
   }
-  // Unknown model: warn ONCE (not per request) so a typo'd ID or a missing alias surfaces
-  // instead of silently degrading to the 128K default (IK5VGJ).
+  return null
+}
+
+/** Unknown model: warn ONCE (not per request) so a typo'd ID or a missing alias surfaces
+ *  instead of silently degrading to the 128K default (IK5VGJ). The dedupe set is shared by
+ *  specForModel / specMatch (PROVIDER.md §16 M5). */
+function warnUnknownModel(model) {
+  const m = (model ?? "").toLowerCase()
   if (m && !warnedModels.has(m)) {
     warnedModels.add(m)
     console.warn(`[config] model "${model}" not found in MODEL_SPECS — using default spec (128K context, 32K output). Check the model ID or add an alias.`)
   }
+}
+
+export function specForModel(model) {
+  const hit = lookupSpec(model)
+  if (hit) return hit
+  warnUnknownModel(model)
   return DEFAULT_SPEC
 }
 
+/** specMatch(model) → { spec, matched }（PROVIDER.md §16 M5——切换回显的来源判定）。
+ *  `matched:false` = DEFAULT_SPEC 兜底（未知模型）；与 specForModel 共享同一查表实现（单次），
+ *  specForModel 的返回形状与共享对象契约零改（热路径零变）。 */
+export function specMatch(model) {
+  const hit = lookupSpec(model)
+  if (hit) return { spec: hit, matched: true }
+  warnUnknownModel(model)
+  return { spec: DEFAULT_SPEC, matched: false }
+}
+
 /**
  * providerSpec(provider) — spec with a provider-level context override (PROVIDER.md §15, 2026-09-02).
  *