dsh-data-domain-knowledge 0.1.0-alpha.2 → 0.1.0-alpha.4

package/src/present.ts

@@ -0,0 +1,367 @@
+/**
+ * 知识工具在**对话流**里的样子（0045）。
+ *
+ * ## 为什么要有这个文件
+ *
+ * 0045 之前，这些工具的 `output.render` 统一是 `JSON.stringify(value)`，而 Web 端没有
+ * 给它们注册 toolview —— 于是「让 Agent 批量编译入库」在对话流里长成一条
+ * `import_sources` 加一坨 JSON，「召回知识库」同理。人看不到「导了几份、编出了几张卡、
+ * 命中了哪几条」，只能自己去右侧面板里找。
+ *
+ * 这一层做两件事，都在**纯函数**里，所以能被测试钉住：
+ *
+ * 1. `presentationMeta` —— 结构化的小账本，随 `tool/result` 落进会话日志，
+ *    Web 端的卡片读它渲染（`src/client/KnowledgeToolRow.tsx`）。它必须
+ *    **可 JSON 序列化**（会话日志会整份校验），所以这里不塞函数、不塞 Date；
+ * 2. `present*View` —— 与工具名无关的渲染意图（标题 / 分类 / 一段 Markdown），
+ *    给终端界面和「没有专用卡片的界面」用。
+ *
+ * ## 一条规矩：数字必须来自真实的产物
+ *
+ * 这些账本里出现的每一个数都对应一次真的写入或一次真的编译（见 `RebuildReport`
+ * 的注释）。**没有估算、没有占位** —— 面板与对话流是同一份诚实标准的两个出口。
+ */
+
+/** 工具调用分类：影响图标与语气。与平台的 `ToolCallKind` 同词表。 */
+type Kind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other'
+
+/**
+ * 一段 Markdown 内容块。
+ *
+ * 单独包一层是为了让 `present*View` 不必各自去构造平台的内容块形状 ——
+ * 那些字段（`type: 'text'`）一旦写错，界面会静默显示空白。
+ */
+function markdown(text: string): Array<{ type: 'text'; text: string }> {
+  return [{ type: 'text', text }]
+}
+
+/** 把数字与名字排成一行「摘要」。空数组返回空串，调用方据此跳过这一段。 */
+function facts(entries: Array<[string, string | number | undefined | null]>): string {
+  return entries
+    .filter(([, value]) => value !== undefined && value !== null && value !== '')
+    .map(([label, value]) => `${label} ${value}`)
+    .join(' · ')
+}
+
+/** 截断长标题：卡片标题要能排成一行，`title` 属性里仍给全文。 */
+function short(text: string, max = 48): string {
+  const flat = text.replace(/\s+/g, ' ').trim()
+  return flat.length > max ? `${flat.slice(0, max)}…` : flat
+}
+
+// ------------------------------------------------------------------ 批量导入
+
+export interface ImportMetaSource { sourceId: string; title?: string; bytes: number }
+export interface ImportMetaFailure { index: number; title?: string; code: string; message: string }
+export interface ImportMetaCompile {
+  cardsCreated: number; cardsUpdated: number; cardsReused?: number
+  notesReused?: number; notesRecompiled?: number
+  sourcesExtracted?: number; sourcesSkipped?: number; cardsRemoved?: number
+  embedding?: string; version?: number
+}
+export interface ImportMeta {
+  kind: 'import'
+  attempted: number
+  written: ImportMetaSource[]
+  failed: ImportMetaFailure[]
+  compile: ImportMetaCompile | null
+}
+
+/** `import_sources` 的账本。字段逐个点名，不用展开运算符 —— 形状是契约，要看得见。 */
+export function importMetaOf(value: {
+  attempted?: number
+  written?: Array<{ sourceId: string; title?: string; bytes?: number }>
+  failed?: ImportMetaFailure[]
+  compile?: ImportMetaCompile | null
+}): ImportMeta {
+  return {
+    kind: 'import',
+    attempted: value.attempted ?? (value.written?.length ?? 0) + (value.failed?.length ?? 0),
+    written: (value.written ?? []).map(item => ({
+      sourceId: item.sourceId,
+      ...(item.title ? { title: item.title } : {}),
+      bytes: item.bytes ?? 0,
+    })),
+    failed: (value.failed ?? []).map(item => ({
+      index: item.index,
+      ...(item.title ? { title: item.title } : {}),
+      code: item.code,
+      message: item.message,
+    })),
+    compile: value.compile ?? null,
+  }
+}
+
+/** 运行中的标题：**先说清楚这一下要动多少东西**。 */
+export function importCallView(args: { sources?: unknown[]; compile?: boolean }): { card: 'generic'; kind: Kind; title: string; rawInput?: unknown } {
+  const count = Array.isArray(args?.sources) ? args.sources.length : 0
+  const titles = (args?.sources ?? [])
+    .map(item => (item && typeof item === 'object' && typeof (item as { title?: unknown }).title === 'string' ? (item as { title: string }).title : ''))
+    .filter(Boolean)
+  return {
+    card: 'generic',
+    kind: 'edit',
+    title: `导入 ${count} 份来源${args?.compile === false ? '' : '并编译'}`,
+    rawInput: titles.length > 0 ? titles.map(title => short(title)) : { 份数: count },
+  }
+}
+
+/** 完成后的 Markdown：终端界面与「没有专用卡片」的界面都用它。 */
+export function importResultMarkdown(meta: ImportMeta): string {
+  const lines = [`**导入 ${meta.attempted} 份来源** —— 写入 ${meta.written.length} 份，失败 ${meta.failed.length} 份。`]
+  for (const item of meta.written) lines.push(`- ${item.title ? `**${short(item.title)}**` : item.sourceId} · ${item.bytes} 字符`)
+  for (const item of meta.failed) lines.push(`- 第 ${item.index + 1} 份${item.title ? `「${short(item.title)}」` : ''}失败：${item.code} ${item.message}`)
+  if (meta.compile) {
+    const { cardsCreated, cardsUpdated, cardsReused, notesReused, notesRecompiled, embedding, version } = meta.compile
+    lines.push('', `编译：新建 ${cardsCreated} 张、并入 ${cardsUpdated} 张、复用 ${cardsReused ?? 0} 张；wikiNotes 复用 ${notesReused ?? 0} 条、重编 ${notesRecompiled ?? 0} 条；索引 v${version ?? '?'}${embedding ? `（向量 ${embedding}）` : ''}。`)
+  } else {
+    lines.push('', '这次没有编译（`compile: false`）—— 卡片还没生成，需要时再调 `rebuild_knowledge`。')
+  }
+  return lines.join('\n')
+}
+
+// ------------------------------------------------------------------ 召回
+
+export interface RecallMetaHit {
+  entityId: string
+  entityType: string
+  title: string
+  score: number
+  rerankScore?: number
+  reviewScore?: number
+}
+export interface RecallMeta {
+  kind: 'recall'
+  query: string
+  backend: string
+  recallMode: string
+  recallTopK: number
+  contextTopN: number
+  /** 上下文里的卡片数：命中 N 张 + 1 跳扩展 M 张（0050）。 */
+  hitCards?: number
+  expandedCards?: number
+  /** 因为上下文预算没进去的卡片数（0050）。 */
+  omittedCards?: number
+  insufficientEvidence: boolean
+  rerankStatus: string
+  hits: RecallMetaHit[]
+  /** 路由名字，按这一轮真的跑过的顺序。 */
+  routes: string[]
+}
+
+/**
+ * `recall_knowledge` 的账本。
+ *
+ * `hits` 只带前 8 条：对话流里的卡片要能一眼看完，而完整的上下文包本来就在工具返回里
+ * 给模型了。**不改这个数**（不四舍五入、不归一），因为大小关系就是排序依据。
+ */
+export function recallMetaOf(value: {
+  hits?: Array<{ entityId?: string; entityType?: string; title?: string; score?: number; rerankScore?: number; reviewScore?: number }>
+  query?: string
+  backend?: string
+  recallMode?: string
+  recallTopK?: number
+  contextTopN?: number
+  /** 上下文预算的真实账（0050）：命中几张卡、扩展几张、几张超预算。 */
+  budget?: { hitCards?: number; expandedCards?: number; omittedCards?: number }
+  insufficientEvidence?: boolean
+  rerank?: { status?: string }
+  routes?: Array<{ route?: string; status?: string } | string>
+}): RecallMeta {
+  const hits = (value.hits ?? []).slice(0, 8).map(hit => ({
+    entityId: hit.entityId ?? '',
+    entityType: hit.entityType ?? '',
+    title: hit.title ?? hit.entityId ?? '',
+    score: typeof hit.score === 'number' ? hit.score : 0,
+    ...(typeof hit.rerankScore === 'number' ? { rerankScore: hit.rerankScore } : {}),
+    ...(typeof hit.reviewScore === 'number' ? { reviewScore: hit.reviewScore } : {}),
+  }))
+  return {
+    kind: 'recall',
+    query: value.query ?? '',
+    backend: value.backend ?? 'fts',
+    recallMode: value.recallMode ?? 'hybrid',
+    recallTopK: value.recallTopK ?? 0,
+    contextTopN: value.contextTopN ?? 0,
+    // 缺字段而不是 `undefined` 字段：这份账本要能原样进会话日志（`undefined` 会被
+    // 序列化检查拦下，见 0046）。
+    ...(value.budget?.hitCards === undefined ? {} : { hitCards: value.budget.hitCards }),
+    ...(value.budget?.expandedCards === undefined ? {} : { expandedCards: value.budget.expandedCards }),
+    ...(value.budget?.omittedCards === undefined ? {} : { omittedCards: value.budget.omittedCards }),
+    insufficientEvidence: value.insufficientEvidence === true,
+    rerankStatus: value.rerank?.status ?? 'skipped',
+    hits,
+    routes: (value.routes ?? []).map(route => (typeof route === 'string' ? route : route.route ?? '')).filter(Boolean),
+  }
+}
+
+export function recallCallView(args: { query?: string; mode?: string; top_k?: number }): { card: 'generic'; kind: Kind; title: string; rawInput?: unknown } {
+  const query = typeof args?.query === 'string' && args.query.trim() ? args.query.trim() : '(空查询)'
+  return {
+    card: 'generic',
+    kind: 'search',
+    title: `召回「${short(query, 40)}」`,
+    rawInput: { 模式: args?.mode ?? '默认', topK: args?.top_k ?? '默认' },
+  }
+}
+
+export function recallResultMarkdown(meta: RecallMeta): string {
+  if (meta.insufficientEvidence) {
+    return `**没有可回答这个问题的内容**（查询：「${short(meta.query, 40)}」）。库里没有一条越过相关性阈值 —— 这是结论，不是错误；把来源导进来再问。`
+  }
+  const head = facts([
+    ['命中', `${meta.hits.length} 条`],
+    ['进上下文', meta.hitCards === undefined
+      ? `${meta.contextTopN} 条`
+      : `${meta.hitCards} 张卡${meta.expandedCards ? ` + ${meta.expandedCards} 张扩展` : ''}${meta.omittedCards ? `（${meta.omittedCards} 张超预算，在溢出文件里）` : ''}`],
+    ['检索', meta.backend],
+    ['路由', meta.routes.join('+') || undefined],
+    ['重排', meta.rerankStatus],
+  ])
+  const lines = [`**召回「${short(meta.query, 40)}」** —— ${head}`]
+  for (const hit of meta.hits) {
+    const score = typeof hit.rerankScore === 'number' ? hit.rerankScore : hit.score
+    const review = hit.reviewScore !== undefined ? ` · 评分 ${hit.reviewScore.toFixed(2)}` : ''
+    lines.push(`- **${short(hit.title)}** \`${hit.entityType}:${hit.entityId}\` · ${score.toFixed(3)}${review}`)
+  }
+  return lines.join('\n')
+}
+
+// ------------------------------------------------------------------ 编译
+
+export interface RebuildMeta {
+  kind: 'rebuild'
+  only: string
+  version?: number
+  cardsCreated: number
+  cardsUpdated: number
+  cardsReused?: number
+  notesReused?: number
+  notesRecompiled?: number
+  sourcesExtracted?: number
+  sourcesSkipped?: number
+  cardsRemoved?: number
+  embedding?: string
+  skipped?: boolean
+}
+
+export function rebuildMetaOf(only: string, value: Partial<Omit<RebuildMeta, 'kind' | 'only'>>): RebuildMeta {
+  return {
+    kind: 'rebuild',
+    only,
+    cardsCreated: value.cardsCreated ?? 0,
+    cardsUpdated: value.cardsUpdated ?? 0,
+    ...(value.version !== undefined ? { version: value.version } : {}),
+    ...(value.cardsReused !== undefined ? { cardsReused: value.cardsReused } : {}),
+    ...(value.notesReused !== undefined ? { notesReused: value.notesReused } : {}),
+    ...(value.notesRecompiled !== undefined ? { notesRecompiled: value.notesRecompiled } : {}),
+    ...(value.sourcesExtracted !== undefined ? { sourcesExtracted: value.sourcesExtracted } : {}),
+    ...(value.sourcesSkipped !== undefined ? { sourcesSkipped: value.sourcesSkipped } : {}),
+    ...(value.cardsRemoved !== undefined ? { cardsRemoved: value.cardsRemoved } : {}),
+    ...(value.embedding !== undefined ? { embedding: value.embedding } : {}),
+    ...(value.skipped !== undefined ? { skipped: value.skipped } : {}),
+  }
+}
+
+export function rebuildCallView(args: { only?: string }): { card: 'generic'; kind: Kind; title: string } {
+  const only = args?.only ?? 'all'
+  const what = only === 'all' ? '全链路' : only === 'wiki' ? 'wiki 与 wikiNotes' : only === 'embeddings' ? '向量索引' : '注册表与 schema'
+  return { card: 'generic', kind: 'execute', title: `编译知识库 · ${what}` }
+}
+
+export function rebuildResultMarkdown(meta: RebuildMeta): string {
+  if (meta.skipped) return `**知识库没有变化** —— 复用了全部产物，没有生成新的索引版本（当前 v${meta.version ?? '?'}）。`
+  const head = facts([
+    ['新建卡片', meta.cardsCreated],
+    ['并入卡片', meta.cardsUpdated],
+    ['复用卡片', meta.cardsReused],
+    ['wikiNotes', `复用 ${meta.notesReused ?? 0} / 重编 ${meta.notesRecompiled ?? 0}`],
+    ['重抽来源', meta.sourcesExtracted],
+    ['跳过来源', meta.sourcesSkipped],
+    ['向量', meta.embedding],
+    ['索引', meta.version !== undefined ? `v${meta.version}` : undefined],
+  ])
+  return `**编译完成** —— ${head}。`
+}
+
+// ------------------------------------------------------------------ 单份来源 / 写卡
+
+export interface AddSourceMeta { kind: 'addSource'; sourceId: string; path: string; title?: string; sourceType: string; bytes: number }
+
+/**
+ * `value` 用偏松的类型：失败信封里的 `data` 是空壳（`{ sourceId: '', path: '' }`）。
+ * 呈现层宁可显示一个空 id，也不该在渲染时抛 —— 卡片渲染抛异常会把整条工具记录弄没。
+ */
+export function addSourceMetaOf(args: { source_type?: string; title?: string; content?: string }, value: { sourceId?: string; path?: string }): AddSourceMeta {
+  const content = typeof args?.content === 'string' ? args.content : ''
+  return {
+    kind: 'addSource',
+    sourceId: value?.sourceId ?? '',
+    path: value?.path ?? '',
+    sourceType: args?.source_type ?? 'document',
+    ...(args?.title ? { title: args.title } : {}),
+    bytes: content.length,
+  }
+}
+
+export function addSourceCallView(args: { source_type?: string; title?: string; content?: string }): { card: 'generic'; kind: Kind; title: string; rawInput?: unknown } {
+  const title = typeof args?.title === 'string' && args.title.trim() ? short(args.title) : '(未命名)'
+  return {
+    card: 'generic',
+    kind: 'edit',
+    title: `写入来源「${title}」`,
+    rawInput: { 分类: args?.source_type ?? 'document', 字符: typeof args?.content === 'string' ? args.content.length : 0 },
+  }
+}
+
+export function addSourceResultMarkdown(meta: AddSourceMeta): string {
+  return `**来源已写入** —— 「${meta.title ? short(meta.title) : meta.sourceId}」（分类 ${meta.sourceType}，${meta.bytes} 字符）。\n\n下一步：\`rebuild_knowledge\` 把它编译成 wiki 卡片。`
+}
+
+export interface WriteCardsMeta {
+  kind: 'writeCards'
+  sourceId: string
+  /**
+   * 落库的卡片 id。
+   *
+   * 字段名叫 `ids` 而不是 `written`：`import` 那份账本里 `written` 是**来源对象数组**
+   * （带标题与字符数），两个工具共用同一个 meta 类型时同名不同形状会让类型系统直接拒绝。
+   */
+  ids: string[]
+  rejected: Array<{ index?: number; title?: string; reason?: string; code?: string }>
+}
+
+export function writeCardsMetaOf(value: { written?: string[]; ids?: string[]; rejected?: unknown[] }, sourceId: string): WriteCardsMeta {
+  const rejected = (value.rejected ?? []).map(item => {
+    if (typeof item === 'string') return { reason: item }
+    const record = item && typeof item === 'object' ? item as Record<string, unknown> : {}
+    return {
+      ...(typeof record.index === 'number' ? { index: record.index } : {}),
+      ...(typeof record.title === 'string' ? { title: record.title } : {}),
+      ...(typeof record.reason === 'string' ? { reason: record.reason } : {}),
+      ...(typeof record.code === 'string' ? { code: record.code } : {}),
+    }
+  })
+  return { kind: 'writeCards', sourceId, ids: value.written ?? value.ids ?? [], rejected }
+}
+
+export function writeCardsCallView(args: { source_id?: string; proposals?: unknown[] }): { card: 'generic'; kind: Kind; title: string; rawInput?: unknown } {
+  const count = Array.isArray(args?.proposals) ? args.proposals.length : 0
+  const titles = (args?.proposals ?? [])
+    .map(item => (item && typeof item === 'object' && typeof (item as { title?: unknown }).title === 'string' ? (item as { title: string }).title : ''))
+    .filter(Boolean)
+  return {
+    card: 'generic',
+    kind: 'edit',
+    title: `写入 ${count} 张 wiki 卡片`,
+    rawInput: titles.length > 0 ? titles.map(title => short(title)) : { source_id: args?.source_id ?? '' },
+  }
+}
+
+export function writeCardsResultMarkdown(meta: WriteCardsMeta): string {
+  const head = facts([['写入', `${meta.ids.length} 张`], ['被拒', meta.rejected.length > 0 ? `${meta.rejected.length} 张` : undefined]])
+  const lines = [`**卡片已直接入库** —— ${head}（来源 \`${meta.sourceId}\`）。`, '', '正文只读；要补信息就加备注，要否掉就改状态。']
+  for (const id of meta.ids.slice(0, 12)) lines.push(`- \`${id}\``)
+  for (const item of meta.rejected) lines.push(`- 被拒${item.title ? `「${short(item.title)}」` : ''}：${item.reason ?? item.code ?? '原因未知'}`)
+  return lines.join('\n')
+}

package/src/recall-rank.ts

@@ -113,10 +113,21 @@ export function graphBoost(fused: FusedHit[], graphRanking: RouteRanking[], opti
  * 「弱命中」、挡不住「整批都弱」；向量路的分是原始余弦，是绝对的。两者都要如实
  * 写进诊断，不能让人以为「过了阈值」等于「相关」。
  */
-export function applyThreshold(ranking: RouteRanking[], threshold: number): { kept: RouteRanking[]; dropped: number; topScore: number } {
+export function applyThreshold(ranking: RouteRanking[], threshold: number): {
+  kept: RouteRanking[]
+  dropped: number
+  topScore: number
+  /** 阈值前后的**全部**候选（0050）：面板要显示「哪些被丢了、各自多少分」。 */
+  rows: Array<RouteRanking & { kept: boolean }>
+} {
   const topScore = ranking.length > 0 ? Math.max(...ranking.map(item => item.score)) : 0
   const kept = ranking.filter(item => item.score >= threshold)
-  return { kept, dropped: ranking.length - kept.length, topScore }
+  return {
+    kept,
+    dropped: ranking.length - kept.length,
+    topScore,
+    rows: ranking.map(item => ({ ...item, kept: item.score >= threshold })),
+  }
 }
 
 /**
@@ -255,6 +266,36 @@ export function matchOf(ranks: Partial<Record<RecallRoute, number>>): 'fts' | 'v
   return used[0] ?? 'fts'
 }
 
+/**
+ * review 评分对融合分的加权区间（0044）。
+ *
+ * **它是有界的小幅加权，不是准入闸门。** 三个数各有理由：
+ * - 下限 `0.85`：一张被标成异常点的卡片降到 0.85 倍，还是召回得到。评分不该等于删除，
+ *   否则「人点一下」与「删掉一条知识」变成同一个动作，而后者是不可逆的。
+ * - 上限 `1.2`：review 过的人认为对，但它不该压过「这条根本更相关」。相关性由 RRF 与
+ *   重排回答，评分只回答「同类命中里先看谁」。
+ * - 中性 `0.5` → 倍率 1.0。这样「没有评分」与「评分 0.5」行为一致，缺字段不需要特判。
+ */
+export const REVIEW_WEIGHT_MIN = 0.85
+export const REVIEW_WEIGHT_MAX = 1.2
+export const REVIEW_SCORE_NEUTRAL = 0.5
+
+/**
+ * 评分 → 融合分倍率。
+ *
+ * 纯函数，所以「review 一下到底能改多少排序」可以在 `node:test` 里被钉住 ——
+ * 这类加权最容易悄悄漂成「评分即一切」。
+ */
+export function reviewWeight(score: number | undefined): number {
+  // 缺字段（旧版本编译出来的 note）按中性处理：升级不该让老语料的排序突然变化。
+  if (score === undefined || !Number.isFinite(score)) return 1
+  const clamped = Math.min(1, Math.max(0, score))
+  if (clamped >= REVIEW_SCORE_NEUTRAL) {
+    return 1 + (REVIEW_WEIGHT_MAX - 1) * ((clamped - REVIEW_SCORE_NEUTRAL) / (1 - REVIEW_SCORE_NEUTRAL))
+  }
+  return 1 - (1 - REVIEW_WEIGHT_MIN) * ((REVIEW_SCORE_NEUTRAL - clamped) / REVIEW_SCORE_NEUTRAL)
+}
+
 /** 展示用的概率：`rerankScore` 是 logit 的 sigmoid。 */
 export function sigmoidLogit(logit: number): number {
   return 1 / (1 + Math.exp(-logit))
@@ -267,6 +308,14 @@ export interface RerankOutcome<T> {
   dropped: number
   /** 候选池里最高的 logit —— 跨查询可比的「这一批到底有多相关」。 */
   topLogit: number
+  /**
+   * **逐条**的打分（0050）。
+   *
+   * `kept` 只给活下来的那些，而面板要回答的是「哪些被丢了、丢在哪一步」——
+   * 少了这份账，界面上就只能显示「14 条候选、全部被丢弃」，人看不到那 14 条分别多少分。
+   * 顺序与入参一致（不是排序后的），因为「重排前后的名次变化」本身也是信息。
+   */
+  scored: Array<{ unitId: string; logit: number; rerankScore: number; kept: boolean }>
 }
 
 /**
@@ -295,5 +344,11 @@ export function applyRerank<T extends { unitId: string }>(scores: number[], item
       .sort((left, right) => right.rerankScore - left.rerankScore || left.unitId.localeCompare(right.unitId)),
     dropped: scored.length - kept.length,
     topLogit: scored.length > 0 ? Math.max(...scored.map(entry => entry.logit)) : 0,
+    scored: scored.map(entry => ({
+      unitId: entry.item.unitId,
+      logit: entry.logit,
+      rerankScore: sigmoidLogit(entry.logit),
+      kept: entry.logit >= threshold,
+    })),
   }
 }