dsh-data-domain-knowledge 0.1.0-alpha.9 → 0.1.1-alpha.2

package/src/migrate.ts

@@ -29,8 +29,8 @@
  */
 
 import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmdirSync, rmSync, statSync } from 'node:fs'
-import { basename, join, resolve } from 'node:path'
-import { knowledgeBaseRoot, looksLikeKnowledgeTree, memoryRoot, resourceRoot, KNOWLEDGE_DB_FILE, DERIVED_DB_FILE, ASSETS_DIR, SOURCE_RAW_DIR } from './layout.js'
+import { basename, dirname, join, resolve } from 'node:path'
+import { AGENT_DIRS, knowledgeBaseRoot, looksLikeKnowledgeTree, memoryRoot, resourceRoot, KNOWLEDGE_DB_FILE, DERIVED_DB_FILE, ASSETS_DIR, SOURCE_RAW_DIR } from './layout.js'
 
 /**
  * 知识树的段。与 `runtime.ts` 的 `LAYOUT` 同源，这里重列是为了不引入 runtime 依赖。
@@ -83,6 +83,79 @@ function skipped(reason: string, from?: string, to?: string): MigrationOutcome {
   return { status: 'skipped', reason, ...(from ? { from } : {}), ...(to ? { to } : {}) }
 }
 
+/**
+ * 把旧版完整的 Agent 根目录合并到新的固定根目录。
+ *
+ * 这和 `migrateLegacyKnowledgeTree` 不同：后者只认识一棵知识库树，而这里要把
+ * `domain_knowledge`、`memory`、`intent`、`resource` 与 `tmp` 一起搬走。目标里已经有
+ * 同名目录时逐层合并，任何同名文件都不覆盖，并把冲突留下来交给界面报告。
+ */
+export function migrateLegacyAgentRoot(input: { agentRoot: string; legacyRoot: string }): MigrationOutcome {
+  const from = resolve(input.legacyRoot)
+  const to = resolve(input.agentRoot)
+  if (from === to) return skipped('新旧 Agent 根路径相同', from, to)
+  if (!existsSync(from)) return skipped('旧 Agent 根路径不存在', from, to)
+
+  const moved: string[] = []
+  const conflicts: string[] = []
+
+  const moveTree = (source: string, target: string, relative: string): void => {
+    if (!existsSync(source)) return
+    if (existsSync(target)) {
+      const sourceIsDir = statSync(source).isDirectory()
+      const targetIsDir = statSync(target).isDirectory()
+      if (!sourceIsDir || !targetIsDir) {
+        conflicts.push(relative)
+        return
+      }
+      for (const name of readdirSync(source)) {
+        moveTree(join(source, name), join(target, name), join(relative, name))
+      }
+      try { rmdirSync(source) } catch { /* 仍有冲突项，保留源目录 */ }
+      return
+    }
+
+    mkdirSync(dirname(target), { recursive: true })
+    try {
+      renameSync(source, target)
+    } catch (cause) {
+      if ((cause as NodeJS.ErrnoException)?.code !== 'EXDEV') throw cause
+      cpSync(source, target, { recursive: true })
+      rmSync(source, { recursive: true, force: true })
+    }
+    moved.push(relative)
+  }
+
+  try {
+    // 新根已经存在时只合并属于 Agent 的目录，不碰用户可能放在旧根下的其他文件。
+    for (const name of AGENT_DIRS) {
+      const source = join(from, name)
+      if (existsSync(source)) moveTree(source, join(to, name), name)
+    }
+    try { rmdirSync(from) } catch { /* 还有未迁移的冲突或用户文件，保留源目录 */ }
+  } catch (cause) {
+    return {
+      status: 'failed',
+      from,
+      to,
+      moved,
+      reason: cause instanceof Error ? cause.message : String(cause),
+    }
+  }
+
+  if (conflicts.length > 0) {
+    return {
+      status: 'failed',
+      from,
+      to,
+      moved,
+      reason: `有 ${conflicts.length} 个同名文件未覆盖：${conflicts.slice(0, 5).join('、')}${conflicts.length > 5 ? '…' : ''}`,
+    }
+  }
+  if (moved.length === 0) return skipped('旧 Agent 根目录没有可搬内容', from, to)
+  return { status: 'moved', from, to, moved, reason: `已迁移 ${moved.length} 项 Agent 数据` }
+}
+
 /**
  * 把 `legacyRoot` 下的知识树搬进 `<agentRoot>/domain_knowledge/<kbId>`。
  *

package/src/model-text.ts

@@ -1,3 +1,5 @@
+import type { TrialTokenUsage } from './wiki-trial-types.js'
+
 /**
  * 把平台 `llm` 服务的 chunk 流收成一段文本（0044 实机验证第三批）。
  *
@@ -29,6 +31,7 @@
 interface StreamChunkLike {
   type?: string
   text?: string
+  usage?: TrialTokenUsage
   reason?: { kind?: string; failure?: { code?: string; message?: string } }
 }
 
@@ -95,7 +98,11 @@ export function buildModelRequest(input: {
  * @throws 流以 error / aborted 结束时，抛出带 code 与 message 的错误；
  *         流正常结束但一个字符都没有时，也抛 —— 「模型没说话」不是一次成功的调用。
  */
-export async function collectModelText(stream: AsyncIterable<StreamChunkLike>): Promise<string> {
+export async function collectModelText(
+  stream: AsyncIterable<StreamChunkLike>,
+  onUsage?: (usage: TrialTokenUsage) => void,
+  onDelta?: (text: string) => void,
+): Promise<string> {
   let text = ''
   /** 流怎么结束的。用来区分「正常但空」「失败」「中止」三种情况。 */
   let finish: string | undefined
@@ -103,8 +110,10 @@ export async function collectModelText(stream: AsyncIterable<StreamChunkLike>):
 
   for await (const chunk of stream) {
     if (!chunk || typeof chunk !== 'object') continue
+    if (chunk.type === 'usage' && chunk.usage) onUsage?.(chunk.usage)
     if (chunk.type === 'text-delta' && typeof chunk.text === 'string') {
       text += chunk.text
+      onDelta?.(chunk.text)
       continue
     }
     if (chunk.type === 'finish') {
@@ -113,9 +122,9 @@ export async function collectModelText(stream: AsyncIterable<StreamChunkLike>):
     }
   }
 
-  if (failure) {
-    const code = failure.code?.trim() || '未知错误码'
-    const message = failure.message?.trim() || '模型服务没有给出说明'
+  if (failure || finish === 'error' || finish === 'aborted' || finish === 'max-tokens') {
+    const code = failure?.code?.trim() || (finish === 'max-tokens' ? 'OUTPUT_TRUNCATED' : '未知错误码')
+    const message = failure?.message?.trim() || (finish === 'max-tokens' ? '输出达到长度上限，部分返回已保留，请调整模型限制后重试' : '模型服务没有给出说明')
     throw new Error(`模型调用失败（${code}）：${message}`)
   }
   if (text.length === 0) {
@@ -124,3 +133,99 @@ export async function collectModelText(stream: AsyncIterable<StreamChunkLike>):
   }
   return text
 }
+
+/**
+ * 这次失败**重发一次有没有意义**。
+ *
+ * ## 为什么需要这个判断
+ *
+ * 知识抽取是一次**长**调用：一次调用要吐出几十条 Knowledge，实测一次
+ * `deepseek-v4.1-flash` 的抽取要生成约四万 token、跑两三分钟（见实机轨迹）。
+ * 上游网关、本机代理、账号额度任何一处短暂抽风，都会让流在半路结束 ——
+ * 适配器报出来就是 `TRANSPORT: Stream ended without finish_reason`，
+ * 一次失败就让整份文档的抽取作废，而重发一次多半是好的。
+ *
+ * 但**不是所有失败都值得重发**：
+ *
+ * - 凭据无效、模型不存在、请求体不合法 → 重发只会同样失败，还多等两分钟；
+ * - 输出撞上长度上限（`OUTPUT_TRUNCATED`）→ 同样的提示词会得到同样的截断；
+ * - 用户主动取消（`ABORTED`）→ 再发一次等于不听取消。
+ *
+ * 所以这里只承认「网络/网关/上游临时故障」这一类。判据用**错误码优先**：
+ * 适配器的 code 是稳定契约，message 是给人看的，会随版本改。
+ */
+export function isRetryableModelFailure(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error)
+  const code = /模型调用失败（([^）]*)）/.exec(message)?.[1]?.trim().toUpperCase() ?? ''
+
+  // 明确不可重试：配置问题与用户取消。宁可让人去改设置，也不要在错的地方重试。
+  if (['ABORTED', 'INVALID_CREDENTIAL', 'AUTH', 'UNAUTHORIZED', 'NOT_FOUND', 'INVALID_REQUEST', 'CONTEXT_LENGTH', 'OUTPUT_TRUNCATED'].includes(code)) return false
+
+  // 明确可重试：上游在流式过程中断掉。
+  if (['TRANSPORT', 'NETWORK', 'TIMEOUT', 'RATE_LIMIT', 'OVERLOADED', 'SERVER_ERROR', 'INTERNAL'].includes(code)) return true
+
+  // 没有 code 的情况（旧适配器、或错误被包了一层）：按可辨认的措辞判断。
+  if (/没有返回任何文本|没有收到 finish 块|Stream ended without finish_reason/i.test(message)) return true
+  if (/ECONNRESET|ECONNREFUSED|ETIMEDOUT|EPIPE|socket hang up|premature close|other side closed|fetch failed|network error|HTTP 5\d\d|HTTP 429/i.test(message)) return true
+
+  return false
+}
+
+/** 重试策略：最多几次、每次之前等多久。 */
+export interface ModelRetryOptions {
+  /** 总尝试次数（含第一次）。默认 3。 */
+  attempts?: number
+  /** 第 N 次重试前等多久；用完后沿用最后一个。默认 2s / 6s。 */
+  delaysMs?: number[]
+  /** 每次重试前告诉调用方（打日志、写面板）。 */
+  onRetry?: (info: { attempt: number; attempts: number; error: unknown; delayMs: number }) => void
+  /** 重试时往**流式预览**里写的一行说明；不给就写默认文案。传 null 表示不写。 */
+  notice?: ((info: { attempt: number; attempts: number; error: unknown }) => string | null) | null
+  /** 注入 sleep，测试里不必真的等。 */
+  sleep?: (ms: number) => Promise<void>
+}
+
+/**
+ * 用**同一个请求**重发几次，直到成功或遇到不可重试的失败。
+ *
+ * `send` 每次都会收到一个新的 `onDelta` —— 调用方按 attempt 收流，失败的那几次
+ * 收过的字不会被算进最终结果（`collectModelText` 每轮从空串开始）。
+ *
+ * 重试时往预览里写一句 `[模型流中断…正在重试 N/M]`：不写的话，界面上会出现
+ * 「前半份 JSON + 后半份 JSON」拼在一起，看起来像模型答错了，而不是流断了。
+ */
+export async function callModelWithRetry(
+  send: (onDelta: (text: string) => void) => Promise<string>,
+  options: ModelRetryOptions & { onDelta?: (text: string) => void } = {},
+): Promise<string> {
+  const attempts = Math.max(1, Math.floor(options.attempts ?? 3))
+  const delays = options.delaysMs ?? [2000, 6000]
+  const sleep = options.sleep ?? ((ms: number) => new Promise<void>(resolve => { setTimeout(resolve, ms) }))
+  const notice = options.notice === undefined
+    ? (info: { attempt: number; attempts: number; error: unknown }) =>
+      `\n\n[模型流中断（${info.error instanceof Error ? info.error.message : String(info.error)}），正在重试 ${info.attempt}/${info.attempts - 1}]\n\n`
+    : options.notice
+
+  let lastError: unknown
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    try {
+      return await send(text => options.onDelta?.(text))
+    } catch (error) {
+      lastError = error
+      if (attempt >= attempts || !isRetryableModelFailure(error)) throw error
+      const delayMs = delays[Math.min(attempt - 1, delays.length - 1)] ?? 0
+      options.onRetry?.({ attempt, attempts, error, delayMs })
+      const line = notice?.({ attempt, attempts, error }) ?? ''
+      if (line) options.onDelta?.(line)
+      await sleep(delayMs)
+    }
+  }
+  /**
+   * 用尽之后的报错要说出**重过几次**。
+   *
+   * 「一次就失败」与「重了两次还是失败」对读的人是两件事：前者查代码/提示词，
+   * 后者查额度、代理和上游状态。不写这一句，新加的重试在界面上等于不存在。
+   */
+  const message = lastError instanceof Error ? lastError.message : String(lastError)
+  throw new Error(`${message}（已自动重试 ${attempts - 1} 次仍失败；可稍后重试此阶段，或检查账号额度与网络代理）`)
+}

package/src/oplog.ts

@@ -30,6 +30,7 @@
 import { mkdir } from 'node:fs/promises'
 import { dirname } from 'node:path'
 import { loadSqlite, type SqliteDatabase } from './fts.js'
+import { applyRetention } from './retention.js'
 import type { OperationDetail, OperationKind, OperationStatus } from './types.js'
 
 /** 谁发起的：面板按钮，还是 Agent 的工具。 */
@@ -125,6 +126,12 @@ export class OperationLog {
     this.db.prepare(
       'INSERT INTO operations (id, kind, status, actor, kb, title, summary, started_at, finished_at, detail) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
     ).run(entry.id, entry.kind, entry.status, entry.actor, entry.kb, entry.title, entry.summary, entry.startedAt, entry.finishedAt ?? null, JSON.stringify(entry.detail))
+    /*
+     * 处理日志的保留上限（0070）。这张表原来只增不减：每编译一次、每导入一批都加行，
+     * 而 `detail` 里还塞着整批文件清单。上限同样只作用在**水位以上**的新行 ——
+     * 升级那一刻已有的日志一条不删（见 `retention.ts`）。
+     */
+    applyRetention(this.db, 'operations', { table: 'operations', key: 'rowid', keep: 2000 })
   }
 
   async patch(

package/src/organize-contract.ts

@@ -0,0 +1,83 @@
+/**
+ * 组织阶段（Organize）的 system 段。
+ *
+ * 与 `extract-contract.ts` 同一个理由：说明页要把「这一步发给模型的提示词」原样显示出来，
+ * 所以它必须能从浏览器 bundle 里 import。它原来住在 `card-organize.ts` 里，那个模块
+ * import 了 `node:crypto`（算版面指纹），客户端进不去。
+ *
+ * 服务端照旧通过 `card-organize.ts` 的 re-export 拿它 —— 界面与真正发出去的提示词
+ * 读的是同一份文本。
+ */
+
+/**
+ * 组织阶段的 system 提示词。
+ *
+ * 四条规则是这份提示词的全部：**只组织不创造**、**每条知识都要落地**、
+ * **每句都要挂引用**。其余全是输出形状。
+ */
+export function buildOrganizeSystem(wikiKind: 'fact' | 'way' = 'fact'): string {
+  return [
+    '你在把一批已经抽好的知识组织成一张 Wiki 卡片。',
+    '',
+    `文件类型：${wikiKind === 'way' ? 'Wiki Way；同 Object + Action 的 Procedure' : 'Wiki Fact；同 Object 的 Fact'}。Scene 可以不同，必须保留每条的条件、状态与限制。`,
+    '这些条目是 Knowledge 真源。你不许新增、',
+    '删除或改动它们说的事实。你能做的是：分小节、定顺序、把它们改写成读得下去的',
+    '叙述、给卡片起一个自然的标题、写一句概述。',
+    '',
+    '## 三条规则',
+    '',
+    '1. **只组织，不创造。** 你写的每一句话，说的都必须是这批知识里已经有的事。',
+    '   你觉得「应该还有一步」而知识里没有 —— 那就不要写。',
+    '2. **每条知识都要落地。** 输入给了几条，正文里就必须用上几条，一条都不能丢。',
+    '   可以把两条合成一行表格、合成一个步骤 —— 但它们的 id 都要挂上。',
+    '3. **每句都要挂引用。** 陈述事实的句子末尾挂 `[^知识id]`，可以挂多个。',
+    '   只有很短的导语（「这一节讲取数流程」）可以不挂。长句子不挂引用 = 没有来源的',
+    '   断言，整份方案会被打回。',
+    '4. **标题只做归纳，不要机械拼接。** 标题要能让人一眼知道卡片讲什么；不要照抄候选卡名，',
+    '   不要写成「对象的动作」「动作的动作」这类重复结构，不要加入知识里没有的新事实。',
+    '   保留区分这张卡所需的业务对象、字段名和动作词。知识条目附带的原文标题路径是定位线索，',
+    '   可用来补回被知识正文省略的对象或动作词；它不能单独证明新的业务事实。',
+    '',
+    '## 可以做的改写',
+    '',
+    '- 允许缩写与重排，不改变原意，不从 Fact 推导新方法，不从 Case 新提炼 Procedure。',
+    '- 把两条同类的知识合成一张表或一个步骤。',
+    '- 把字段名、SQL、URL 放进反引号。',
+    '- 加很短的小节导语，把一节的内容串起来。',
+    '',
+    '## 输出形状',
+    '',
+    '只回一个 JSON 对象，不要散文，不要代码围栏。',
+    '',
+    '```json',
+    '{',
+    '  "title": "简洁、自然、可检索的标题；保留必要的业务对象、字段名和动作词",',
+    '  "summary": "一句话说清这张卡讲什么。挂引用，如 [^k_abc]。",',
+    '  "sections": [',
+    '    {',
+    '      "title": "一、这一节讲什么",',
+    '      "blocks": [',
+    '        { "kind": "prose", "text": "一段话。[^k_abc]" },',
+    '        { "kind": "steps", "items": ["第一步。[^k_def]", "第二步。[^k_ghi]"] },',
+    '        { "kind": "bullets", "items": ["一个要点。[^k_jkl]"] },',
+    '        { "kind": "table", "header": ["", "甲", "乙"], "rows": [["来源", "A[^k_mno]", "B[^k_pqr]"]] },',
+    '        { "kind": "note", "text": "一句提醒。[^k_stu]" }',
+    '      ]',
+    '    }',
+    '  ]',
+    '}',
+    '```',
+    '',
+    '`kind` 只能是这五个之一：`prose`（一段话）、`steps`（有序步骤）、`bullets`（无序要点）、',
+    '`table`（对比表）、`note`（提醒）。表格的每一行列数必须与表头一致。',
+    '',
+    '二级章节用于召回；一个章节服务一个明确的信息需求或一组等价问法。',
+    '回答同一需求的内容放一起；服务不同需求时拆分；必要条件、例外、步骤不因形式被拆散。',
+    '不要套固定目录，不使用无主体的说明、其他、注意事项、操作步骤等标题。',
+    '标题写具体对象、任务、字段及改变答案的条件。章节不必等于一条 Fact 或 Procedure。',
+    'Scene 分支可用三级标题；正文不能再出现 Markdown 二级标题。',
+    '每节返回 section_id（复用已有 ID，新节为 null）、retrieval_need（检索需求）、knowledge_ids（正文引用的记录 ID）。',
+    '小节数量由检索需求决定；不要为凑目录数量而丢失知识或合并无关问题。协议最多支持 200 节，超过时应报错。',
+  ].join('\n')
+}
+