@thincoder/core 0.9.5 → 0.10.2

package/provider-flows.mjs

@@ -0,0 +1,248 @@
+/**
+ * provider-flows.mjs — provider 加 ∕ 删 ∕ 密钥三流程 + 渠道准入探针判据（核件 —— 「桌面处理流 · VSC 对齐」
+ * 批 R8 上提产物；2026-09-28）。
+ *
+ * 上提源 = VSC `thincoder-vscode/src/extension/provider-flows.mjs`（`addProviderFlow:60` ∕
+ * `removeProviderFlow:129` ∕ `setKeyFlow:153` ∕ `probeProviderAdmission:32`）——**纯搬 + 转口，零语义改**
+ * （三流程步序 ∕ 字段校验 ∕ 拒因 ∕ 探针语义逐字）；VSC 自持副本已随本批（parity-b4）迁移改指本档（双写窗口关闭——本档 = 桌面 ∕ VSC 消费单源）。
+ *
+ * 转口（宿主面 ⇒ 注入缝；本档零宿主依赖、零 `vscode` 引用）：
+ *  - **UI 壳**（VSC = `vscode.window.showQuickPick ∕ showInputBox ∕ showErrorMessage ∕ showWarningMessage ∕
+ *    showInformationMessage`）⇒ `ui = { pick, input, error, warn, info }`；
+ *  - **网络探针**（VSC = `probeChannelModels(name, probeTargetFromEntry(entry))`——目标构造随迁 = `probeTargetOf`）
+ *    ⇒ `deps.probe(name, target)`（缺省 = 核真探 `probeChannelModels`；测试 ∕ 端侧可注入。**缝契约** = 同
+ *    `probeChannelModels` 形：`{ ok:true, models }` ∕ `{ ok:false, error }`，**并自落账** `recordAdmission`
+ *    ——未落账 ⇒ 失败分档回落 `classifyProbeFailure` 现算）；
+ *  - **宿主忙证据覆盖**（VSC = `loop-sampler.mjs` `overrideAdmissionIfHostBusy`，F-W19）⇒
+ *    `deps.hostBusyOverride`（缺省 null = 无宿主证据 —— 核零宿主事件循环观测）。
+ * 持久化面 = 核 `config-io.mjs`（`addProviderEntry` ∕ `removeProviderEntry` ∕ `setProviderKey` ∕
+ * `resolveProviders`）——本档零副本。
+ *
+ * M9 语义定死：**准入永不阻断写** —— 探针只出读数 ∕ 失败消息（消息本体逐字长句），绝不抛出 ∕
+ * 绝不回滚已完成的保存；失败不缓存（下次配置动作重探）。
+ *
+ * 消费面：桌面 `thincoder-desktop/src/main/providers.mjs`（四通道壳——判据面：`FORMATS` ∕
+ * `customFieldsError` ∕ `probeAdmission`；端侧 reason 词法不动）；三流程本体 = 桌面 ∕ VSC（已随本批迁移改指）消费，CLI 待迁。
+ */
+import { PROVIDER_PRESETS } from "./config-presets.mjs"
+import { normalizeProxy } from "./config.mjs"
+import { addProviderEntry, loadRaw, removeProviderEntry, resolveProviders, setProviderKey } from "./config-io.mjs"
+import { admissionOf, channelUnavailableMessage, classifyProbeFailure, probeChannelModels } from "./provider/list-models.mjs"
+
+/** 自定形协议域（闭集三协议 —— VSC 同档 `FORMATS` 逐字；端侧形判 ∕ 表单选项集同值域）。 */
+export const FORMATS = Object.freeze(["openai", "anthropic", "google"])
+
+/** UI 壳缝校验（缺 ∕ 形违 ⇒ 抛 —— fail-loud：宿主未接线不得静默扮成零动作）。 */
+function requireUi(ui) {
+  if (!ui || typeof ui.pick !== "function" || typeof ui.input !== "function"
+    || typeof ui.error !== "function" || typeof ui.warn !== "function" || typeof ui.info !== "function") {
+    throw new TypeError("provider-flows: ui seam missing — inject { pick, input, error, warn, info }")
+  }
+  return ui
+}
+
+/**
+ * 自定形渠道名校验（VSC `addProviderFlow` 名称步 `validateInput` 逐字）：空 ⇒ `Name is required`；
+ * 已配 ∕ 撞预设名 ⇒ `Name already in use`；合法 ⇒ `null`。
+ * `existing` = 已配渠道名集（VSC 同源 = `resolveProviders().providers` 名集；缺省空集）。
+ */
+export function providerNameError(name, existing = new Set()) {
+  const n = String(name ?? "").trim()
+  if (!n) return "Name is required"
+  if (existing.has(n) || PROVIDER_PRESETS[n]) return "Name already in use"
+  return null
+}
+
+/**
+ * 自定形必填字段校验（VSC `addProviderFlow` 自定径输入步步序 = baseURL → model → format；
+ * name 步单列见 `providerNameError`）。三拒因串 = 核持久化面**同条件串**逐字（`config-io.mjs`
+ * `addProviderEntry`）——VSC 该三步为静默中止位（无消息可搬）⇒ 取同条件核串，保「同条件同词」。
+ * `format` 缺省 = `"openai"`（沿端侧形判同式）。
+ * @returns {string|null} 首个失败字段的拒因串；全过 ⇒ `null`
+ */
+export function customFieldsError(fields) {
+  const baseURL = String(fields?.baseURL ?? "").trim()
+  if (!baseURL) return "Base URL is required"
+  const model = String(fields?.model ?? "").trim()
+  if (!model) return "Model is required"
+  const format = fields?.format ?? "openai"
+  if (!FORMATS.includes(format)) return `Unknown API format: ${format} (expected ${FORMATS.join("/")})`
+  return null
+}
+
+/**
+ * M9 探针目标构造（上提源 = VSC `provider-flows.mjs:38` 的实参面 `presets.mjs` `probeTargetFromEntry`——
+ * 逐条随迁）：渠道条目 ⇒ `listModels` 可消费的探针目标。代理链与 chat 请求同规则（per-provider `proxy: true`
+ * ∧ 全局 `proxy.model === true` ⇒ 探针也走该代理）；apiKey 归一（trim；缺 ⇒ 空串——探针会如实失败 ⇒
+ * 渠道标「不可用」——准入判据 M8）。
+ */
+export function probeTargetOf(entry) {
+  const raw = loadRaw()
+  const proxyCfg = normalizeProxy(raw.proxy)
+  const proxyUri = entry?.proxy === true && proxyCfg?.uri && proxyCfg.model === true ? proxyCfg.uri : undefined
+  return {
+    name: entry?.name,
+    baseURL: entry?.baseURL,
+    apiKey: typeof entry?.apiKey === "string" ? entry.apiKey.trim() : "",
+    format: entry?.format,
+    proxyUri,
+  }
+}
+
+/**
+ * 探针 + 失败分档（已解析条目的低层面 —— 端侧「读账优先 ∕ 未落账回落现算」单源：
+ * `failure` ∈ { timeout, malformed, hostBusy }，分类本体住核 `classifyProbeFailure`；网络探针经 `deps.probe`
+ * 注入，缺省 = 核真探；**探针目标由本档 `probeTargetOf` 构造**（同 VSC 源实参）。**绝不抛出**（探针族语义）。
+ * @returns {{ok:true, models:string[]} | {ok:false, failure:string, error:string}}
+ */
+export async function probeAdmission(name, provider, deps = {}) {
+  const probe = typeof deps.probe === "function" ? deps.probe : probeChannelModels
+  const r = await probe(name, probeTargetOf(provider))
+  if (r?.ok) return { ok: true, models: r.models ?? [] }
+  const error = r?.error
+  const failure = admissionOf(name)?.failure ?? classifyProbeFailure({ message: error })
+  return { ok: false, failure, error }
+}
+
+/** M9 渠道准入探（配置写入面）：对目标渠道探一次 `GET /models`。
+ *  探通 → 渠道可用（探得候选可直接用）；探不通 → 记录失败展示态（providerStatus 行 `不可用` + 失败消息本体）
+ *  并返回失败消息供调用方提示。**绝不抛出、绝不阻断任何写**；失败不缓存——下次配置动作重探。 */
+export async function probeProviderAdmission(name, deps = {}) {
+  if (!name) return { ok: false, error: "provider name is required" }
+  try {
+    const { providers } = resolveProviders()
+    const entry = providers.find((p) => p.name === name)
+    if (!entry) return { ok: false, error: `Unknown provider "${name}"` }
+    const r = await probeAdmission(name, entry, deps)
+    // F-W19：核分类只知超时 ∕ 畸形；宿主忙 = 端侧证据 ⇒ 覆盖落账分类为 `hostBusy`
+    // （`reason` 逐字不动；返回面零扩张）——宿主证据经注入缝给（核零宿主事件循环观测）。
+    if (!r.ok && typeof deps.hostBusyOverride === "function") deps.hostBusyOverride(name, r.error)
+    return r.ok ? { ok: true, models: r.models } : { ok: false, error: r.error }
+  } catch (e) {
+    return { ok: false, error: channelUnavailableMessage(e) }
+  }
+}
+
+/** M9：探一次并在失败时界面明示失败消息（消息本体逐字长句）——不阻断已完成的保存。 */
+async function reportAdmission(name, ui, deps) {
+  const probe = await probeProviderAdmission(name, deps)
+  if (!probe.ok) ui.warn(probe.error)
+  return probe
+}
+
+// ─── Three interactive flows (host UI shell injected) ───
+
+/** Add a provider interactively: pick an unused preset or configure custom manually. */
+export async function addProviderFlow(ui, refresh, deps = {}) {
+  const host = requireUi(ui)
+  let providers
+  try {
+    ({ providers } = resolveProviders())
+  } catch (e) {
+    host.error(e.message)
+    return
+  }
+  const existing = new Set(providers.map((p) => p.name))
+
+  const items = Object.entries(PROVIDER_PRESETS)
+    .filter(([name]) => !existing.has(name))
+    .map(([name, p]) => ({ label: name, description: p.desc, detail: p.model ?? "", kind: "preset", name }))
+  items.push({ label: "Custom (manual config)", description: "enter baseURL/model/format", kind: "custom" })
+
+  const sel = await host.pick(items, {
+    placeHolder: "Add provider — select a preset",
+    matchOnDescription: true, matchOnDetail: true,
+  })
+  if (!sel) return
+
+  if (sel.kind === "custom") {
+    const name = (await host.input({
+      prompt: "Provider name",
+      validateInput: (v) => providerNameError(v, existing),
+    }))?.trim()
+    if (!name) return
+    const baseURL = (await host.input({
+      prompt: `Base URL for ${name}`,
+      placeHolder: "https://api.example.com/v1",
+    }))?.trim()
+    if (!baseURL) return
+    const model = (await host.input({ prompt: `Model name for ${name}` }))?.trim()
+    if (!model) return
+    const format = await host.pick(
+      FORMATS.map((f) => ({ label: f, description: f === "openai" ? "(default)" : f === "anthropic" ? "Messages API" : "streamGenerateContent" })),
+      { placeHolder: "API format" },
+    )
+    if (!format) return
+    const err = addProviderEntry({ custom: { name, baseURL, model, format: format.label } })
+    if (err) { host.error(err); return }
+    const key = await host.input({ prompt: `API key for ${name} (leave empty to skip)`, password: true })
+    if (key?.trim()) {
+      const kerr = setProviderKey(name, key.trim())
+      if (kerr) { host.error(kerr); return } // F5b：config 并发被改——放弃 + 提示重试
+    }
+    await refresh?.()
+    await reportAdmission(name, host, deps) // M9：加渠道的配置写入面——探一次 /models（失败标不可用，不阻断保存）
+    return
+  }
+
+  // Preset: entry auto-filled from PROVIDER_PRESETS, then ask for a key
+  const err = addProviderEntry({ preset: sel.name })
+  if (err) { host.error(err); return }
+  const key = await host.input({ prompt: `API key for ${sel.name} (leave empty to skip)`, password: true })
+  if (key?.trim()) {
+    const kerr = setProviderKey(sel.name, key.trim())
+    if (kerr) { host.error(kerr); return } // F5b：冲突放弃提示重试
+  }
+  await refresh?.()
+  await reportAdmission(sel.name, host, deps) // M9：同上
+}
+
+/** Remove a provider interactively (active one is not listed, CLI parity). */
+export async function removeProviderFlow(ui, refresh) {
+  const host = requireUi(ui)
+  let providers, activeProvider
+  try {
+    ({ providers, activeProvider } = resolveProviders())
+  } catch (e) {
+    host.error(e.message)
+    return
+  }
+  const candidates = providers.filter((p) => p.name !== activeProvider)
+  if (candidates.length === 0) {
+    host.info("No removable providers — the active provider is kept.")
+    return
+  }
+  const sel = await host.pick(
+    candidates.map((p) => ({ label: p.name, description: p.model ?? "" })),
+    { placeHolder: "Remove provider" },
+  )
+  if (!sel) return
+  const err = removeProviderEntry(sel.label)
+  if (err) host.error(err)
+  else await refresh?.()
+}
+
+/** Set / replace an API key for a configured provider. */
+export async function setKeyFlow(ui, refresh, deps = {}) {
+  const host = requireUi(ui)
+  let providers
+  try {
+    ({ providers } = resolveProviders())
+  } catch (e) {
+    host.error(e.message)
+    return
+  }
+  if (providers.length === 0) return
+  const sel = await host.pick(
+    providers.map((p) => ({ label: p.name, description: p.apiKey ? "(has key)" : "(no key)" })),
+    { placeHolder: "Set API key for provider" },
+  )
+  if (!sel) return
+  const key = await host.input({ prompt: `API key for ${sel.label}`, password: true })
+  if (key?.trim()) {
+    const kerr = setProviderKey(sel.label, key.trim())
+    if (kerr) { host.error(kerr); return } // F5b：config 并发被改——放弃 + 提示重试
+    await refresh?.()
+  }
+  await reportAdmission(sel.label, host, deps) // M9：设 API key 的配置写入面——探一次 /models（失败标不可用，不阻断保存）
+}

package/queued.mjs

@@ -0,0 +1,90 @@
+/**
+ * queued.mjs — busy 排队消息的合并消费纯函数族（核件——「桌面处理流 · VSC 对齐」批 R3 上提产物）。
+ *
+ * 机制单源 = `docs/core/design/AGENT-LOOP-ASYNC-POOL.md` §6.8（「合并消费」条 + 「步边界 pickup」块）。
+ * 上提源 = VSC `thincoder-vscode/src/extension/queued-merge.mjs:15-36`（容量常量 ∕ 合并串 ∕ 批计划）
+ * + `queued-pickup.mjs:49`（`takeQueuedBatchItem` 取项）——**纯搬 + 转口，零语义改**（常量名 / 值 /
+ * 形态文案 / 批语义逐字）；对拍锚 = CLI 副本 `thincoder-cli/src/tui/queued-merge.mjs`（同名同值）。
+ *
+ * 消费面：计划面（常量 ∕ 合并串 ∕ 计划）由桌面排队面消费（`thincoder-desktop/src/main/queued-input.mjs`）；
+ * `takeQueuedBatchItem` = **取项单源**（携图批退化逐条 ∕ slash 单条取——统一语义 = 计划首动作即消费），
+ * 消费点在册五处 = VSC 三径（`panel-turn-stages.mjs` 退出兜底 ∕ `suspension.mjs` 取项缝 ∕ 同档退出残余）
+ * + 桌面两径（`turn-chain.mjs` 尾径 ∕ `suspension-drive.mjs` 窗输入面）。
+ *
+ * 留端（载体面不迁——各端 adapter 各持）：队容器（按会话键 `Map` ∥ 单容器）· 容量门与满队回执 ·
+ * 快照投影 · 步边界守卫与送达面（附件判决 ∕ 回合链出站）· 显示面。
+ */
+
+// ── 合并常量（三端逐字一致）：单批 ≤ MAX_MERGE_ITEMS 条且合并注入 ≤ MAX_MERGE_CHARS 字符；
+// 超限截批先行（余下留待下批——不丢不截断单条）；单条 > MAX_MERGE_CHARS 直发不进批；
+// /cmd 不进合并（逐条保序即时）。──
+export const MAX_MERGE_ITEMS = 8
+export const MAX_MERGE_CHARS = 2000
+
+/** 队容量（条）——**三端同名常量**（无会话载体与会话在飞载体合计口径；满队 = 第 9 条 ⇒
+ *  拒收 + 提示 + 不回显——容量门与满队回执留端）。 */
+export const QUEUED_MAX_ITEMS = 8
+
+/** 合并注入形态（编号逐条——模型一次处理全部；zh 字面，三端逐字）。 */
+export function formatMergedMessages(items) {
+  return `你排队了 ${items.length} 条消息：\n${items.map((m, i) => `${i + 1}. ${m}`).join("\n")}\n——一次处理`
+}
+
+/**
+ * R15 攒批计划（纯函数——消费点共享同一事实源）：按队列顺序产出动作序列（输入 = 文本数组；
+ * 调用侧以 `queue.map((q) => q.text)` 取数）。
+ * - { kind:"slash", text, count:1 }——/cmd 逐条即时执行（保序——不进合并缓冲）；
+ * - { kind:"turn", text, count, merged }——文本批次：连续非 / 条目攒批（单批 ≤ MAX_MERGE_ITEMS 条；
+ *   合并注入（格式化后）≤ MAX_MERGE_CHARS 字符；count ≥2 → merged 编号注入；count === 1 → 原文
+ *   直发（含单条 > MAX_MERGE_CHARS——不进批）；超限截批先行——余下条目留待下批（不丢）。
+ * 消费者每次取动作 [0] 并按 count 从源队列移除——下轮重新计划余项（边界幂等）。
+ */
+export function planQueuedInput(items) {
+  const actions = []
+  const n = items.length
+  let i = 0
+  while (i < n) {
+    const cur = String(items[i])
+    if (cur.startsWith("/")) { actions.push({ kind: "slash", text: cur, count: 1 }); i++; continue }
+    let j = i
+    for (;;) {
+      if (j - i >= MAX_MERGE_ITEMS || j >= n) break
+      const it = String(items[j])
+      if (it.startsWith("/")) break
+      if (it.length > MAX_MERGE_CHARS) break // 单条超长——不进批（留作直发）
+      const cand = items.slice(i, j + 1)
+      if (cand.length > 1 && formatMergedMessages(cand).length > MAX_MERGE_CHARS) break // 批总长超限——截批
+      j++
+    }
+    // 超长条目堵头（内环一步未进）→ 该条直发（不进批——也不与前后合并）
+    if (j === i) { actions.push({ kind: "turn", text: String(items[i]), count: 1, merged: false }); i++; continue }
+    const taken = items.slice(i, j)
+    if (taken.length === 1) {
+      actions.push({ kind: "turn", text: String(taken[0]), count: 1, merged: false })
+    } else {
+      actions.push({ kind: "turn", text: formatMergedMessages(taken), count: taken.length, merged: true })
+    }
+    i = j
+  }
+  return actions
+}
+
+/** 贴图判定（取项退化与步边界让位共用——图片随条目元数据走降级面，不静默丢）。 */
+const hasImages = (q) => Array.isArray(q?.images) && q.images.length > 0
+
+/**
+ * 载体条目面取批（纯函数——就地消费；**统一语义 = 计划首动作即消费**）：`turn` 首动作 ⇒ 按计划取一批
+ * （多条合并 ∕ 超长直发）；`slash` 首动作 ⇒ 单条取（count 1 ∕ 原文——保序 ∕ 不合并）。
+ * **贴图批退化逐条**（批内任一条目携 `images` ⇒ count = 1——图片随条目元数据走降级面）；
+ * 无贴图 ⇒ 多条合并为一条（头条目元数据 + 合并文本）。
+ * @param {Array} queue 载体条目数组（条目 `{ text, images?, ... }`——就地 `splice` 消费）
+ * @returns {{item: object|null, merged: string|null}} 取出的载体条目 + 本批文本（快照 `merged` 源）
+ */
+export function takeQueuedBatchItem(queue) {
+  if (!Array.isArray(queue) || queue.length === 0) return { item: null, merged: null }
+  const action = planQueuedInput(queue.map((q) => String(q?.text ?? "")))[0]
+  const count = queue.slice(0, action.count).some(hasImages) ? 1 : action.count
+  const taken = queue.splice(0, count)
+  const text = count > 1 ? action.text : String(taken[0]?.text ?? "")
+  return { item: { ...taken[0], text }, merged: text }
+}

package/rules.mjs

@@ -1,7 +1,12 @@
 /**
- * rules.mjs — stream rule discovery from .thincoder/rules/*.md
+ * rules.mjs — 规则面**单源**（两面）：
+ *   ① stream 规则（`.thincoder/rules/*.md`——两端；`discoverRules` ∕ `mergeFileRules`）
+ *   ② 作用域规则（`.cursor/rules/*`——三端同面；`loadRules` 读取 ∕ 三分类 ∕ 尾块 ∕ JIT 注入全档单源）
  *
- * Rule file format (markdown + YAML frontmatter):
+ * 面定义（权威）= `docs/core/design/WORKSPACE.md` §2.3「规则发现面（一线程一语义）」：
+ * `.thincoder/rules/*` 恒 = stream 规则；`.cursor/rules/*` 恒 = 作用域规则。
+ *
+ * Stream rule file format (markdown + YAML frontmatter):
  *   ---
  *   pattern: "console\\.log"
  *   action: abort        # "abort"|"warn" (default: "warn")
@@ -10,10 +15,19 @@
  *   Use the project logger instead of console.log.
  *
  * The body becomes the rule message; if empty, falls back to `message` frontmatter.
+ *
+ * 上提史（R10 → B7 3a）：`.cursor/rules` **读取面**（`loadRules` + 私有 frontmatter 解析）自 VSC
+ * `thincoder-vscode/src/extension/rules.mjs` 纯搬（R10）；**三分类 ∕ 尾块文本 ∕ JIT 注入判据**
+ * 自 VSC `src/agent/rules-face.mjs` 纯搬 · **glob 匹配**（`matchesGlob`）自 VSC
+ * `src/extension/rules.mjs` 纯搬 · **合并**（`mergeFileRules`）自核 `agent/assemble.mjs` 内联块
+ * 抽取（B7 3a——均零语义改；VSC 两档退役，desk ∕ CLI 乘核径取得）。尾块 ∕ JIT 两缝同门
+ * `depth === 0`（B7 §2 修正轮 1 ④——子代理不携 `.cursor/rules`）。
  */
 import { existsSync, readFileSync, readdirSync } from "node:fs"
 import { join } from "node:path"
 import { parseFrontmatter } from "./markdown.mjs"
+// #327 触达路径单源谓词 + 写集（JIT 面 `PATH_TOOLS` 构造——B7 3a：与门禁 ∕ 记账同址单源）
+import { FILE_MUTATORS, toolTouchPaths } from "./agent/helpers.mjs"
 
 /**
  * Scan `.thincoder/rules/` in the project root for `.md` rule files.
@@ -51,3 +65,196 @@ export function discoverRules(projectRoot) {
   }
   return rules
 }
+
+// ─── A 面：stream 规则装配合并（`.thincoder/rules`——B7 3a 自核装配内联块抽取单源）────────
+
+/** 装配合并：`.thincoder/rules/` 文件规则**置前**，config 规则按 `pattern` 去重（文件侧优先；
+ *  逐字镜像原 CLI `make-agent.mjs:44-48` 语义）。文件规则为空 ⇒ 归一数组原样返回（零拷贝零改）。
+ *  `discover` 可注入（核装配 `DEFAULT_DEPS.discoverRules` 缝——U79 装配序可机验；VSC 端壳同取本件）。 */
+export function mergeFileRules(configRules, cwd, discover = discoverRules) {
+  const rules = Array.isArray(configRules) ? configRules : []
+  const fileRules = discover(cwd)
+  if (fileRules.length === 0) return rules
+  const filePatterns = new Set(fileRules.map((r) => r.pattern))
+  return [...fileRules, ...rules.filter((r) => !filePatterns.has(r.pattern))]
+}
+
+// ─── B 面：作用域规则读取面（`.cursor/rules`——R10 上提；纯搬自 VSC `src/extension/rules.mjs:28-81`）──
+
+/**
+ * Load all scoped rules from `.cursor/rules/`.
+ * Returns [{ name, content, globs, alwaysApply, description, source }, ...]
+ */
+export function loadRules(cwd) {
+  const dir = join(cwd, ".cursor/rules")
+  if (!existsSync(dir)) return []
+  const results = []
+  let entries
+  try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return results }
+  for (const e of entries) {
+    if (!e.isFile() || e.name.startsWith(".") || (!e.name.endsWith(".md") && !e.name.endsWith(".mdc"))) continue
+    try {
+      const raw = readFileSync(join(dir, e.name), "utf8").trim()
+      if (raw.length === 0) continue
+      const { content, meta } = parseScopedFrontmatter(raw)
+      results.push({
+        name: e.name.replace(/\.(md|mdc)$/, ""),
+        content,
+        globs: meta.globs ? String(meta.globs).split(/[;\n]/).map(s => s.trim()).filter(Boolean) : null,
+        alwaysApply: meta.alwaysApply === "true",
+        description: meta.description ? String(meta.description) : null,
+        source: ".cursor/rules",
+      })
+    } catch { /* skip unreadable */ }
+  }
+  return results
+}
+
+/**
+ * Split frontmatter block from content.
+ * Frontmatter starts and ends with `---` on its own line.
+ * （私有件——随搬；名改 `parseScopedFrontmatter` = 与 `./markdown.mjs` 的 `parseFrontmatter`
+ *   导入同名冲突的机械改名——**体逐字纯搬，零语义改**。）
+ */
+function parseScopedFrontmatter(raw) {
+  const m = raw.match(/^---\s*\n([\s\S]*?)\n---\s*\n?/)
+  if (!m) return { content: raw, meta: {} }
+
+  const front = m[1]
+  const content = raw.slice(m[0].length).trim()
+  const meta = {}
+  for (const line of front.split("\n")) {
+    const kv = line.match(/^(\w[\w-]*)\s*:\s*(.+?)\s*$/)
+    if (kv) {
+      const key = kv[1]
+      let val = kv[2]
+      // Strip surrounding quotes
+      if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+        val = val.slice(1, -1)
+      }
+      meta[key] = val
+    }
+  }
+  return { content, meta }
+}
+
+// ─── B 面判据：三分类 ∕ 尾块 ∕ glob ∕ JIT（B7 3a 自 VSC 端壳上提单源）─────────────────────────
+
+/** 三分类（**按序判定·互斥**——权威定义 `docs/core/design/WORKSPACE.md` §2.3）：
+ *  ① `alwaysApply === true` ⇒ **常驻集**（**先判**——`globs` 同在不改分类）
+ *  ② 有 `globs` ⇒ **作用域集**（命中路径的工具派发前置提醒）
+ *  ③ 无 `globs` 且无 `description` ⇒ **常驻集**
+ *  ④ 仅 `description`（Cursor 的 agent-requested 语义）⇒ 两集皆无（本端无该机制——登记）。 */
+export function classifyRules(rules) {
+  const always = []
+  const scoped = []
+  for (const r of rules ?? []) {
+    if (r.alwaysApply === true) always.push(r)
+    else if (r.globs?.length) scoped.push(r)
+    else if (!r.description) always.push(r)
+  }
+  return { always, scoped }
+}
+
+/** 目录读点（每 run 一次——装配期）：`.cursor/rules` 读取 + 三分类（本函数 = 分类入口单源）。 */
+export function loadScopedRules(cwd) {
+  return classifyRules(loadRules(cwd))
+}
+
+/** 常驻集注入块（[4] 层尾块——与项目指令块同槽：每 run 重建、不进 history）+ **本 run 唯一
+ *  一次目录读取**：结果缓存于 `agent._rules`（`{ always, scoped }`）——作用域集 JIT 判定
+ *  只读该缓存（零重读盘）。无命中 ⇒ 空串（零改字符串）。 */
+export function scopedRulesBlock(agent, cwd) {
+  const rules = loadScopedRules(cwd)
+  if (agent) agent._rules = rules
+  if (rules.always.length === 0) return ""
+  return `\n\nProject rules (.cursor/rules):\n${rules.always.map((r) => `- ${r.name}: ${r.content}`).join("\n")}`
+}
+
+/** 文件路径 glob 匹配（简单 `*` / `**` / `?` 通配——无完整 glob 库；纯搬自 VSC
+ *  `src/extension/rules.mjs:37-74`，零语义改）。 */
+export function matchesGlob(filePath, patterns) {
+  if (!patterns || patterns.length === 0) return false
+  // Normalize to forward slashes
+  const normalized = filePath.replace(/\\/g, "/")
+  for (const pat of patterns) {
+    if (simpleGlobMatch(normalized, pat.replace(/\\/g, "/"))) return true
+  }
+  return false
+}
+
+/** Simple glob match: supports *, **, ? */
+function simpleGlobMatch(path, pattern) {
+  // Convert glob pattern to regex
+  let regexStr = ""
+  let i = 0
+  while (i < pattern.length) {
+    if (pattern[i] === "*" && pattern[i + 1] === "*") {
+      // ** matches anything including /
+      regexStr += ".*"
+      i += 2
+      // Skip trailing /
+      if (pattern[i] === "/") i++
+    } else if (pattern[i] === "*") {
+      regexStr += "[^/]*"
+      i++
+    } else if (pattern[i] === "?") {
+      regexStr += "[^/]"
+      i++
+    } else {
+      // Escape regex special chars
+      const c = pattern[i]
+      if (".+^${}()|[]\\".includes(c)) regexStr += "\\" + c
+      else regexStr += c
+      i++
+    }
+  }
+  return new RegExp("^" + regexStr + "$").test(path)
+}
+
+const PATH_TOOLS = new Set([...FILE_MUTATORS, "file_ops", "read", "glob"])
+
+/** 路径候选（绝对路径先归一为 cwd 相对——globs 语义 = 项目相对；`read` 可收绝对路径）：
+ *  前缀比对**大小写不敏感**（VS Code `uri.fsPath` 的 Windows 盘符为小写，模型侧常给大写盘符
+ *  ——`D:\proj\a.py` vs cwd `d:\proj`）；另剥前导 `./`。 */
+function matchCandidates(p, cwd) {
+  const norm = String(p).replace(/\\/g, "/").replace(/^\.\//, "")
+  const out = [norm]
+  const base = String(cwd ?? "").replace(/\\/g, "/").replace(/\/+$/, "")
+  const underCwd = base && norm.length > base.length
+    && norm.slice(0, base.length).toLowerCase() === base.toLowerCase() && norm[base.length] === "/"
+  if (underCwd) out.push(norm.slice(base.length + 1))
+  return out
+}
+
+/** 作用域集 JIT 注入（**派发前**——模型下一轮可见）：文件路径类工具（`FILE_MUTATORS` ∪
+ *  `file_ops` ∪ `read` / `glob`）的触达路径命中**未注入**规则 ⇒ `history` 注入
+ *  `[System reminder — project rule "<name>" (globs: <g>): <content>]`。语义一句话 =
+ *  「Agent 将触碰匹配文件时，该文件作用域的规则先入上下文」。去重键 = `name`；去重域 =
+ *  会话（`agent._rulesInjected` 惰性建 Set——顶层 agent 单例；子代理 agent 每 run 新对象
+ *  ⇒ 去重域 = 该子回合）。路径候选 = #327 单源谓词（`toolTouchPaths`——设计
+ *  B-4 公式）——`read.filePath` 别名与 `glob.pattern` **不作候选**（登记边界）。
+ *  @returns {number} 本次注入条数（测试直驱面）。 */
+export function injectScopedRules(agent, history, calls) {
+  const scoped = agent?._rules?.scoped ?? []
+  if (scoped.length === 0) return 0
+  const injected = (agent._rulesInjected ??= new Set())
+  let count = 0
+  for (const { tool, args } of calls ?? []) {
+    if (!PATH_TOOLS.has(tool?.name)) continue
+    const raw = toolTouchPaths(tool, args)
+    const paths = (raw ?? []).filter((p) => typeof p === "string" && p).flatMap((p) => matchCandidates(p, agent.cwd))
+    if (paths.length === 0) continue
+    for (const rule of scoped) {
+      if (injected.has(rule.name)) continue
+      if (!paths.some((p) => matchesGlob(p, rule.globs))) continue
+      injected.add(rule.name)
+      history.push({
+        role: "user",
+        content: `[System reminder — project rule "${rule.name}" (globs: ${rule.globs.join("; ")}): ${rule.content}]`,
+      })
+      count++
+    }
+  }
+  return count
+}

package/session-guard.mjs

@@ -4,20 +4,29 @@
  * 行随迁，verbatim 零语义变）：saveSession 与 token-ttl persistEngTokens 共用同一份。
  * 写前校验磁盘槽文件是否本进程会话的现场——磁盘文件 sessionStart 与本进程会话不符
  * （另一进程/会话的现场）/版本更新/异 cwd → 先轮转 .bak 保留再写。检查按 mtime 缓存
- * （agent._slotMtime）：文件自上次检查/自写未变就跳过全量解析——每次保存都
+ * （agent._slotMtime = `{p, mtimeMs}`——**按槽文件路径**命中，见 #386 复核）：文件自上次检查/自写未变就跳过全量解析——每次保存都
  * readFileSync+JSON.parse 多 MB 会话 → O(n²) 退化。文件存在但不可读（损坏/半写）→
  * 改名 .corrupted 保留现场。返回轮转的 .bak 路径或 null。
+ *
+ * 创建端取值链（SLOT-END-PARAM 批 §6.20 判据句 4）：本守卫是全量解析盘面的唯一写前窗口
+ * ⇒ 创建端**顺带解析**（副作用回写 `agent._slotCreatedBy`，供 saveSession 在守卫**之后**
+ * 注入 fields——分支：文件不在盘 / 轮转 / 损坏改名 ⇒ `sessionEnd()`（本端将首物化这份文件）；
+ * 解析通过未轮转 ⇒ `disk.createdBy ?? null`（透传盘上键；老槽无键 ⇒ null ⇒ 禁回填）；
+ * mtime 命中 ⇒ 本函数未解析盘面 ⇒ 值不动）。
  */
 
 import { existsSync, readFileSync, renameSync, statSync } from "node:fs"
 import { basename } from "node:path"
-// §14.3.8①（修正轮 #1）：.bak 轮转对**非本会话活动绑定面**联动改名 sidecar（`{p}.d → {bak}.d`）。
+// SESSION.md §6.12①（修正轮 #1）：.bak 轮转对**非本会话活动绑定面**联动改名 sidecar（`{p}.d → {bak}.d`）。
 import { RECORD_DIR_SUFFIX } from "./session-store.mjs"
+// 本进程端名（创建端取值链缺省值）——静态环：本档 ↔ session-slots.mjs（经 session.mjs，同
+// 两档头注：函数体内运行时使用、求值期零顶层调用 ⇒ 环安全）。
+import { sessionEnd } from "./session-slots.mjs"
 
 /** 轮转时随迁记录存储（.bak 路径联动）——本会话活动绑定面跳过（防拔掉活动存储）。 */
 function moveSidecar(src, dst, agent) {
   const dir = src + RECORD_DIR_SUFFIX
-  if (agent?._recordStore?.dir === dir) return // 本会话活动绑定面——原地保留（§14.3.8①）
+  if (agent?._recordStore?.dir === dir) return // 本会话活动绑定面——原地保留（SESSION.md §6.12①）
   try {
     if (existsSync(dir)) renameSync(dir, dst + RECORD_DIR_SUFFIX)
   } catch { /* 随迁失败不阻断轮转（现场原地保留——读侧身份核验兜底） */ }
@@ -25,9 +34,17 @@ function moveSidecar(src, dst, agent) {
 
 export function guardForeignSlotFile(agent, p, slot) {
   try {
-    if (!existsSync(p)) return null
+    if (!existsSync(p)) {
+      agent._slotCreatedBy = sessionEnd() // 文件不在盘 ⇒ 本端即将首物化（= 创建端）
+      return null
+    }
     const st = statSync(p)
-    if (st.mtimeMs === (agent._slotMtime ?? -1)) return null
+    // mtime 命中（**同路径** ∧ 同 mtime）：未解析盘面 ⇒ 值不动。缓存带路径标签（#386 复核）——
+    // 单 agent 换槽复用（`_slot` 直钉新槽，未经 applySession / resetSessionState 清缓存）时，
+    // 旧槽 mtime 不得命中新槽（同 mtime 巧合 ⇒ 漏轮转 / 漏 createdBy 透传）；「换槽即清缓存」
+    // 不再是被依赖的隐式前提。
+    const hit = agent._slotMtime
+    if (hit && hit.p === p && st.mtimeMs === hit.mtimeMs) return null
     const disk = JSON.parse(readFileSync(p, "utf8"))
     // version>2 的新版文件无论 sessionStart 一律轮转（loadSlotFile 对 v3 返回 null 不动
     // 文件——若其 sessionStart 为 null，旧版首次保存会静默覆盖；轮转 .bak 保证新版文件
@@ -42,10 +59,12 @@ export function guardForeignSlotFile(agent, p, slot) {
       renameSync(p, bak)
       moveSidecar(p, bak, agent)
       console.error(`[session] slot ${slot} holds ${diskIsNewer ? `a newer-version file (v${disk.version})` : diskForeign ? `a foreign-cwd file (${disk.cwd})` : `another session (start ${diskStart}, ours ${myStart})`} — preserved as ${basename(bak)}`)
-      agent._slotMtime = st.mtimeMs
+      agent._slotMtime = { p, mtimeMs: st.mtimeMs }
+      agent._slotCreatedBy = sessionEnd() // 轮转：现场已让位 ⇒ 本端将首物化新文件
       return bak
     }
-    agent._slotMtime = st.mtimeMs
+    agent._slotMtime = { p, mtimeMs: st.mtimeMs }
+    agent._slotCreatedBy = disk?.createdBy ?? null // 解析通过：透传盘上键（无键 ⇒ null ⇒ 禁回填）
     return null
   } catch {
     // 文件存在但不可读（损坏/半写）：改名 .corrupted 保留现场（2026-09-01 advisor 🔵——
@@ -54,6 +73,7 @@ export function guardForeignSlotFile(agent, p, slot) {
     if (existsSync(p)) {
       try { renameSync(p, `${p}.corrupted`) } catch {}
     }
+    agent._slotCreatedBy = sessionEnd() // 损坏改名：现场已让位 ⇒ 本端将首物化新文件
     return null
   }
 }