@aiwayds/dsh-topics-memory 0.22.0 → 0.24.0

package/src/digest.ts

@@ -12,6 +12,7 @@
 import type { TopicDoc } from './okf.ts'
 import { sectionOf, firstParagraph, CONCLUSION_HEADING, RECOMMENDATIONS_HEADING } from './okf.ts'
 import type { SearchHit } from './retrieval.ts'
+import { tokenize } from './retrieval.ts'
 
 /** Rough CJK-aware token estimate: ~0.75 token per CJK char, ~4 chars per latin token. */
 export function estimateTokens(text: string): number {
@@ -109,6 +110,8 @@ export interface AssembleResult {
   dropped: { slug: string; reason: string }[]
   /** Slow-lane pointers that entered the context (v4 §4.2). */
   slowIncluded?: string[]
+  /** Established lessons that entered the context (B2, spec 卷一 §6.3). */
+  lessonIncluded?: string[]
 }
 
 export interface AssembleConfig {
@@ -125,6 +128,36 @@ export interface SlowPointerInput {
   why: string
 }
 
+/**
+ * One established-lesson pointer (B2, spec 卷一 §6.3): flat-mode normal-entry
+ * rendering with the machine-recognizable source marker (MJ-C combination
+ * matrix — lessonInject=on without the A3 package injects lessons as plain
+ * entries, tagged `lesson source:<kind>`).
+ */
+export interface LessonPointerInput {
+  slug: string
+  title: string
+  status: string
+  description?: string
+  score: number
+  source: string
+}
+
+/** The `(lesson source:x)` marker on lesson entries — flat AND package form. */
+export function lessonSourceTag(source: string): string {
+  return `lesson source:${source}`
+}
+
+/** One flat lesson entry: same two-line pointer shape + the source marker. */
+export function lessonEntryText(input: LessonPointerInput, budgetTokens: number): { text: string; usedTokens: number } {
+  const lines: string[] = []
+  lines.push(`### ${input.title} [${input.status}] (topics:${input.slug} score:${input.score.toFixed(2)}) (${lessonSourceTag(input.source)})`)
+  const one = (input.description ?? '').replace(/\s+/g, ' ').trim()
+  if (one !== '') lines.push(truncateToTokens(one, Math.max(16, budgetTokens - 32)).text)
+  const text = lines.join('\n')
+  return { text, usedTokens: estimateTokens(text) }
+}
+
 /**
  * One slow-lane pointer: same shape as a fast pointer plus the mandatory why
  * line (v4 §4.2 — 每条带 why 行). No score: the gate here was the LLM rerank,
@@ -152,8 +185,9 @@ function wrapBlocks(blocks: readonly string[]): string {
 
 /**
  * Shared greedy packing: fast entries first (score-ordered), then optional
- * slow-lane pointers, all under one total budget (v4 B2: shared 600 — the
- * slow lane spends whatever the fast lane leaves; 分账终值 is a P3 question).
+ * slow-lane pointers, then optional lesson entries (B2: flat-mode normal
+ * entry slots), all under one total budget (v4 B2: shared 600 — the slow lane
+ * spends whatever the fast lane leaves; 分账终值 is a P3 question).
  * Zero blocks → empty text (ADR 0006: 零命中零注入).
  */
 function packInjection(
@@ -161,12 +195,14 @@ function packInjection(
   cfg: AssembleConfig,
   render: (entry: DigestInput, budget: number) => { text: string; usedTokens: number },
   slow?: readonly SlowPointerInput[],
+  lessons?: readonly LessonPointerInput[],
 ): AssembleResult {
-  if (entries.length === 0 && (slow === undefined || slow.length === 0)) {
+  if (entries.length === 0 && (slow === undefined || slow.length === 0) && (lessons === undefined || lessons.length === 0)) {
     return { text: '', usedTokens: 0, included: [], dropped: [] }
   }
   const included: string[] = []
   const slowIncluded: string[] = []
+  const lessonIncluded: string[] = []
   const dropped: { slug: string; reason: string }[] = []
   const blocks: string[] = []
   let used = estimateTokens(`${WRAPPER_OPEN}\n${WRAPPER_INTRO}\n\n${WRAPPER_CLOSE}`)
@@ -200,33 +236,486 @@ function packInjection(
     slowIncluded.push(item.slug)
     used += block.usedTokens
   }
+  for (const item of lessons ?? []) {
+    const budget = Math.min(cfg.perTopicBudget, cfg.totalBudget - used)
+    if (budget < 24) {
+      dropped.push({ slug: item.slug, reason: 'lesson-budget' })
+      continue
+    }
+    const block = lessonEntryText(item, budget)
+    if (used + block.usedTokens > cfg.totalBudget) {
+      dropped.push({ slug: item.slug, reason: 'lesson-budget' })
+      continue
+    }
+    blocks.push(block.text)
+    lessonIncluded.push(item.slug)
+    used += block.usedTokens
+  }
   if (blocks.length === 0) return { text: '', usedTokens: 0, included: [], dropped }
   const text = wrapBlocks(blocks)
   const result: AssembleResult = { text, usedTokens: estimateTokens(text), included, dropped }
   if (slowIncluded.length > 0) result.slowIncluded = slowIncluded
+  if (lessonIncluded.length > 0) {
+    result.lessonIncluded = lessonIncluded
+    result.included = [...included, ...lessonIncluded]
+  }
   return result
 }
 
 /**
  * Greedily pack pointer entries (hits already score-ordered) under the total
- * budget. Zero hits → empty text (ADR 0006: 零命中零注入).
+ * budget. Zero hits → empty text (ADR 0006: 零命中零注入). `lessons` (B2)
+ * packs after the slow pointers as flat entries with the source marker.
  */
 export function assemblePointer(
   entries: readonly DigestInput[],
   cfg: AssembleConfig,
   slow?: readonly SlowPointerInput[],
+  lessons?: readonly LessonPointerInput[],
 ): AssembleResult {
-  return packInjection(entries, cfg, pointerEntry, slow)
+  return packInjection(entries, cfg, pointerEntry, slow, lessons)
 }
 
 /**
- * Greedily pack per-topic digests (hits already score-ordered) under the
- * total budget. Zero hits → empty text (ADR 0006: 零命中零注入).
+ * Greedily pack per-topic digests (hits already score-ordered) under the total
+ * budget. Zero hits → empty text (ADR 0006: 零命中零注入). `lessons` (B2).
  */
 export function assembleInjection(
   entries: readonly DigestInput[],
   cfg: AssembleConfig,
   slow?: readonly SlowPointerInput[],
+  lessons?: readonly LessonPointerInput[],
 ): AssembleResult {
-  return packInjection(entries, cfg, topicDigest, slow)
+  return packInjection(entries, cfg, topicDigest, slow, lessons)
+}
+
+// ---------------------------------------------------------------------------
+// A3 相关性三层信息包 (spec 2026-10-self-improve-topics §2) — the gated new
+// shape. Coexists with assemblePointer: the service-layer mode gate decides
+// which renderer runs; both stay pure here. 分层预算取代单条 80（§2.6）：
+// 直接相关 ~120×≤2、邻域 ~40×≤3、弱信号合并一行；总预算钉 600 不浮动
+// （A3 决议 3）。降档=琐碎 query 且与全部候选零词面实体 → null（整包跳过）。
+// ---------------------------------------------------------------------------
+
+/** One retrieval-side candidate, roster metadata pre-extracted by the caller. */
+export interface PackageCandidate {
+  slug: string
+  title: string
+  status: string
+  description?: string
+  /** Conclusion section first line (fallback for a missing description). */
+  conclusion?: string
+  score: number
+  /** Retrieval reason tags (`triggers:0.83` / `title:0.50` / `tags:…` / …). */
+  reasons: string[]
+  /** Edge/lane provenance: `depends:dN` | `slow-pick` | `semantic…` | raw. */
+  via?: string
+  /**
+   * Lesson priority seat (B2, spec 卷一 §6.3): sorts FIRST in the direct
+   * layer and is exempt from the ≤2 direct-seat cap (still budget-bound) —
+   * 「主层 ≤2 席中命中 lesson 至少 1 席」. Absent on every topic candidate.
+   */
+  prioritySeat?: boolean
+  /** Rendered as a `(${sourceTag})` suffix on the entry head — lesson source
+   *  marker (`lesson source:correction`), MJ-C. */
+  sourceTag?: string
+}
+
+export interface PackageInput {
+  query: string
+  /** Query lexemes the caller retrieved with (tokenize + §3.3 cleaning). */
+  queryTokens: string[]
+  /** Lexical strong hits (gate-passed); lands in the direct layer. */
+  direct: PackageCandidate[]
+  /** Graph expansion + slow-lane picks; lands in the neighborhood layer. */
+  neighborhood: PackageCandidate[]
+  /** nearFloor band (0.20–0.30) head; lands in the merged weak-signal line. */
+  weak: PackageCandidate[]
+  /** ADR 0015 usage signal — within-layer ordering tiebreak only (v1). */
+  usageBySlug?: Map<string, number>
+}
+
+export interface PackageOpts {
+  /**
+   * `'on'` renders the live package; `'shadow'` means the caller double-runs
+   * (old assemblePointer + this) for the bypass ledger (spec §8.3). The pure
+   * output is identical in both modes — the mode is call-site bookkeeping.
+   */
+  mode?: 'on' | 'shadow'
+}
+
+export interface PackageResult {
+  text: string
+  usedTokens: number
+  included: string[]
+  dropped: { slug: string; reason: string }[]
+  /** Final per-layer rosters (what the 包头 counts report). */
+  layers: { direct: string[]; neighborhood: string[]; weak: string[] }
+}
+
+/** Total package cap — pinned, does not float with hit strength (A3 决议 3). */
+export const PACKAGE_TOTAL = 600
+export const PACKAGE_DIRECT_MAX = 2
+export const PACKAGE_DIRECT_BUDGET = 120
+export const PACKAGE_NEIGHBOR_MAX = 3
+export const PACKAGE_NEIGHBOR_BUDGET = 40
+export const PACKAGE_WEAK_MAX = 2
+/**
+ * Padded-trivial arm of the downgrade guard (spec §2.3 名词实体口径, an
+ * implementation-time item per §11): after stripping whitespace, a query this
+ * short counts as 琐碎 even when the tokenizer expands CJK bigrams past 3
+ * tokens. Calibrated on the two named scenarios: 场景① ack query strips to
+ * 15 chars (downgrade), a real review query strips to 18 (kept).
+ */
+export const PACKAGE_TRIVIAL_QUERY_CHARS = 16
+
+const PACKAGE_WRAPPER_OPEN = '<topic-memory>'
+const PACKAGE_WRAPPER_CLOSE = '</topic-memory>'
+
+/** Edge/lane note for the why line / neighborhood annotation (A3 决议 2). */
+function viaNote(via: string | undefined): string | null {
+  if (via === undefined || via === '') return null
+  if (via.startsWith('depends')) return '经 depends 关联'
+  if (via.startsWith('slow')) return '慢道 pick'
+  if (via.startsWith('semantic')) return '语义近邻'
+  return via
+}
+
+/** Trigger reason → the trigger word when the caller carries it, `''` channel-only. */
+function triggerWordOfReason(reason: string): string | undefined {
+  const m = reason.match(/^triggers?[:：](.*)$/)
+  if (m === null) return undefined
+  const v = m[1].trim()
+  return /^[\d.+-]+$/.test(v) ? '' : v
+}
+
+/**
+ * slug/title 词面，含分隔符子词（`cs-geely-voice-agent` → `voice`/`agent`）：
+ * query 里的连字符词（voice-agent）与 slug 复合词永远不相等，实体判定必须
+ * 下探到子词才有交集；CJK 已由 tokenize 的二元切分覆盖。
+ */
+function subtokenSurface(text: string): Set<string> {
+  const out = new Set<string>()
+  for (const t of tokenize(text)) {
+    out.add(t)
+    if (/[+#.-]/.test(t)) {
+      for (const sub of t.split(/[+#.-]+/)) if (sub.length >= 2) out.add(sub)
+    }
+  }
+  return out
+}
+
+function tokenMatchesSurface(token: string, surface: ReadonlySet<string>): boolean {
+  const t = token.toLowerCase()
+  if (surface.has(t)) return true
+  if (/[+#.-]/.test(t)) {
+    for (const sub of t.split(/[+#.-]+/)) if (sub.length >= 2 && surface.has(sub)) return true
+  }
+  return false
+}
+
+/**
+ * Strict display matcher for why-line attribution: a compound query token
+ * counts as a title/weak word only when EVERY separator part ties to the
+ * surface — `voice-agent` matches `cs-geely-voice-agent`, but
+ * `cs-geely-alert-manager-api` must not match it via the shared `cs`.
+ */
+function tokenMatchesSurfaceStrict(token: string, surface: ReadonlySet<string>): boolean {
+  const t = token.toLowerCase()
+  if (surface.has(t)) return true
+  if (!/[+#.-]/.test(t)) return false
+  const subs = t.split(/[+#.-]+/).filter((s) => s.length >= 2)
+  return subs.length > 0 && subs.every((s) => surface.has(s))
+}
+
+/** Query tokens (original spelling, query order) with a词面 tie to the surface. */
+function matchedQueryTokens(queryTokens: readonly string[], surfaceText: string): string[] {
+  const surface = subtokenSurface(surfaceText)
+  const out: string[] = []
+  for (const tok of queryTokens) {
+    if (!out.includes(tok) && tokenMatchesSurfaceStrict(tok, surface)) out.push(tok)
+  }
+  return out
+}
+
+/** Entity-anchored candidate: its slug/title surface shares a query token
+ *  (验证波次修正——A③ 场景实证：词法第 3 名恰是 query 点名实体时，≤2 席
+ *  会把任务对象整体剪掉；实体锚定者不受席帽约束，仍受总预算约束）。 */
+function isEntityAnchored(queryTokens: readonly string[], c: PackageCandidate): boolean {
+  if (queryTokens.length === 0) return false
+  const surface = subtokenSurface(`${c.slug} ${c.title}`)
+  for (const tok of queryTokens) {
+    if (tokenMatchesSurface(tok, surface)) return true
+  }
+  return false
+}
+
+function hasEntityOverlap(queryTokens: readonly string[], candidates: readonly PackageCandidate[]): boolean {
+  if (queryTokens.length === 0) return false
+  for (const c of candidates) {
+    const surface = subtokenSurface(`${c.slug} ${c.title}`)
+    for (const tok of queryTokens) {
+      if (tokenMatchesSurface(tok, surface)) return true
+    }
+  }
+  return false
+}
+
+function isTrivialQuery(query: string, queryTokens: readonly string[]): boolean {
+  if (queryTokens.length <= 3) return true
+  const stripped = query.replace(/\s+/g, '')
+  return stripped.length > 0 && stripped.length <= PACKAGE_TRIVIAL_QUERY_CHARS
+}
+
+/** Stable within-layer order: prioritySeat first (lesson 优先席), then score
+ *  desc, then usage, then input order. */
+function rankStable(list: readonly PackageCandidate[], usage: Map<string, number> | undefined): PackageCandidate[] {
+  return list
+    .map((c, i) => ({ c, i, u: usage?.get(c.slug) ?? 0 }))
+    .sort((a, b) =>
+      (b.c.prioritySeat === true ? 1 : 0) - (a.c.prioritySeat === true ? 1 : 0) ||
+      b.c.score - a.c.score ||
+      b.u - a.u ||
+      a.i - b.i)
+    .map((x) => x.c)
+}
+
+/** Machine-assembled why line (A3 决议 2): hit channel + edge source + score. */
+function packageWhyLine(c: PackageCandidate, queryTokens: readonly string[]): string {
+  const parts: string[] = []
+  let triggerWord: string | null = null
+  let triggerChannel = false
+  let titleHit = false
+  const fields: string[] = []
+  for (const r of c.reasons) {
+    const tw = triggerWordOfReason(r)
+    if (tw !== undefined) {
+      if (tw === '') triggerChannel = true
+      else if (triggerWord === null) triggerWord = tw
+      continue
+    }
+    if (r.startsWith('title:')) titleHit = true
+    else if (r.startsWith('tags:')) fields.push('标签')
+    else if (r.startsWith('description:')) fields.push('描述')
+    else if (r.startsWith('conclusion:')) fields.push('正文')
+    else if (r.startsWith('slug:')) fields.push('slug')
+  }
+  if (triggerWord !== null) parts.push(`trigger「${triggerWord}」`)
+  else if (triggerChannel) parts.push('trigger 命中')
+  if (titleHit) {
+    const words = matchedQueryTokens(queryTokens, `${c.slug} ${c.title}`)
+    parts.push(words.length > 0 ? `标题词「${words.slice(0, 2).join('」「')}」` : '标题词命中')
+  }
+  if (fields.length > 0) parts.push(`${[...new Set(fields)].join('/')}词面命中`)
+  const via = viaNote(c.via)
+  if (via !== null) parts.push(via)
+  if (parts.length === 0) parts.push('词面命中')
+  return `命中: ${truncateToTokens(parts.join('、'), 32).text}（score:${c.score.toFixed(2)}）`
+}
+
+/**
+ * One direct-layer full entry (~120 tok): 标题+[status] + 一行实质 +
+ * 机器 why 行 + 指令式打开引导（预告源 description 优先，缺失回退结论行时
+ * 不再重复预告）。实质行是弹性段，超预算先截它（spec §2.4）。
+ */
+function directEntryText(
+  c: PackageCandidate,
+  queryTokens: readonly string[],
+  budget: number,
+): { text: string; usedTokens: number } {
+  const head = `### ${c.title} [${c.status}]${c.sourceTag !== undefined && c.sourceTag !== '' ? ` (${c.sourceTag})` : ''}`
+  const why = packageWhyLine(c, queryTokens)
+  const warn = c.reasons.includes('conflicted-demoted') ? '⚠ 此条存在未合并冲突，结论可能过期。' : null
+  const openBase = `细节: topic_open "${c.slug}"`
+  const conclusionLine = (c.conclusion ?? '').trim()
+  const substanceRaw = (conclusionLine !== '' ? conclusionLine : (c.description ?? '')).trim()
+  const previewRaw = (c.description ?? '').replace(/\s+/g, ' ').trim()
+
+  const lines: string[] = [head, why]
+  let substanceText = ''
+  if (substanceRaw !== '') {
+    const others = estimateTokens([head, why, openBase].join('\n')) + (warn !== null ? estimateTokens(warn) + 1 : 0)
+    const room = budget - others - 1
+    if (room >= 8) substanceText = truncateToTokens(substanceRaw, room).text
+  }
+  if (substanceText !== '') lines.push(substanceText)
+  if (warn !== null) lines.push(warn)
+  let open = openBase
+  if (previewRaw !== '' && previewRaw !== substanceText) {
+    const room = budget - estimateTokens([...lines, open].join('\n')) - 3
+    if (room >= 6) open = `${openBase}，${truncateToTokens(previewRaw, room).text}`
+  }
+  lines.push(open)
+  // Last resort for pathological heads (giant titles): shed elastic lines.
+  while (lines.length > 2 && estimateTokens(lines.join('\n')) > budget) {
+    const dropWarn = lines.indexOf(warn ?? '')
+    if (warn !== null && dropWarn !== -1) lines.splice(dropWarn, 1)
+    else if (substanceText !== '' && lines.includes(substanceText)) lines.splice(lines.indexOf(substanceText), 1)
+    else break
+  }
+  const text = lines.join('\n')
+  return { text, usedTokens: estimateTokens(text) }
+}
+
+/** One neighborhood half-line (~40 tok): 标题 + slug + 边来源/通道标注. */
+function neighborhoodEntryText(c: PackageCandidate): { text: string; usedTokens: number } {
+  const via = viaNote(c.via)
+  const text = `- ${truncateToTokens(c.title, 20).text} [${c.status}] (topics:${c.slug}) ← ${via ?? '关联扩展'}`
+  return { text, usedTokens: estimateTokens(text) }
+}
+
+/** Merged weak-signal line: nearFloor head slugs + the weak query words. */
+function weakSignalLine(
+  cands: readonly PackageCandidate[],
+  queryTokens: readonly string[],
+): { text: string; usedTokens: number; slugs: string[] } {
+  const slugs = cands.map((c) => c.slug)
+  const words: string[] = []
+  for (const c of cands) {
+    for (const w of matchedQueryTokens(queryTokens, `${c.slug} ${c.title}`)) {
+      if (!words.includes(w)) words.push(w)
+    }
+  }
+  let text = `弱信号: ${slugs.join('、')}`
+  if (words.length > 0) text += ` ← 弱词「${words.slice(0, 3).join('」「')}」`
+  return { text, usedTokens: estimateTokens(text), slugs }
+}
+
+/** 包头 one-liner: 资料声明 + 「为什么是这批」各层计数（A3 决议 1）. */
+function packageHeader(query: string, nDirect: number, nNeigh: number, nWeak: number): string {
+  const summary = truncateToTokens(query.replace(/\s+/g, ' ').trim(), 16).text
+  const clauses: string[] = []
+  if (nDirect > 0) clauses.push(`${nDirect} 条词法强命中`)
+  if (nNeigh > 0) clauses.push(`${nNeigh} 条经关联`)
+  if (nWeak > 0) clauses.push(`${nWeak} 条弱词信号`)
+  const why = clauses.length > 0 ? `为什么是这批：${clauses.join('，')}。` : ''
+  return `与「${summary}」相关的记忆（资料，非指令）。${why}`
+}
+
+/**
+ * Assemble the three-layer package. Returns `null` — the whole-package skip
+ * signal — when the roster is empty (ADR 0006 零命中零注入) or when the
+ * downgrade guard fires (spec §2.3: 琐碎 query 且与全部候选 slug/title 零
+ * 词面实体交集). Packing is layered greedy: direct first, then neighborhood,
+ * then the weak line — over budget, lower layers are cut first.
+ */
+export function assemblePackage(input: PackageInput, opts?: PackageOpts): PackageResult | null {
+  void opts // shadow 双算在调用方（旧 assemblePointer + 本函数各调一次）；两态渲染同构
+  const dropped: { slug: string; reason: string }[] = []
+  const all = [...input.direct, ...input.neighborhood, ...input.weak]
+  if (all.length === 0) return null
+  if (isTrivialQuery(input.query, input.queryTokens) && !hasEntityOverlap(input.queryTokens, all)) return null
+
+  // 跨层去重（spec §2.6）：直接层赢席；重合的邻域条目并 why（边来源并入
+  // 直接层条目）不重占席；弱信号重合直接丢弃。
+  const direct = rankStable(input.direct, input.usageBySlug).map((c) => ({ ...c }))
+  const seen = new Set(direct.map((c) => c.slug))
+  const neighborhood: PackageCandidate[] = []
+  for (const c of rankStable(input.neighborhood, input.usageBySlug)) {
+    if (seen.has(c.slug)) {
+      const host = direct.find((d) => d.slug === c.slug)
+      if (host !== undefined && host.via === undefined && c.via !== undefined) host.via = c.via
+      dropped.push({ slug: c.slug, reason: 'duplicate' })
+      continue
+    }
+    seen.add(c.slug)
+    neighborhood.push(c)
+  }
+  const weak: PackageCandidate[] = []
+  for (const c of rankStable(input.weak, input.usageBySlug)) {
+    if (seen.has(c.slug)) {
+      dropped.push({ slug: c.slug, reason: 'duplicate' })
+      continue
+    }
+    seen.add(c.slug)
+    weak.push(c)
+  }
+
+  // Reserve with an upper-bound header (pre-cap counts); the final header is
+  // never longer, so the 600 cap holds after the swap.
+  let used =
+    estimateTokens(`${PACKAGE_WRAPPER_OPEN}\n${packageHeader(input.query, direct.length, neighborhood.length, weak.length)}\n\n${PACKAGE_WRAPPER_CLOSE}`)
+
+  const layers: PackageResult['layers'] = { direct: [], neighborhood: [], weak: [] }
+  const directBlocks: string[] = []
+  for (const c of direct) {
+    // prioritySeat (lesson 优先席) is exempt from the direct-seat cap — the
+    // budget is the only thing that can still cut it.
+    if (directBlocks.length >= PACKAGE_DIRECT_MAX && !isEntityAnchored(input.queryTokens, c) && c.prioritySeat !== true) {
+      dropped.push({ slug: c.slug, reason: 'direct-cap' })
+      continue
+    }
+    const budget = Math.min(PACKAGE_DIRECT_BUDGET, PACKAGE_TOTAL - used)
+    if (budget < 24) {
+      dropped.push({ slug: c.slug, reason: 'total-budget' })
+      continue
+    }
+    const block = directEntryText(c, input.queryTokens, budget)
+    if (used + block.usedTokens > PACKAGE_TOTAL) {
+      dropped.push({ slug: c.slug, reason: 'total-budget' })
+      continue
+    }
+    directBlocks.push(block.text)
+    layers.direct.push(c.slug)
+    used += block.usedTokens
+  }
+
+  const neighBlocks: string[] = []
+  for (const c of neighborhood) {
+    if (neighBlocks.length >= PACKAGE_NEIGHBOR_MAX) {
+      dropped.push({ slug: c.slug, reason: 'neighborhood-cap' })
+      continue
+    }
+    const budget = Math.min(PACKAGE_NEIGHBOR_BUDGET, PACKAGE_TOTAL - used)
+    if (budget < 16) {
+      dropped.push({ slug: c.slug, reason: 'total-budget' })
+      continue
+    }
+    const block = neighborhoodEntryText(c)
+    if (used + block.usedTokens > PACKAGE_TOTAL) {
+      dropped.push({ slug: c.slug, reason: 'total-budget' })
+      continue
+    }
+    neighBlocks.push(block.text)
+    layers.neighborhood.push(c.slug)
+    used += block.usedTokens
+  }
+
+  const weakTake = weak.slice(0, PACKAGE_WEAK_MAX)
+  for (const c of weak.slice(PACKAGE_WEAK_MAX)) dropped.push({ slug: c.slug, reason: 'weak-cap' })
+  let weakText: string | null = null
+  if (weakTake.length > 0) {
+    const full = weakSignalLine(weakTake, input.queryTokens)
+    if (used + full.usedTokens <= PACKAGE_TOTAL) {
+      weakText = full.text
+      layers.weak = full.slugs
+      used += full.usedTokens
+    } else if (weakTake.length > 1) {
+      const single = weakSignalLine(weakTake.slice(0, 1), input.queryTokens)
+      if (used + single.usedTokens <= PACKAGE_TOTAL) {
+        weakText = single.text
+        layers.weak = single.slugs
+        used += single.usedTokens
+        for (const slug of weakTake.slice(1).map((c) => c.slug)) dropped.push({ slug, reason: 'total-budget' })
+      } else {
+        for (const slug of full.slugs) dropped.push({ slug, reason: 'total-budget' })
+      }
+    } else {
+      for (const slug of full.slugs) dropped.push({ slug, reason: 'total-budget' })
+    }
+  }
+
+  const parts: string[] = [packageHeader(input.query, layers.direct.length, layers.neighborhood.length, layers.weak.length)]
+  if (directBlocks.length > 0) parts.push(['### 直接相关', ...directBlocks].join('\n\n'))
+  if (neighBlocks.length > 0) parts.push(['### 邻域', ...neighBlocks].join('\n'))
+  if (weakText !== null) parts.push(weakText)
+  if (parts.length === 1) return null // everything budget-cut → 零命中零注入
+  const text = `${PACKAGE_WRAPPER_OPEN}\n${parts.join('\n\n')}\n${PACKAGE_WRAPPER_CLOSE}`
+  return {
+    text,
+    usedTokens: estimateTokens(text),
+    included: [...layers.direct, ...layers.neighborhood, ...layers.weak],
+    dropped,
+    layers,
+  }
 }