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

package/scripts/e2e-pipeline.mjs

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+/**
+ * SourceRaw → 编译 → 构建 → 召回 → 重排 的端到端实跑（0029）。
+ *
+ * ## 为什么要一个可重跑的脚本
+ *
+ * 这条链路跨五个阶段、三个存储层和两个进程外模型（WeMM 嵌入、BERT 重排），而单元
+ * 测试每一段都用替身把邻居挡掉了 —— 于是「每一段都对、连起来不对」这类问题只会在
+ * 真跑一次时才露出来。这个脚本就是把那条链路**按真实顺序跑一遍**，并把它每一步的
+ * 真实数字打出来，好让「哪里不对」是一个可读的结论而不是一句「好像有问题」。
+ *
+ * ## 两条纪律
+ *
+ * 1. **只跑副本。** 默认把 `--from` 指向的语料**复制**进一个临时 agent root 再跑，
+ *    所以它不会碰任何真实知识树（版本号、编译产物、记忆快照都不会被动）。
+ * 2. **失败不中断。** 每个阶段单独 try/catch，失败记下来继续跑后面的 —— 链路排查
+ *    最怕的是第一步就抛，于是看不到后面还有没有别的问题。
+ *
+ * 用法：
+ *   node scripts/e2e-pipeline.mjs                        # 用内置夹具
+ *   node scripts/e2e-pipeline.mjs --from ~/domain_knowledge   # 用真实语料的副本
+ *   node scripts/e2e-pipeline.mjs --root /tmp/x --keep    # 指定 root 且跑完不删
+ *   node scripts/e2e-pipeline.mjs --no-models             # 跳过嵌入/重排（快，只看文本链路）
+ */
+import { cp, mkdir, mkdtemp, readdir, rm, stat } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { KnowledgeRuntime } from '../lib/types/runtime.js'
+
+const args = process.argv.slice(2)
+const flag = name => args.includes(name)
+const value = (name, fallback) => {
+  const index = args.indexOf(name)
+  return index >= 0 && args[index + 1] ? args[index + 1] : fallback
+}
+
+const from = value('--from', null)
+const keep = flag('--keep')
+const noModels = flag('--no-models')
+const explicitRoot = value('--root', null)
+
+const pluginRoot = resolve(fileURLToPath(new URL('.', import.meta.url)), '..')
+
+/** 内置夹具：三种来源形态，覆盖「直写」「转换而来」「同一文档的第二个版本」。 */
+const FILLER = '补充说明：这一节的结论来自当期对账口径复核，与财务确认后生效，口径变更需要同时通知数据与财务两侧，并在下一次月结前完成回归验证。'
+const FIXTURES = [
+  {
+    // 经转换内核进来的形态：`source_path` 让扩展名推导拿到真实扩展名，
+    // `parser` 是内核写下的真值。
+    sourceType: 'document',
+    title: 'GMV 口径说明',
+    externalId: 'doc:gmv-metric',
+    content: `# GMV 口径说明\n\nGMV 指成交总额，含未支付订单。它与营收的差别在于退款与取消是否从总额里扣减，对账时必须先说清用的是哪一个。\n\n${FILLER}\n\n## 计算方式\n\nGMV 等于订单金额之和，按**下单时间**归集，不按支付时间。跨月订单算在下单月，这是它与营收最容易对不上的地方。\n\n${FILLER}\n\n## 与营收的区别\n\n营收扣减退款与取消，GMV 不扣。两者对账时必然不等，差额就是当期退款总额，这也就是退款表的核对入口。\n\n${FILLER}\n`,
+    metadata: { source_path: '/incoming/GMV口径说明.pdf', parser: 'anydoc@1/pdf' },
+  },
+  {
+    // 直写进来的形态：没有 parser，扩展名靠 source_format 推。
+    sourceType: 'document',
+    title: '退款处理流程',
+    externalId: 'doc:refund-flow',
+    content: `# 退款处理流程\n\n退款分三步：申请、审核、打款。审核超过 48 小时未处理会自动升级到主管，避免卡在单个人身上。\n\n${FILLER}\n\n## 打款失败怎么办\n\n打款失败会退回待处理状态，并在 [[GMV 口径说明]] 里那条差额上体现出来，所以对账前要先看退款表。\n\n${FILLER}\n`,
+    metadata: { source_format: 'markdown' },
+  },
+  {
+    // 什么都没有的形态：扩展名回退成 .md。
+    sourceType: 'document',
+    title: '数据表清单',
+    externalId: 'doc:tables',
+    content: `# 数据表清单\n\ndwd_order 是订单明细表，一行一个订单。dwd_refund 是退款表，一行一次退款，两表用 order_id 关联。\n\n${FILLER}\n\n## 关联关系\n\ndwd_refund.order_id 关联 dwd_order.order_id。GMV 与退款额的差额在 [[GMV 口径说明]] 里有定义，不要各算各的。\n\n${FILLER}\n`,
+    metadata: {},
+  },
+]
+
+function hr(title) {
+  console.log(`\n${'─'.repeat(4)} ${title} ${'─'.repeat(Math.max(0, 62 - title.length))}`)
+}
+
+function show(label, value) {
+  console.log(`  ${label.padEnd(28)} ${value}`)
+}
+
+/** 把一个可能很长的错误压成一行，免得把报告淹掉。 */
+function short(error) {
+  const text = error instanceof Error ? `${error.name}: ${error.message}` : String(error)
+  return text.length > 300 ? `${text.slice(0, 300)}…` : text
+}
+
+async function main() {
+  const root = explicitRoot ? resolve(explicitRoot) : await mkdtemp(join(tmpdir(), 'tita-e2e-'))
+  await mkdir(root, { recursive: true })
+  const knowledgeRoot = join(root, 'domain_knowledge', 'default')
+  console.log(`agent root  ${root}`)
+  console.log(`知识库根    ${knowledgeRoot}`)
+
+  const problems = []
+  const note = (stage, message) => { problems.push({ stage, message }); console.log(`  ⚠ ${stage}: ${message}`) }
+
+  // ---------------------------------------------------------------- 0. 语料
+  hr('0. 语料')
+  let corpusSource = '内置夹具'
+  if (from) {
+    const source = resolve(from.replace(/^~/, process.env.HOME ?? '~'))
+    if (!existsSync(source)) throw new Error(`--from 指向的语料不存在：${source}`)
+    /*
+     * `--from` 可以给**知识库目录**（里面有 01_source_truth 等段），也可以给它自然的
+     * 父目录（`domain_knowledge/`）。父目录是最顺手的写法，但直接 `cp` 会把它当成目标
+     * 本身，于是真正的 `default/` 被多套一层 —— 运行时读到 0 份文档，然后后面每个阶段
+     * 都报一串**看起来很确定**的假问题（第一次跑就是这么得到 17 条）。
+     *
+     * 诊断工具说谎比没有诊断更糟，所以这里认出来并自己降级；认不出就明确报错，而不是
+     * 让下游去猜。
+     */
+    const segmentPattern = /^\d{2}_[a-z_]+$/
+    const looksLikeKb = async dir => (await readdir(dir).catch(() => [])).some(entry => segmentPattern.test(entry))
+    let corpus = source
+    if (!(await looksLikeKb(source))) {
+      const children = (await readdir(source, { withFileTypes: true }).catch(() => []))
+        .filter(entry => entry.isDirectory())
+        .map(entry => join(source, entry.name))
+      const candidates = []
+      for (const child of children) if (await looksLikeKb(child)) candidates.push(child)
+      if (candidates.length === 1) {
+        corpus = candidates[0]
+        show('语料修正', `--from 给的是父目录，实际使用 ${corpus}`)
+      } else if (candidates.length === 0) {
+        throw new Error(`--from 指向的目录里找不到知识库段（01_source_truth 等）：${source}`)
+      } else {
+        throw new Error(`--from 指向的目录下有多个知识库，请直接指定其中一个：\n  ${candidates.join('\n  ')}`)
+      }
+    }
+    await cp(corpus, knowledgeRoot, { recursive: true })
+    corpusSource = `${corpus}（副本）`
+    const entries = await readdir(knowledgeRoot).catch(() => [])
+    show('来源', corpusSource)
+    show('搬进来的段', entries.filter(entry => entry !== '.DS_Store').join(' '))
+  } else {
+    show('来源', corpusSource)
+  }
+
+  /*
+   * 家当（`resource/`：Python 环境 + 本地模型）**不在这次副本里** —— 只复制了知识树。
+   * 于是模型腿会以「No module named 'torch'」这类形式报不可用，而那是**环境缺失**，
+   * 不是链路坏了（真实 agent root 里模型是好的）。这两件事在报告里必须分得开，否则
+   * 每次跑都会得到一串听起来很严重的假警报。
+   */
+  const envHint = from
+    ? `副本只含知识树，不含家当（resource/）。模型腿若报 No module named …，那是这次副本没有模型环境，不代表真实库不可用；真实库请用 /knowledge/stats 核对。`
+    : null
+
+  const config = {
+    // 0029 的默认值：抽取开着（它就是「SourceRaw → Wiki」唯一不依赖模型的一步）。
+    extractCandidates: true,
+    // `--no-models` 时把两条模型腿关掉：文本链路照样能跑，且报告会如实说它们没跑。
+    embeddingProvider: noModels ? 'none' : 'wemm-python',
+    rerankProvider: noModels ? 'none' : 'bert-python',
+    recallTopK: 10,
+    recallMode: 'hybrid',
+    contextTopN: 5,
+  }
+  const runtime = new KnowledgeRuntime(knowledgeRoot, config)
+  const t0 = Date.now()
+
+  try {
+    // ------------------------------------------------------------ 1. SourceRaw
+    hr('1. SourceRaw 收录')
+    if (!from) {
+      for (const fixture of FIXTURES) {
+        const result = await runtime.addSource(fixture)
+        const status = result.ok ? 'ok' : `失败 ${result.error?.code}`
+        show(fixture.externalId, status)
+        if (!result.ok) note('SourceRaw', `${fixture.externalId} 写入失败：${result.error?.code} ${result.error?.message}`)
+      }
+      // 幂等：同一个 externalId 再写一次应该是「更新」，不是新增。
+      const again = await runtime.addSource({ ...FIXTURES[0], content: `${FIXTURES[0].content}\n\n## 补充\n\n口径每年复核一次。\n` })
+      show('同 externalId 重写', again.ok ? `ok（版本 +1）` : `失败 ${again.error?.code}`)
+      if (!again.ok) note('SourceRaw', '同 externalId 重写失败：幂等契约不成立')
+    }
+
+    let documents = await runtime.listDocuments()
+    show('文档数', documents.length)
+    const withExt = documents.filter(document => document.ext && document.ext !== '.md').length
+    show('非 .md 扩展名', `${withExt} / ${documents.length}（靠 metadata.source_path 推导）`)
+    const parsers = [...new Set(documents.map(document => document.parser))]
+    show('parser 取值', parsers.join(' ') || '（无）')
+    show('扩展名分布', Object.entries(documents.reduce((acc, d) => ({ ...acc, [d.ext]: (acc[d.ext] ?? 0) + 1 }), {})).map(([k, v]) => `${k}:${v}`).join(' '))
+    const versions = documents.reduce((sum, document) => sum + (document.versionCount ?? 0), 0)
+    show('版本快照总数', versions)
+    if (documents.length === 0) note('SourceRaw', '一份文档都没有 —— 后面的阶段都会是空的')
+
+    // ------------------------------------------------------------ 2. 编译（Pass 0 + 落卡）
+    hr('2. 编译：Pass 0 抽取 + 归一 + 落卡')
+    const wiki = await runtime.rebuild('wiki')
+    if (!wiki.ok) {
+      note('编译', `rebuild('wiki') 失败：${wiki.error?.code} ${wiki.error?.message}`)
+    } else {
+      const report = wiki.data
+      show('卡片', `${report.cards}（新增 ${report.cardsAdded ?? 0} / 复用 ${report.cardsReused ?? 0} / 重编 ${report.cardsRecompiled ?? 0}）`)
+      show('wikiNotes', report.notes)
+      show('版本', `v${report.version}`)
+      // 八个 Pass 0 计数**直接在 report 上**（`lastBuild` 是 build-manifest.json 的
+      // 形状，不是 RebuildReport 的字段 —— 这里第一次就写错了，读出来全是 0）。
+      show('抽取候选', `${report.candidatesExtracted ?? 0} 抽出 / ${report.candidatesRejected ?? 0} 拒绝`)
+      show('归一结果', `${report.cardsMerged ?? 0} 合并进已有卡片 / ${report.cardsCreated ?? 0} 新建`)
+      show('抽出的关系', `${report.relationsExtracted ?? 0} 条，丢掉 ${report.relationsDropped ?? 0} 条`)
+      show('来源层', `${report.sourcesExtracted ?? 0} 篇参与 / ${report.sourcesSkipped ?? 0} 篇跳过`)
+      if ((report.candidatesExtracted ?? 0) === 0 && (report.sourcesExtracted ?? 0) > 0) {
+        const shortest = Math.min(...documents.map(document => document.content?.length ?? 0))
+        note('编译', `Pass 0 参与了 ${report.sourcesExtracted} 篇来源却一个候选都没抽出来。报告只说「0 抽出 / 0 拒绝」，不区分「小节都短于阈值」与「抽取坏了」—— 这是一处报告缺口（本批最短文档 ${shortest} 字）`)
+      }
+      if ((report.relationsDropped ?? 0) > 0) note('编译', `有 ${report.relationsDropped} 条关系被丢掉：两端没同时存在（[[链接]] 指向了还没落卡的实体）`)
+      if ((report.cardsCreated ?? 0) > 0 && report.cardsAdded !== report.cardsCreated) {
+        show('计数自洽性', `cardsAdded=${report.cardsAdded} 与 cardsCreated=${report.cardsCreated} 不等（前者是 stage 2 的「新指纹」，后者是 Pass 0 的「新建卡片」）`)
+      }
+    }
+
+    const cards = await runtime.loadCards()
+    show('卡片类型分布', Object.entries(cards.reduce((acc, card) => ({ ...acc, [card.entityType]: (acc[card.entityType] ?? 0) + 1 }), {})).map(([k, v]) => `${k}:${v}`).join(' ') || '（无）')
+    const noRefs = cards.filter(card => !card.sourceRefs || card.sourceRefs.length === 0)
+    if (noRefs.length > 0) note('编译', `${noRefs.length} 张卡片没有 source_refs —— 它们无法追溯回原文`)
+    // 引用必须真的指向存在的文档。
+    const knownIds = new Set(documents.map(document => document.docId))
+    for (const card of cards) {
+      const dangling = (card.sourceRefs ?? []).filter(ref => !knownIds.has(ref))
+      if (dangling.length > 0) note('编译', `卡片 ${card.entityId} 的 source_refs 指向不存在的文档：${dangling.join(' ')}`)
+    }
+
+    // 增量：语料没变时重跑应该是空操作。
+    const wikiAgain = await runtime.rebuild('wiki')
+    if (wikiAgain.ok) {
+      const report = wikiAgain.data
+      show('原地重跑', `${report.skipped ? 'skipped' : '没有跳过'} · 复用 ${report.cardsReused ?? 0} / 重编 ${report.cardsRecompiled ?? 0} / notes 复用 ${report.notesReused ?? 0}`)
+      if (!report.skipped && (report.cardsReused ?? 0) === 0 && report.cards > 0) {
+        note('编译', `语料没变，${report.cards} 张卡片却一张都没复用（reused=0、recompiled=${report.cardsRecompiled ?? 0}）—— 增量指纹没生效`)
+      }
+    } else {
+      note('编译', `第二次 rebuild('wiki') 失败：${wikiAgain.error?.code}`)
+    }
+
+    // ------------------------------------------------------------ 3. 构建（向量 + 图）
+    hr('3. 构建：wikiNotes + 向量索引 + 知识图谱')
+    const build = await runtime.rebuild('all')
+    if (!build.ok) {
+      note('构建', `rebuild('all') 失败：${build.error?.code} ${build.error?.message}`)
+    } else {
+      const report = build.data
+      show('卡片 / notes', `${report.cards} / ${report.notes}`)
+      show('图节点 / 边', `${report.graphNodes} / ${report.graphEdges}`)
+      show('嵌入', `${report.embedding}${report.embeddingItems === undefined ? '' : ` · ${report.embeddingItems} 条`}${report.embeddingReused === undefined ? '' : ` · 复用 ${report.embeddingReused}`}${report.embeddingDimension ? ` · ${report.embeddingDimension} 维` : ''}`)
+      if (report.embeddingError) note('构建', `嵌入不可用：${report.embeddingError}`)
+      if (report.embedding === 'unavailable') note('构建', '向量腿没起来 —— 召回会退化成关键词 + 图')
+      if (report.graphEdges === 0) note('构建', '图一条边都没有：溯源边 supported_by 应该至少等于「卡片引用了几篇文档」')
+    }
+
+    const graph = await runtime.graphQuery('types')
+    if (graph.ok) show('图上的关系类型', (graph.data.relationTypes ?? []).join(' ') || '（无）')
+    const listed = await runtime.graphQuery('list', undefined, undefined, 1, { limit: 50 })
+    if (listed.ok) {
+      const nodes = listed.data.nodes ?? []
+      const edges = listed.data.edges ?? []
+      const byType = nodes.reduce((acc, node) => ({ ...acc, [node.type ?? '?']: (acc[node.type ?? '?'] ?? 0) + 1 }), {})
+      show('图节点类型分布', Object.entries(byType).map(([k, v]) => `${k}:${v}`).join(' ') || '（无）')
+      // 图节点的键是 `${type}:${id}`，没有现成的 degree —— 自己按边算。
+      const touched = new Set()
+      for (const edge of edges) { touched.add(String(edge.from)); touched.add(String(edge.to)) }
+      const orphan = nodes.filter(node => !touched.has(`${node.type}:${node.id}`))
+      show('被边连上的节点', `${nodes.length - orphan.length} / ${nodes.length}`)
+      if (orphan.length > 0) show('孤立节点', orphan.map(node => `${node.type}:${node.id}`).slice(0, 6).join(' ') + (orphan.length > 6 ? ` …共 ${orphan.length} 个` : ''))
+      const byEdge = edges.reduce((acc, edge) => ({ ...acc, [edge.type ?? '?']: (acc[edge.type ?? '?'] ?? 0) + 1 }), {})
+      show('边类型分布', Object.entries(byEdge).map(([k, v]) => `${k}:${v}`).join(' ') || '（无）')
+    } else {
+      note('构建', `graphQuery('list') 失败：${listed.error?.code}`)
+    }
+
+    // ------------------------------------------------------------ 4. 召回
+    hr('4. 召回：三路 + 融合')
+    const health = await runtime.embeddingHealth()
+    if (health.ok) {
+      const index = health.data.vectorIndex ?? {}
+      show('嵌入后端', `${health.data.provider} · 索引 ${index.ready ? 'ready' : 'not-ready'} · ${index.itemCount ?? 0} 条 · ${health.data.dimension ?? '?'} 维`)
+      if (health.data.lastError) show('嵌入上次错误', String(health.data.lastError).slice(0, 160))
+      if (!index.ready) note('召回', `向量索引没就绪（${index.itemCount ?? 0} 条）—— vector 路会退化成关键词路`)
+    } else {
+      note('召回', `embeddingHealth 失败：${health.error?.code}`)
+    }
+
+    const queries = ['GMV 怎么算', '退款审核超时怎么办', 'dwd_refund 关联哪张表', '知识库里有没有讲过营收']
+    for (const mode of ['fts', 'vector', 'graph', 'hybrid']) {
+      for (const query of queries.slice(0, 2)) {
+        const result = await runtime.recall(query, 10, [], false, mode)
+        if (!result.ok) { note('召回', `${mode} / 「${query}」失败：${result.error?.code} ${result.error?.message}`); continue }
+        const data = result.data
+        const routes = (data.routes ?? []).join('+') || '（无）'
+        show(`${mode} · ${query}`, `${(data.hits ?? []).length} 命中 · top=${data.hits?.[0]?.score?.toFixed?.(3) ?? '—'} · 实际走 ${routes} · backend ${data.backend}`)
+        if ((data.hits ?? []).length === 0) note('召回', `${mode} 对「${query}」零命中`)
+        // 请求的路由与实际走的路由不一致时必须说清 —— 这是「我说了算」与「它实际怎么跑」的差别。
+        if (mode === 'vector' && !(data.routes ?? []).includes('vector')) note('召回', `请求 mode=vector，实际只走了 ${routes}：向量腿不可用时会静默退化成关键词路`)
+        if (mode === 'graph' && !(data.routes ?? []).includes('graph')) note('召回', `请求 mode=graph，实际只走了 ${routes}`)
+      }
+    }
+
+    // ------------------------------------------------------------ 5. 重排
+    hr('5. 重排：BERT cross-encoder → 上下文包')
+    const reranked = await runtime.recall('GMV 口径与营收的差别', 10, [], false, 'hybrid', undefined, { contextTopN: 5, rerank: true })
+    if (!reranked.ok) {
+      note('重排', `带 rerank 的召回失败：${reranked.error?.code} ${reranked.error?.message}`)
+    } else {
+      const data = reranked.data
+      show('重排', `${data.rerank?.status} · ${data.rerank?.provider}${data.rerank?.model ? ` · ${data.rerank.model}` : ''}${data.rerank?.scored === undefined ? '' : ` · 打分了 ${data.rerank.scored} 条`}`)
+      show('进入上下文的条数', (data.context ?? []).length)
+      show('命中数', (data.hits ?? []).length)
+      if (data.rerank?.status === 'unavailable') note('重排', `精排不可用：${data.rerank.error ?? '未说明原因'} —— 顺序按融合分数，不是 cross-encoder 的分数`)
+      if (data.rerank?.status === 'skipped') show('重排跳过原因', (data.hits ?? []).length < 2 ? '命中不足 2 条，没有可排的东西' : 'provider 配成了 none')
+      if ((data.context ?? []).length === 0) note('重排', '上下文包是空的：模型这一轮拿不到任何知识')
+      const first = data.context?.[0]
+      if (first) {
+        const text = first.note?.content ?? ''
+        show('上下文首条', `${first.note?.entityType ?? '?'}:${first.note?.entityId ?? '?'}「${first.note?.title ?? '?'}」（正文 ${text.length} 字）`)
+        if (text.length === 0) note('重排', '上下文首条的正文是空的 —— 模型拿到的是一条没有内容的「知识」')
+        if (!first.wiki) note('重排', `上下文首条没有解出 wiki 卡片（note 指向 ${first.note?.entityId}）—— 卡片可能在编译后被删了`)
+      }
+    }
+
+    // ------------------------------------------------------------ 6. 统计
+    hr('6. 落盘事实（/knowledge/stats 的来源）')
+    // `stats()` 直接返回统计对象（不是 Envelope）—— 别按 ok 判。
+    const data = await runtime.stats()
+    show('来源 / 卡片 / notes', `${data.sourceCount} / ${data.cards ?? '?'} / ${data.notes ?? '?'}`)
+    show('版本', `v${data.buildVersion}`)
+    show('各段文件数', Object.entries(data.layout ?? {}).map(([k, v]) => `${k}:${v}`).join(' '))
+    show('卡片版本文件数', data.cardVersions ?? '?')
+    if (data.notes === 0) note('统计', 'notes 为 0：召回没有可检索的单元')
+
+    hr('结论')
+    console.log(`  语料来源    ${corpusSource}`)
+    console.log(`  耗时        ${((Date.now() - t0) / 1000).toFixed(1)}s`)
+    if (problems.length === 0) console.log('  没有发现问题。')
+    else {
+      console.log(`  发现 ${problems.length} 处问题：`)
+      for (const problem of problems) console.log(`    · [${problem.stage}] ${problem.message}`)
+    }
+    if (envHint) console.log(`\n  读数前提    ${envHint}`)
+    return problems
+  } finally {
+    await runtime.close?.()
+    if (!keep && !explicitRoot) await rm(root, { recursive: true, force: true })
+    else console.log(`\n（保留在 ${root}）`)
+  }
+}
+
+main().then(problems => { process.exitCode = problems.length > 0 ? 2 : 0 }).catch(error => {
+  console.error(`\n实跑中断：${short(error)}`)
+  process.exitCode = 1
+})

package/scripts/install-agent-preset.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * Tita Data Agent preset 的**迁移与自检**（0.1.7 改写）。
+ *
+ * ## 这个脚本以前做什么，为什么不能那么做了
+ *
+ * 它以前把 `preset/tita-data-agent/` 拷进 `$DSH_HOME/.agent-presets/<id>/`，
+ * 因为 0.1.5 的用户 preset 就是那个目录里的 `preset.yml` + `agent.cordis.yml`。
+ *
+ * **0.1.7 不再读那个目录。** registry 只接受 `agentPresets.register(config)`，
+ * 没有任何文件系统扫描；preset 的唯一形态是 profile 组合里的一条
+ * `@deepseek-ai/dsh-agent-preset` 声明行。所以「安装」这一步没有了 —— preset 现在
+ * 随插件自己的 bundle patch 分发（`cordis.patch.yml` 的生成标记区），装插件就是装
+ * preset。
+ *
+ * ## 它现在做什么
+ *
+ * 1. **校验同步**：`cordis.patch.yml` 的声明必须与 `preset/` 真源一致。真源改了
+ *    没跑 `pnpm sync:preset` 的话，DSH 读到的还是旧组合 —— 这正是「我改了提示词
+ *    但没生效」最可能的原因。
+ * 2. **报告遗留目录**：`$DSH_HOME/.agent-presets/` 里的旧 preset 已经没有任何
+ *    消费者。留着它只会让人继续以为 preset 装在那里，所以这里如实报出来，并给
+ *    `--remove-legacy` 让人显式清掉。
+ * 3. **打印设默认的两条路径** —— 这个脚本不替用户决定默认 preset。
+ *
+ * 用法：
+ *   node scripts/install-agent-preset.mjs
+ *   node scripts/install-agent-preset.mjs --remove-legacy   # 顺手删掉旧目录
+ */
+import { rm, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+
+/** 与 `src/client/agent-preset.ts` 的 `TITA_PRESET_ID` 一致。 */
+const PRESET_ID = 'tita-data-agent'
+
+const pluginRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const dshHome = resolve(process.env.DSH_HOME || join(homedir(), '.dsh'))
+const legacyDir = join(dshHome, '.agent-presets', PRESET_ID)
+
+const removeLegacy = process.argv.includes('--remove-legacy')
+
+async function exists(path) {
+  try { await stat(path); return true } catch { return false }
+}
+
+async function main() {
+  let problems = 0
+
+  // ── 1. 声明与真源是否同步 ────────────────────────────────────────────────
+  console.log('检查 cordis.patch.yml 里的 preset 声明 …')
+  const sync = spawnSync(process.execPath, [join(pluginRoot, 'scripts', 'sync-agent-preset.mjs'), '--check'], {
+    stdio: 'inherit',
+    cwd: pluginRoot,
+  })
+  if (sync.status !== 0) {
+    problems += 1
+    console.log('  → 不同步。跑 `pnpm sync:preset` 把 preset/ 真源编译进 patch。')
+  }
+
+  // ── 2. 遗留的旧目录 ──────────────────────────────────────────────────────
+  console.log(`\n检查旧目录 ${legacyDir} …`)
+  if (await exists(legacyDir)) {
+    console.log('  存在，但**现在没有任何东西读它**（0.1.7 起 DSH 不扫描 .agent-presets/）。')
+    if (removeLegacy) {
+      await rm(legacyDir, { recursive: true, force: true })
+      console.log('  已按 --remove-legacy 删除。')
+    } else {
+      console.log('  它不会生效，也不会造成冲突；要清掉加 --remove-legacy。')
+      problems += 1
+    }
+  } else {
+    console.log('  不存在，无需迁移。')
+  }
+
+  // ── 3. 怎么让它成为默认 ─────────────────────────────────────────────────
+  console.log('\n让它成为默认（脚本不替你做这个决定）：')
+  // 只有一个入口：DSH 设置里那一项。TitaAgent 面板里曾经有同一个下拉，已经撤了 ——
+  // 它写的是同一个字段，摆两处只会让用户猜哪处算数。
+  console.log(`  · DSH 设置 → Agent 预设 →「${PRESET_ID}」→ 设为默认`)
+  console.log('  · TitaAgent 面板只**告诉你它还不是默认**，并给出提示词的编辑入口（打开 preset 目录）')
+  console.log('\n改动生效需要**重启 DSH**；preset 在会话创建时固定，正在跑的会话不受影响。')
+
+  if (problems > 0) process.exitCode = 1
+}
+
+main().catch(error => {
+  console.error(`检查失败：${error instanceof Error ? error.message : String(error)}`)
+  process.exitCode = 1
+})

package/scripts/setup-embedding.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Install the optional local WeMM runtime and download only the current model
+# files. The model is intentionally outside the repository and is not bundled
+# into the DSH plugin package.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TITA_HOME="${TITA_DATA_AGENT_HOME:-$HOME/.tita-data-agent}"
+VENV="${DSH_EMBEDDING_VENV:-$TITA_HOME/embedding-venv}"
+MODEL_DIR="${DSH_EMBEDDING_MODEL_PATH:-$TITA_HOME/models/WeMM-Embedding-2B-Quantized}"
+PYTHON_BIN="$VENV/bin/python"
+
+mkdir -p "$TITA_HOME" "$MODEL_DIR"
+if [ ! -x "$PYTHON_BIN" ]; then
+  uv venv --python 3.11 "$VENV"
+fi
+uv pip install --python "$PYTHON_BIN" -r "$ROOT/python/requirements.txt"
+
+if [ ! -f "$MODEL_DIR/config.json" ] || [ ! -f "$MODEL_DIR/model.safetensors" ]; then
+  # `hf download` accepts either exact positional filenames or one --include
+  # glob. Exact filenames avoid pulling repository history and work across the
+  # current and older huggingface_hub CLIs.
+  "$VENV/bin/hf" download ewin-reg/WeMM-Embedding-2B-Quantized \
+    model.safetensors tokenizer.json tokenizer_config.json config.json \
+    config_sentence_transformers.json sentence_bert_config.json modules.json \
+    processor_config.json modeling_st_wemm.py modeling_wemm_embedding.py \
+    chat_template.jinja \
+    --local-dir "$MODEL_DIR"
+fi
+
+echo "Embedding runtime ready. Configure Tita Data Agent with:"
+echo "  provider = wemm-python"
+echo "  python   = $PYTHON_BIN"
+echo "  model    = $MODEL_DIR"