dsh-data-domain-knowledge 0.1.0-alpha.1

package/src/directory-picker.ts

@@ -0,0 +1,164 @@
+/**
+ * 目录选择：把 DSH 宿主的 `ctx.directoryPicker` 接到 TitaAgent 控制台上（0029）。
+ *
+ * ## 为什么不让用户手输路径
+ *
+ * 路径是**磁盘事实**，不是用户脑子里的字符串。让人手打 `/Users/xxx/Desktop/…`
+ * 的结果是：拼错一个字符、`~` 没展开、复制粘贴带上了尾随空格 —— 而这一处的错误
+ * 代价特别大，它决定了整个 Agent 的东西存在哪。所以设置里那个「根路径」是一个
+ * **选择**动作，不是一个输入框。
+ *
+ * ## 为什么要适配两种交互
+ *
+ * 宿主把「怎么选目录」抽象成一个 capability，形状有两种：
+ *
+ * - `native`：在**宿主那台机器**上弹系统文件夹对话框，返回一个绝对路径。
+ *   浏览器和宿主在同一台机器上时这是最好的形态 —— 用户看到的是他熟悉的访达。
+ * - `browse`：宿主只提供「列一层 / 建子目录」两个原语，由调用方自己在页面里画
+ *   浏览界面。浏览器在远端（或宿主没有显示器）时这是唯一能用的形态。
+ *
+ * 两者**不能只挑一个**：本机部署走 native，远程访问走 browse，而这是启动时根据
+ * 绑定地址 / SSH / 显示器判定的（`dsh-host-directory-picker-auto`）。所以这里
+ * 如实把 kind 转给前端，由前端决定弹系统框还是画浏览框 —— 前端的默认写法是
+ * 「拿到 kind 再分叉」，而不是假设自己是哪一种。
+ *
+ * ## 为什么类型是结构化的
+ *
+ * `@deepseek-ai/dsh-host-directory-picker` 是 DSH 安装里的包，不是 npm 上可依赖的
+ * 版本，插件不能 import 它（会把 DSH 的内部路径焊进依赖图）。所以这里只声明我们
+ * 真正用到的那几个成员 —— 服务是按名字从 ctx 里取的，取不到就是没有，退化成
+ * 「宿主没提供目录选择器」这一条如实回答，而不是崩掉。
+ *
+ * @module
+ */
+
+/** 一层目录里的一行：一个子目录，或一个面包屑祖先。 */
+export interface DirectoryEntry {
+  /** 显示用的名字（根面包屑带的是完整路径）。 */
+  name: string
+  /** 宿主机上的绝对路径 —— 调用方永远不自己拼路径段。 */
+  path: string
+  /** 宿主平台约定的隐藏项（POSIX 上是点开头）。 */
+  hidden: boolean
+}
+
+/** 一层目录 + 它的祖先链。 */
+export interface DirectoryListing {
+  path: string
+  /** 宿主账号的 home，面包屑的「Home」锚点。 */
+  home: string
+  crumbs: DirectoryEntry[]
+  entries: DirectoryEntry[]
+  /** 后端把 entries 截断在它的完整结果上限上了。 */
+  truncated: boolean
+}
+
+/** 宿主的目录选择能力。两个原语都可能是 `undefined` —— 取决于 kind。 */
+export interface DirectoryPickerCapability {
+  kind: string
+  pick?(signal: AbortSignal): Promise<string | null>
+  list?(path?: string, signal?: AbortSignal): Promise<DirectoryListing>
+  createDirectory?(path: string, name: string): Promise<string>
+}
+
+/** `ctx.directoryPicker` 的结构化视图。 */
+export interface DirectoryPickerLike {
+  capability(): DirectoryPickerCapability
+}
+
+/** 目录选择失败的业务码。前端据此给出「怎么办」而不是一句「失败了」。 */
+export type PickerErrorCode =
+  | 'PICKER_UNAVAILABLE'
+  | 'PICK_CANCELLED'
+  | 'DIRECTORY_UNREADABLE'
+  | 'DIRECTORY_EXISTS'
+  | 'DIRECTORY_CREATE_FAILED'
+
+/** 带业务码的目录选择失败。 */
+export class PickerError extends Error {
+  readonly code: PickerErrorCode
+  constructor(code: PickerErrorCode, message: string) {
+    super(message)
+    this.code = code
+    this.name = 'PickerError'
+  }
+}
+
+/** 从 ctx 里按名字取目录选择服务。取不到返回 `undefined`（宿主没挂这个能力）。 */
+export function pickerOf(ctx: { get(name: string): unknown }): DirectoryPickerLike | undefined {
+  const service = ctx.get('directoryPicker') as DirectoryPickerLike | undefined
+  return service && typeof service.capability === 'function' ? service : undefined
+}
+
+/** 宿主当前提供的是哪种交互。取不到服务时返回 `null`。 */
+export function pickerKind(picker: DirectoryPickerLike | undefined): string | null {
+  if (!picker) return null
+  try {
+    return picker.capability()?.kind ?? null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 开一次选择。
+ *
+ * native 会**阻塞到用户给出答案**（关掉对话框也算答案：`path` 为 `null`），所以
+ * 调用方的 HTTP 请求会一直挂着 —— 这正是系统对话框的语义，不该用超时把它打断。
+ * browse 立刻返回，让前端去画浏览界面。
+ */
+export async function pickDirectory(
+  picker: DirectoryPickerLike | undefined,
+  signal: AbortSignal,
+): Promise<{ kind: 'native'; path: string | null } | { kind: 'browse' }> {
+  const capability = picker?.capability()
+  if (!capability) {
+    throw new PickerError('PICKER_UNAVAILABLE', '宿主没有提供目录选择器，无法打开文件夹对话框。')
+  }
+  if (capability.kind === 'native') {
+    if (typeof capability.pick !== 'function') {
+      throw new PickerError('PICKER_UNAVAILABLE', '宿主的目录选择器声明为 native，但没有提供 pick。')
+    }
+    return { kind: 'native', path: await capability.pick(signal) }
+  }
+  return { kind: 'browse' }
+}
+
+/** 列一层目录（browse 形态）。 */
+export async function listDirectory(
+  picker: DirectoryPickerLike | undefined,
+  path: string | undefined,
+  signal: AbortSignal,
+): Promise<DirectoryListing> {
+  const capability = picker?.capability()
+  if (!capability || capability.kind !== 'browse' || typeof capability.list !== 'function') {
+    throw new PickerError('PICKER_UNAVAILABLE', '宿主没有提供可浏览的目录列表。')
+  }
+  try {
+    return await capability.list(path, signal)
+  } catch (cause) {
+    throw new PickerError('DIRECTORY_UNREADABLE', cause instanceof Error ? cause.message : String(cause))
+  }
+}
+
+/** 在某个目录下建一个子目录（browse 形态）。 */
+export async function createDirectory(
+  picker: DirectoryPickerLike | undefined,
+  path: string,
+  name: string,
+): Promise<string> {
+  const capability = picker?.capability()
+  if (!capability || capability.kind !== 'browse' || typeof capability.createDirectory !== 'function') {
+    throw new PickerError('PICKER_UNAVAILABLE', '宿主没有提供新建目录的能力。')
+  }
+  const trimmed = name.trim()
+  if (!trimmed || trimmed.includes('/') || trimmed.includes('\\') || trimmed === '.' || trimmed === '..') {
+    throw new PickerError('DIRECTORY_CREATE_FAILED', '目录名不能为空、不能包含路径分隔符，也不能是 . 或 ..')
+  }
+  try {
+    return await capability.createDirectory(path, trimmed)
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause)
+    throw new PickerError(/exist/i.test(message) ? 'DIRECTORY_EXISTS' : 'DIRECTORY_CREATE_FAILED', message)
+  }
+}

package/src/extract-model.ts

@@ -0,0 +1,227 @@
+/**
+ * 模型驱动的候选抽取与**实体归并**（#3b）。
+ *
+ * ## 为什么需要这一步，而不是继续改规则
+ *
+ * Pass 0 的规则抽取用**小节标题**当实体身份（`candidateEntityId(candidate.name)`）。
+ * 于是同一件东西只要换个标题写法，就是两个实体。这不是理论问题，是实测出来的：
+ *
+ * - 年报里的小节叫「毛利率变动及其驱动因素」；
+ * - 口径手册里的小节叫「毛利率（口径补充）」；
+ * - 结果：`新建 2 / 并入 0`，两张互不相干的卡片，
+ *   而「实体已存在就追加正文」那条分支**永远不会触发**。
+ *
+ * 想去掉括号后缀、去掉「及其驱动因素」这类尾巴，是**语义判断**：`毛利率` 与
+ * `毛利率变动及其驱动因素` 是同一个东西，而 `应收账款周转天数` 与 `库存周转天数`
+ * 不是 —— 两者字面都带「周转天数」。阈值化的字符串规则在第二步上必然出错，
+ * 所以这件事必须交给模型。
+ *
+ * ## 这一层只问一个问题
+ *
+ * 它**不**让模型自由编造卡片，也不让它决定正文：正文永远是来源里的原文片段，
+ * 模型只回答两件它擅长、而规则做不好的事 ——
+ *
+ * 1. 「这份来源里有哪些**实体**」（规则只会按小节切，切出来的是标题不是实体）；
+ * 2. 「这个实体是不是已经在下表里了」（给出已有卡片的 `existing_id`）。
+ *
+ * 第 2 问是归并的关键：**判断权在模型，决定权在这里**。模型说「是同一个」，
+ * 我们就走追加；说「不是」，就新建。模型给出的 `existing_id` 必须能在已有卡片里
+ * 找到，找不到就退回新建 —— 不能让模型凭一个不存在的 id 把内容写丢。
+ *
+ * ## 为什么要注入 `call`
+ *
+ * 模型调用是这一层唯一的非纯部分。把它作为参数注入，这个模块就能在没有模型的环境里
+ * 被完整测试（见 `tests/extract-model.test.mjs`）——否则「归并对不对」这件事只能靠
+ * 真跑一次模型来验，而那是不可重复的。
+ *
+ * @module
+ */
+
+import { candidateEntityId, type ExtractionCandidate } from './extract.js'
+import type { KnowledgeCard, SchemaType, SourceRaw, WikiTypeDef } from './types.js'
+
+/** 一次纯文本模型调用：给出 system 与 prompt，拿回模型的原始文本。 */
+export type ModelCall = (request: { system: string; prompt: string }) => Promise<string>
+
+/** 归并条目：与规则抽取的 `NormalizedCandidates['merges']` 保持同一形状。 */
+export interface ModelMerge {
+  key: string
+  entityId: string
+  entityType: SchemaType
+  sourceId: string
+  body: string
+}
+
+export interface ModelExtractionResult {
+  /** 判定为「wiki 里还没有」的实体 → 新建卡片。 */
+  fresh: ExtractionCandidate[]
+  /** 判定为「wiki 里已经有了」的实体 → 正文追加进那张卡。 */
+  merges: ModelMerge[]
+  warnings: string[]
+}
+
+export interface ModelExtractionInput {
+  source: SourceRaw
+  /** 已启用的 wiki 类型：模型只能从这些 id 里选。 */
+  wikiTypes: WikiTypeDef[]
+  /** 当前库里的卡片：既是「已存在」的候选集，也是给模型的上下文。 */
+  existing: KnowledgeCard[]
+  call: ModelCall
+}
+
+/** 单个实体最多给模型的正文长度：够判断语义，又不至于把上下文撑爆。 */
+const BODY_LIMIT = 1200
+
+/**
+ * 系统提示。**刻意写死在这里**而不是做成设置项：它不是用户的偏好，是这个模块与模型
+ * 之间的接口契约（输出必须是一段可解析的 JSON）。允许用户改它，等于允许用户把这个
+ * 解析器改坏。
+ */
+const SYSTEM = [
+  'You extract wiki entities from a business document and decide which of them already exist.',
+  'Answer with a single JSON object and nothing else. No prose, no code fence.',
+  'Shape: {"entities":[{"name":string,"type":string,"summary":string,"body":string,"existing_id":string|null}]}',
+  'Rules:',
+  '- "name" is the entity name as a business person would say it (e.g. 毛利率). Not a section heading.',
+  '- "type" MUST be one of the allowed type ids given in the prompt.',
+  '- "body" must be verbatim text from the document that backs this entity. Never invent facts.',
+  '- "existing_id" is the entityId of the existing card this entity is the SAME thing as, or null.',
+  '  Same thing means the same business concept; a narrower or different concept is NOT the same.',
+  '- Prefer few, real entities over many headings.',
+].join('\n')
+
+/** 从一串可能带 ``` 围栏的文本里取出 JSON 对象并解析。 */
+function parseJsonObject(raw: string): unknown {
+  const trimmed = raw.trim()
+  const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/)
+  const body = (fenced ? fenced[1] : trimmed).trim()
+  try {
+    return JSON.parse(body)
+  } catch {
+    // 模型有时会在 JSON 前后带一句解释：退一步，取第一个 `{` 到最后一个 `}`。
+    const start = body.indexOf('{')
+    const end = body.lastIndexOf('}')
+    if (start < 0 || end <= start) return undefined
+    try {
+      return JSON.parse(body.slice(start, end + 1))
+    } catch {
+      return undefined
+    }
+  }
+}
+
+/** 把模型的回答收敛成「合法实体数组」；任何不合法的一条都丢掉并记一条 warning。 */
+function readEntities(raw: unknown, allowedTypes: Set<string>, warnings: string[]): Array<Record<string, unknown>> {
+  if (raw === null || typeof raw !== 'object') {
+    warnings.push('模型输出不是 JSON 对象，本次抽取按空处理')
+    return []
+  }
+  const list = (raw as { entities?: unknown }).entities
+  if (!Array.isArray(list)) {
+    warnings.push('模型输出里没有 entities 数组，本次抽取按空处理')
+    return []
+  }
+  const kept: Array<Record<string, unknown>> = []
+  for (const item of list) {
+    if (item === null || typeof item !== 'object') continue
+    const record = item as Record<string, unknown>
+    const name = typeof record.name === 'string' ? record.name.trim() : ''
+    const type = typeof record.type === 'string' ? record.type.trim() : ''
+    const body = typeof record.body === 'string' ? record.body.trim() : ''
+    if (!name) continue
+    if (!allowedTypes.has(type)) {
+      warnings.push(`模型给出的类型「${type}」不在已启用类型里，候选「${name}」被丢掉`)
+      continue
+    }
+    if (!body) {
+      warnings.push(`候选「${name}」没有正文，被丢掉（卡片不能没有正文）`)
+      continue
+    }
+    kept.push({ ...record, name, type, body })
+  }
+  return kept
+}
+
+/**
+ * 用模型抽取实体，并把它们判归到「新建」或「追加到已有卡片」两条路上。
+ *
+ * 失败一律降级而不抛出：模型不可用时返回空结果 + 一条 warning，让上层继续跑规则抽取。
+ * 「因为模型挂了所以整次编译失败」是不能接受的 —— 那条链路本来就不依赖模型。
+ */
+export async function extractWithModel(input: ModelExtractionInput): Promise<ModelExtractionResult> {
+  const { source, wikiTypes, existing, call } = input
+  const warnings: string[] = []
+  const enabled = wikiTypes.filter(def => def.enabled)
+  const allowedTypes = new Set(enabled.map(def => String(def.id)))
+
+  const catalog = existing
+    .slice(0, 200)
+    .map(card => `- ${card.entityId} :: ${card.title}（${card.entityType}）`)
+    .join('\n')
+  const types = enabled
+    .map(def => `- ${def.id} :: ${def.label}${def.description ? ` — ${def.description}` : ''}`)
+    .join('\n')
+
+  const prompt = [
+    '# Allowed wiki type ids',
+    types || '（没有任何已启用类型）',
+    '',
+    '# Existing wiki cards (entityId :: title)',
+    catalog || '（这个库还是空的）',
+    '',
+    '# Document',
+    `title: ${source.title}`,
+    `source_id: ${source.sourceId}`,
+    '',
+    source.content.slice(0, BODY_LIMIT * 8),
+  ].join('\n')
+
+  let raw: string
+  try {
+    raw = await call({ system: SYSTEM, prompt })
+  } catch (cause) {
+    warnings.push(`模型抽取不可用：${cause instanceof Error ? cause.message : String(cause)}`)
+    return { fresh: [], merges: [], warnings }
+  }
+
+  const byId = new Map(existing.map(card => [`${card.entityType}:${card.entityId}`, card]))
+  const byEntityId = new Map(existing.map(card => [card.entityId, card]))
+  const fresh: ExtractionCandidate[] = []
+  const merges: ModelMerge[] = []
+  const claimed = new Set<string>()
+
+  for (const entity of readEntities(parseJsonObject(raw), allowedTypes, warnings)) {
+    const name = String(entity.name)
+    const type = String(entity.type) as SchemaType
+    const body = String(entity.body).slice(0, BODY_LIMIT)
+    const wantedId = typeof entity.existing_id === 'string' ? entity.existing_id.trim() : ''
+    // 模型给的 id 必须真的存在：它指着不存在的卡片时退回新建，绝不能让正文丢在空中。
+    const target = (wantedId ? byEntityId.get(wantedId) : undefined) ?? byId.get(`${type}:${name}`)
+
+    if (target) {
+      const key = `${target.entityType}:${target.entityId}`
+      // 同一张卡在一次抽取里被多个候选指向时只并一次，正文在这里先合起来。
+      const already = merges.find(entry => entry.key === key)
+      if (already) already.body = `${already.body}\n\n${body}`
+      else merges.push({ key, entityId: target.entityId, entityType: target.entityType, sourceId: source.sourceId, body })
+      claimed.add(key)
+      continue
+    }
+
+    const entityId = candidateEntityId(name)
+    const key = `${type}:${entityId}`
+    if (claimed.has(key)) continue
+    claimed.add(key)
+    fresh.push({
+      kind: 'entity',
+      name,
+      type,
+      body,
+      aliases: [],
+      evidence: { sourceId: source.sourceId },
+      confidence: 0.7,
+    })
+  }
+
+  return { fresh, merges, warnings }
+}