thincoder 0.12.60 → 0.12.62

package/src/memory/core.mjs

@@ -7,6 +7,7 @@
 
 import { parseEntry, serializeEntry, entryFilename } from "../markdown.mjs"
 import { embed, cosine, toBlob, fromBlob } from "../embedding.mjs"
+import { scanVectors, createTopK } from "./scan.mjs"
 import { readFile, stat, readdir, writeFile, mkdir } from "node:fs/promises"
 import { join } from "node:path"
 import { segmentCJK, VALID_TYPES, SCHEMA_VERSION } from "./schema.mjs"
@@ -57,15 +58,13 @@ export async function search(memory, query, { limit = 5 } = {}) {
   }
   const vecFilter = memory.projectOrigin ? `AND (layer = 'team' OR origin = ?)` : ""
   const vecParams = memory.projectOrigin ? [memory.projectOrigin] : []
-  const rows = memory.db.prepare(`
-    SELECT 'personal:' || id AS uid, embedding FROM entries WHERE embedding IS NOT NULL
-    UNION ALL
-    SELECT layer || ':' || COALESCE(origin, '') || ':' || path AS uid, embedding FROM files WHERE embedding IS NOT NULL ${vecFilter}
-  `).all(...vecParams)
-  const vecList = rows
-    .map((r) => ({ id: r.uid, score: cosine(qvec, fromBlob(r.embedding)) }))
-    .sort((a, b) => b.score - a.score)
-    .slice(0, Math.max(limit * 4, 20))
+  // TUI-OOM-ROOTCAUSE（MEMORY.md §10.3）：分块扫描 + 有界 top-K（原全表 .all() 物化 +
+  // 全量排序——峰值 = 块 + K；召回语义不变）。两表各自游标扫描、共享同一 top-K。
+  const top = createTopK(Math.max(limit * 4, 20))
+  const onRow = (r) => top.push({ id: r.uid, score: cosine(qvec, fromBlob(r.embedding)) })
+  scanVectors(memory.db, `SELECT rowid, 'personal:' || id AS uid, embedding FROM entries WHERE embedding IS NOT NULL`, [], { onRow })
+  scanVectors(memory.db, `SELECT rowid, layer || ':' || COALESCE(origin, '') || ':' || path AS uid, embedding FROM files WHERE embedding IS NOT NULL ${vecFilter}`, vecParams, { onRow })
+  const vecList = top.list()
 
   // ---- RRF merge ----
   const K = 60

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,16 @@
  */
 
 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 { scanVectors, createTopK } from "./scan.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 +21,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 +74,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 }
 }
 
 /**
@@ -105,11 +110,12 @@ export async function docSearch(memory, query, { limit = 5 } = {}) {
     console.error(`[docs] query embedding failed, falling back to FTS-only: ${e.message}`)
     return ftsList.slice(0, limit)
   }
-  const rows = memory.db.prepare(`SELECT rowid, embedding FROM doc_chunks WHERE embedding IS NOT NULL ${vecOriginFilter}`).all(...originParams)
-  const vecList = rows
-    .map((r) => ({ rowid: r.rowid, score: cosine(qvec, fromBlob(r.embedding)) }))
-    .sort((a, b) => b.score - a.score)
-    .slice(0, Math.max(limit * 4, 20))
+  // TUI-OOM-ROOTCAUSE（MEMORY.md §10.3）：分块扫描 + 有界 top-K（原全表 .all()——峰值 = 块 + K）
+  const top = createTopK(Math.max(limit * 4, 20))
+  scanVectors(memory.db, `SELECT rowid, embedding FROM doc_chunks WHERE embedding IS NOT NULL ${vecOriginFilter}`, originParams, {
+    onRow: (r) => top.push({ id: r.rowid, rowid: r.rowid, score: cosine(qvec, fromBlob(r.embedding)) }),
+  })
+  const vecList = top.list().map((c) => ({ rowid: c.id, score: c.score }))
 
   const K = 60
   const scores = new Map()
@@ -233,7 +239,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/scan.mjs

@@ -0,0 +1,95 @@
+/**
+ * memory/scan.mjs — 检索向量通道的分块扫描 + 有界 top-K（TUI-OOM-ROOTCAUSE 批——MEMORY.md §10）。
+ *
+ * 病灶（§10.1）：三张表的向量通道全表 `.all()` 物化后逐行 cosine + 全量排序——无 SQL LIMIT、
+ * 无分块（本机 memory.db ~736MB，embedding BLOB 为体量主源）。本模块把扫描改为
+ * **rowid 游标分块**（块 `SCAN_CHUNK_ROWS`）+ **有界 top-K**（升序小顶堆——候选集
+ * ≤ max(limit×4, 20) 既有口径）：峰值 = 块 + K；召回语义不变（仍全表评分，D-M1/D-M4）。
+ *
+ * 对外结构不变：调用方拿到的仍是 `[{id, score}]` 降序候选（RRF 融合输入）——并列分数按
+ * 既有排序稳定性规则（先到先留——与「全量稳定 sort + slice(0,K)」等价）。
+ *
+ * 可测缝（N-M1）：`scanVectors` 接受注入的 `runChunkedQuery`（默认真实 DB 实现——
+ * `AND rowid > ? ORDER BY rowid LIMIT ?`）；测试以假数据源直测块大小/top-K/等价性
+ * （不建真实大表）。
+ */
+
+/** 单块行数（单源——三处共用；D-M2：块内存量级 KB~MB，随维度有界）。 */
+export const SCAN_CHUNK_ROWS = 2_000
+
+/**
+ * 有界 top-K（升序小顶堆）：`push({id, score})` 摊销 O(log K)；`list()` 返回降序
+ * `[{id, score}]`。并列分数先到先留（与全量稳定排序一致）。
+ */
+export function createTopK(k) {
+  const cap = Math.max(1, k)
+  const heap = [] // 升序小顶堆（堆顶 = 当前最差）
+  let seq = 0
+
+  /** a 比 b 更差？（分低者差；同分 → 迟到者差（seq 大）——堆顶恒为最差） */
+  const worse = (a, b) => a.score < b.score || (a.score === b.score && a.seq > b.seq)
+  /** a 严格优于 b？（同分不互优——先到先留） */
+  const strictlyBetter = (a, b) => a.score > b.score || (a.score === b.score && a.seq < b.seq)
+  const siftUp = (i) => {
+    while (i > 0) {
+      const p = (i - 1) >> 1
+      if (worse(heap[i], heap[p])) { const t = heap[i]; heap[i] = heap[p]; heap[p] = t; i = p; continue }
+      break
+    }
+  }
+  const siftDown = (i) => {
+    for (;;) {
+      const l = i * 2 + 1
+      const r = l + 1
+      let worst = i
+      if (l < heap.length && worse(heap[l], heap[worst])) worst = l
+      if (r < heap.length && worse(heap[r], heap[worst])) worst = r
+      if (worst === i) break
+      const t = heap[i]; heap[i] = heap[worst]; heap[worst] = t
+      i = worst
+    }
+  }
+
+  return {
+    get size() { return heap.length },
+    push(item) {
+      const node = { id: item.id, score: item.score, seq: seq++ }
+      if (heap.length < cap) { heap.push(node); siftUp(heap.length - 1); return true }
+      if (!strictlyBetter(node, heap[0])) return false // 不优于当前最差（含同分迟到）→ 丢弃（先到先留）
+      heap[0] = node
+      siftDown(0)
+      return true
+    },
+    /** 降序 [{id, score}]（K 上限——与「全量 sort desc + slice(0,K)」逐条等价）。 */
+    list() {
+      return [...heap]
+        .sort((a, b) => (b.score - a.score) || (a.seq - b.seq))
+        .map((n) => ({ id: n.id, score: n.score }))
+    },
+  }
+}
+
+/**
+ * 分块扫描（rowid 游标）：逐块物化 → 逐行 `onRow` → 块内存随迭代释放。
+ * @param {object} db  sqlite 句柄（`.prepare(sql).all(...params)`）
+ * @param {string} sql 单表查询（须含 `rowid` 列；不含 LIMIT）
+ * @param {Array}  params 绑定参数（`?` 占位——顺序与 SQL 一致）
+ * @param {object} opts `{ chunk = SCAN_CHUNK_ROWS, onRow, runChunkedQuery }`
+ * @returns {number} 扫描到的行数
+ */
+export function scanVectors(db, sql, params = [], { chunk = SCAN_CHUNK_ROWS, onRow = null, runChunkedQuery = null } = {}) {
+  const run = runChunkedQuery ?? ((after, take) =>
+    db.prepare(`${sql} AND rowid > ? ORDER BY rowid LIMIT ?`).all(...params, after, take))
+  let after = 0
+  let total = 0
+  for (;;) {
+    const rows = run(after, chunk) ?? []
+    if (rows.length === 0) break
+    for (const r of rows) { total++; onRow?.(r) }
+    const next = rows[rows.length - 1]?.rowid
+    if (next === undefined || next === null || !(next > after)) break // 防御：游标不前进即止（不空转）
+    after = next
+    if (rows.length < chunk) break // 尾块
+  }
+  return total
+}

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).
  *

package/src/prompt-overlays.mjs

@@ -1,8 +1,11 @@
 /**
- * prompt-overlays.mjs — prompt overlay 载荷（2026-09-05 module-split：agent.mjs
- * 530 > 500 硬限——explore/coder/plan/eng-coder/consult 角色 overlay 的读取与导出
- * verbatim 迁入；agent.mjs re-export 保 import 面（subagent-actions.mjs /
- * setup.mjs 动态 import 零改）。byte-stable：prompts/*.md 文件内容一次性读取。
+ * prompt-overlays.mjs — prompt slot constants + the scenario→slot assembly (PROMPT-SYSTEM
+ * 施工② G1+G2, 2026-09-10). Slot constants are loaded ONCE (byte-stable, module scope);
+ * assemblePrompt composes them per PROMPT-SYSTEM.md §3.2 装配矩阵 (D1 内联表——设计锚).
+ *
+ * Slot model (PROMPT-SYSTEM.md §1/§2): persona → common → discipline → [4] other
+ * (AGENTS/skills ride the existing tail logic). explore/coder/plan reuse PERSONA_NORMAL
+ * as their persona slot (蓝图 §3.1 同槽位复用——变体差异归人格层覆写; design D1 G1 note).
  */
 
 import { readFileSync } from "node:fs"
@@ -11,15 +14,69 @@ import { fileURLToPath } from "node:url"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
-// Prompt files (byte-stable, loaded once)
-let _EXPLORE, _CODER, _PLAN, _ENG_CODER, _CONSULT_BASE
-try { _EXPLORE = readFileSync(join(__dirname, "prompts", "explore.md"), "utf8") } catch { _EXPLORE = "" }
-try { _CODER = readFileSync(join(__dirname, "prompts", "coder.md"), "utf8") } catch { _CODER = "" }
-try { _PLAN = readFileSync(join(__dirname, "prompts", "plan.md"), "utf8") } catch { _PLAN = "" }
-try { _ENG_CODER = readFileSync(join(__dirname, "prompts", "eng-coder.md"), "utf8") } catch { _ENG_CODER = "" }
-try { _CONSULT_BASE = readFileSync(join(__dirname, "prompts", "consult-base.md"), "utf8") } catch { _CONSULT_BASE = "" }
-export const EXPLORE_OVERLAY = _EXPLORE
-export const CODER_OVERLAY = _CODER
-export const PLAN_OVERLAY = _PLAN
-export const ENG_CODER_OVERLAY = _ENG_CODER
-export const CONSULT_BASE = _CONSULT_BASE
+function loadSlot(name) {
+  try { return readFileSync(join(__dirname, "prompts", name), "utf8") } catch { return "" }
+}
+
+// ── G1 槽位内容表（文件名 → 内容常量）──
+const SLOT_CONTENTS = {
+  "persona-engineering.md": loadSlot("persona-engineering.md"),
+  "persona-normal.md": loadSlot("persona-normal.md"),
+  "persona-eng-coder.md": loadSlot("persona-eng-coder.md"),
+  "persona-eng-designer.md": loadSlot("persona-eng-designer.md"),
+  "persona-explore.md": loadSlot("persona-explore.md"),
+  "persona-coder.md": loadSlot("persona-coder.md"),
+  "persona-plan.md": loadSlot("persona-plan.md"),
+  "common.md": loadSlot("common.md"),
+  "discipline-engineering.md": loadSlot("discipline-engineering.md"),
+  "discipline-normal.md": loadSlot("discipline-normal.md"),
+}
+
+// ── G1 六件导出（评审 #1 计数口径：人格 2 + 公共 1 + 纪律 2 + consult 自含基底；
+//    persona-{role} 三件由 SLOT_CONTENTS 承载、不设独立常量导出——装配表唯一消费面）──
+export const PERSONA_ENGINEERING = SLOT_CONTENTS["persona-engineering.md"]
+export const PERSONA_NORMAL = SLOT_CONTENTS["persona-normal.md"]
+export const COMMON = SLOT_CONTENTS["common.md"]
+export const DISCIPLINE_ENGINEERING = SLOT_CONTENTS["discipline-engineering.md"]
+export const DISCIPLINE_NORMAL = SLOT_CONTENTS["discipline-normal.md"]
+export const CONSULT_BASE = loadSlot("consult-base.md")
+
+// ── D1 场景→槽位文件表（PROMPT-SYSTEM.md §3.2 装配矩阵内联——①②并行契约锚：
+//    槽文件路径字符串以本表为唯一权威——设计 §1.1 红线。explore/coder/plan 行 =
+//    persona-{role}（蓝图 §3.2 1:1——施工①已落地三份角色人格文件；advisor round1
+//    修正：此前误按 G1 括注映射 persona-normal 使三文件永不被消费）。──
+export const SCENARIO_SLOT_FILES = {
+  engineering: ["persona-engineering.md", "common.md", "discipline-engineering.md"],
+  normal: ["persona-normal.md", "common.md", "discipline-normal.md"],
+  "eng-coder": ["persona-eng-coder.md", "common.md", "discipline-engineering.md"],
+  "eng-designer": ["persona-eng-designer.md", "common.md", "discipline-engineering.md"],
+  explore: ["persona-explore.md", "common.md", "discipline-normal.md"],
+  coder: ["persona-coder.md", "common.md", "discipline-normal.md"],
+  plan: ["persona-plan.md", "common.md", "discipline-normal.md"],
+  consult: null, // §3.3 特殊模块——consult-base.md 自含基底，不入主装配链（CONSULT_BASE 直出）
+}
+
+// ── D2 警告文案（走既有 setup 警告通道 = history 注入——不新增机制；common 同款）──
+export function slotWarning(fileName) {
+  return `[System reminder: prompt slot file ${fileName} missing — this slot is SKIPPED, no fallback from another slot (层间隔离). Prompt content may be degraded; check the prompts directory.]`
+}
+
+/**
+ * G2: the single prompt-assembly function — table-driven (D1), fixed order
+ * persona → common → discipline (§3.1 四槽位固定序；[4] AGENTS/skills 由既有尾部
+ * 逻辑承担). A missing slot file is SKIPPED with a prominent warning (蓝图 §3.4 降级链);
+ * AGENTS.md missing = silent skip in the caller's existing tail logic. Byte-stable
+ * per scenario (D3): fixed slot contents + fixed order — no timestamps here.
+ */
+export function assemblePrompt(scenario) {
+  const files = SCENARIO_SLOT_FILES[scenario]
+  if (!files) return { prompt: CONSULT_BASE, warnings: [] }
+  const parts = []
+  const warnings = []
+  for (const file of files) {
+    const content = SLOT_CONTENTS[file]
+    if (content) parts.push(content)
+    else warnings.push(slotWarning(file))
+  }
+  return { prompt: parts.join("\n\n"), warnings }
+}