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

package/src/proposals.ts

@@ -0,0 +1,337 @@
+import { createHash } from 'node:crypto'
+import { mkdir, readFile, readdir, unlink } from 'node:fs/promises'
+import { join } from 'node:path'
+import { writeTextAtomic } from './fs-atomic.js'
+import { validateCardAgainstType } from './wiki-types.js'
+import type { CardSchemaIssue, WikiTypeDef } from './types.js'
+
+/**
+ * 卡片**提议 → 确认**的两段门（0021 §6.1 / §6.2、0040 §7）。
+ *
+ * ## 它解决什么
+ *
+ * 类型层是**收敛**的那一层 —— 它错一条，所有现象的排序一起错；可它又必须**能不断补充**，
+ * 否则新根因永远进不来。两个要求只有一个解：**让补充低摩擦（Agent 每次排查都提议），
+ * 让生效高门槛（人确认）**。
+ *
+ * ## 为什么不能靠 `status: draft`
+ *
+ * 今天 `status` 只是标签：`draft` 卡照样进 wikiNotes、进图、被召回（只有 `problem`
+ * 被召回路径排除）。要让「未确认不生效」真正成立，就得让提议**根本不落卡片**。
+ * 所以这一层的关键词是「不落 `02_wiki/`」—— 未确认的提议不参与编译、不参与召回、
+ * 不在图上出现，它连一张卡片都还不是。
+ *
+ * ## 提议存在哪（**这一条与 PRD 的措辞有一处偏离，理由写在下面**）
+ *
+ * PRD 说「提议挂在触发它的那条 SourceRaw 上，停在来源侧」。这里按**逻辑上挂在它上面**
+ * 实现：每条提议都带 `sourceRef`，按它索引；但**物理上落在记忆段**
+ * （`<agentRoot>/memory/<库 id>/card-proposals/`）。
+ *
+ * 三条理由：
+ * 1. **它不属于「源头」。** `01_source_truth/` 的性质是「删掉就丢数据」。提议删掉只丢
+ *    待办 —— 重跑一次提议就能回来。把可重建的东西放进源头段，会让「这段能不能删」
+ *    这个问题失去唯一答案（0021 §9 的三段判据）。
+ * 2. **它更不属于知识侧。** 落 `02_wiki/` 正是这道门要拦的事。
+ * 3. **记忆段就是为这种东西存在的。** 它的定义是「关于这个 Agent 的动作留痕，不是关于
+ *    知识的断言」—— 一条待审的提议正好是 Agent 的动作留痕。
+ *
+ * 逻辑上「挂在 SourceRaw 上」这条没有丢：`sourceRef` 是必填字段，review 界面按它分组，
+ * 来源被删掉时提议会如实报「来源已不存在」而不是静默生效。
+ *
+ * ## 判重与拒绝留痕
+ *
+ * 提议 id 由「来源 + 动作 + 类型 + 实体 id」算出来，**稳定**：同一件事重跑一次提议
+ * 不会产生第二条，只会原地更新。内容指纹决定**拒绝之后要不要再提**：
+ * 指纹没变就不再提（不打扰人），指纹变了才重新提（知识确实变了）。
+ */
+
+export type ProposalAction = 'create' | 'update' | 'merge'
+export type ProposalTrigger = 'extraction' | 'agent' | 'diagnosis-run'
+export type ProposalStatus = 'pending' | 'confirmed' | 'rejected'
+
+export interface CardProposal {
+  /** 稳定 id：`p-<hash(sourceRef|action|entityType|entityId)>`。 */
+  id: string
+  /** 触发这条提议的那条 SourceRaw。 */
+  sourceRef: string
+  trigger: ProposalTrigger
+  action: ProposalAction
+  entityType: string
+  entityId: string
+  title: string
+  summary?: string
+  /** 卡片正文（小节 + 结构化块），与 `writeCard` 的 `content` 同形。 */
+  content: string
+  sourceRefs: string[]
+  metadata?: Record<string, unknown>
+  status: ProposalStatus
+  /** 内容指纹：拒绝之后同一条不再重复提。 */
+  fingerprint: string
+  createdAt: string
+  updatedAt: string
+  /** **提议阶段**跑出来的三层校验问题。确认阶段会再跑一遍。 */
+  issues: CardSchemaIssue[]
+  /** `update` / `merge` 的目标卡片当时的正文指纹 —— 提议之后卡片又被人改过时能发现。 */
+  baseHash?: string
+  /** 已经确认、但还没落卡（等人或等 Agent 调 `write_knowledge_card`）。 */
+  confirmedAt?: string
+  confirmedBy?: string
+  /** 落卡时间。有它就说明这条提议已经变成卡片了。 */
+  writtenAt?: string
+  reviewedAt?: string
+  reviewedBy?: string
+  /** 拒绝原因。**必须留档** —— 「为什么这条不算」本身就是知识。 */
+  reason?: string
+}
+
+/** 提一条提议时给的东西。`id` / `status` / 时间戳由 store 生成。 */
+export interface ProposalInput {
+  sourceRef: string
+  trigger: ProposalTrigger
+  action: ProposalAction
+  entityType: string
+  entityId: string
+  title: string
+  summary?: string
+  content: string
+  sourceRefs?: string[]
+  metadata?: Record<string, unknown>
+  baseHash?: string
+}
+
+export interface ProposalSchema {
+  types: WikiTypeDef[]
+}
+
+const TRIGGER_LABEL: Record<ProposalTrigger, string> = {
+  extraction: '编译时自动抽取',
+  agent: 'Agent 主动提议',
+  'diagnosis-run': '一次排查结束',
+}
+
+export function triggerLabel(trigger: ProposalTrigger): string {
+  return TRIGGER_LABEL[trigger] ?? trigger
+}
+
+function shortHash(value: string): string {
+  return createHash('sha256').update(value).digest('hex').slice(0, 16)
+}
+
+/**
+ * 提议的身份：**同一件事重跑不会产生第二条**。
+ *
+ * 它**刻意不含 `sourceRef`**。同一张卡片常常由多份来源共同支撑（同一份口径在两篇文档里
+ * 都写了、一次排查与它的复盘各指一遍）—— 把来源算进身份，同一条提议就会按来源裂成
+ * 好几条，人 review 时要在队列里连着点头三次，而且每次点的都是同一件事。
+ *
+ * 来源没有被丢掉：它是**多值**的。`sourceRef` 记「最先触发它的那一条」，
+ * `sourceRefs` 累积全部触发它的来源（见 `upsert` 的合并规则）。
+ */
+export function proposalIdOf(input: Pick<ProposalInput, 'action' | 'entityType' | 'entityId'>): string {
+  return `p-${shortHash(`${input.action}|${input.entityType}|${input.entityId}`)}`
+}
+
+/**
+ * 内容指纹。
+ *
+ * 它只包含**会改变卡片内容的东西**（标题、正文、出处）：状态流转、时间戳不参与 ——
+ * 否则一次无意义的写入就会让「拒绝过的那条」重新冒出来。
+ */
+export function fingerprintOf(input: Pick<ProposalInput, 'entityType' | 'entityId' | 'title' | 'content' | 'sourceRefs'>): string {
+  const refs = [...(input.sourceRefs ?? [])].sort().join(',')
+  return shortHash(`${input.entityType}|${input.entityId}|${input.title}|${input.content}|${refs}`)
+}
+
+/** 卡片正文的指纹，用来发现「提议之后卡片又被人改过」。 */
+export function contentHashOf(content: string): string {
+  return shortHash(content)
+}
+
+export interface ProposalStoreHost {
+  /** 记忆段根（`<agentRoot>/memory/<库 id>`）。 */
+  memoryRoot: string
+  /** 当前生效的卡片 schema。提议阶段与确认阶段各跑一遍校验。 */
+  schema: () => ProposalSchema
+}
+
+export class CardProposalStore {
+  constructor(private readonly host: ProposalStoreHost) {}
+
+  private get dir(): string { return join(this.host.memoryRoot, 'card-proposals') }
+
+  /** 全部提议，新的在前。读不动就返回空 —— 提议是可重建的待办，不是数据。 */
+  async list(): Promise<CardProposal[]> {
+    let names: string[]
+    try { names = await readdir(this.dir) } catch { return [] }
+    const result: CardProposal[] = []
+    for (const name of names) {
+      if (!name.endsWith('.json')) continue
+      try {
+        const value = JSON.parse(await readFile(join(this.dir, name), 'utf8')) as CardProposal
+        if (value && typeof value.id === 'string') result.push(value)
+      } catch { /* 坏掉的一条不该让整张待办清单消失 */ }
+    }
+    return result.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))
+  }
+
+  async get(id: string): Promise<CardProposal | undefined> {
+    if (!/^p-[a-f0-9]{16}$/.test(id)) return undefined
+    try {
+      const value = JSON.parse(await readFile(join(this.dir, `${id}.json`), 'utf8')) as CardProposal
+      return typeof value?.id === 'string' ? value : undefined
+    } catch { return undefined }
+  }
+
+  async pending(): Promise<CardProposal[]> {
+    return (await this.list()).filter(item => item.status === 'pending')
+  }
+
+  /**
+   * 写入一批提议。返回真正**新增或更新**的那些（被指纹判重挡掉的不会出现在结果里）。
+   *
+   * 三条判重规则，按已有提议的状态分：
+   * - `pending`：原地更新（来源可能又长了一节，正文跟着变），保留 `createdAt`；
+   * - `confirmed` / `written`：指纹相同就跳过（人已经说过是了，不必再问一遍）；
+   * - `rejected`：指纹相同就跳过（不重复打扰人），**指纹变了才重新提**（知识确实变了）。
+   */
+  async upsert(inputs: ProposalInput[]): Promise<CardProposal[]> {
+    if (inputs.length === 0) return []
+    await mkdir(this.dir, { recursive: true })
+    const existing = new Map((await this.list()).map(item => [item.id, item]))
+    const schema = this.host.schema()
+    const touched: CardProposal[] = []
+    const now = new Date().toISOString()
+
+    for (const input of inputs) {
+      const id = proposalIdOf(input)
+      const fingerprint = fingerprintOf(input)
+      const previous = existing.get(id)
+      if (previous && previous.fingerprint === fingerprint && previous.status !== 'pending') continue
+      if (previous && previous.status === 'pending' && previous.fingerprint === fingerprint) continue
+
+      const issues = this.issuesOf(schema, input)
+      /**
+       * 出处**合并**而不是覆盖。
+       *
+       * 提议的身份不含来源（见 `proposalIdOf`），所以第二份来源再提同一张卡片时命中的是
+       * 同一条提议。覆盖的话，第一份来源的出处会凭空消失 —— 而「这张卡片由哪几份来源
+       * 共同支撑」正是 review 时最需要看到的东西。
+       */
+      const sourceRefs = [...new Set([...(previous?.sourceRefs ?? []), ...(input.sourceRefs ?? [input.sourceRef])])]
+      const next: CardProposal = {
+        id,
+        sourceRef: previous?.sourceRef ?? input.sourceRef,
+        trigger: input.trigger,
+        action: input.action,
+        entityType: input.entityType,
+        entityId: input.entityId,
+        title: input.title,
+        ...(input.summary ? { summary: input.summary } : {}),
+        content: input.content,
+        sourceRefs,
+        ...(input.metadata ? { metadata: input.metadata } : {}),
+        status: 'pending',
+        fingerprint,
+        createdAt: previous?.createdAt ?? now,
+        updatedAt: now,
+        issues,
+        ...(input.baseHash ? { baseHash: input.baseHash } : {}),
+      }
+      await writeTextAtomic(join(this.dir, `${id}.json`), JSON.stringify(next, null, 2))
+      existing.set(id, next)
+      touched.push(next)
+    }
+    return touched
+  }
+
+  /** 提议阶段的三层校验。缺字段 / 图断了 / 知识没用，各报各的。 */
+  private issuesOf(schema: ProposalSchema, input: ProposalInput): CardSchemaIssue[] {
+    const type = schema.types.find(def => def.id === input.entityType)
+    if (!type) {
+      return [{ level: 'format', field: 'entity_type', message: `未知卡片类型：${input.entityType}` }]
+    }
+    return validateCardAgainstType(type, {
+      title: input.title,
+      content: input.content,
+      sourceRefs: input.sourceRefs ?? [input.sourceRef],
+      metadata: input.metadata ?? {},
+      ...(input.summary ? { summary: input.summary } : {}),
+    })
+  }
+
+  /**
+   * 人点了「通过」。
+   *
+   * **确认与落卡是两件事**，所以这里只标状态、不写卡片：
+   * - 面板上的主操作是「确认并写入」，它先调这里再调 `writeCard`；
+   * - 副操作是「仅确认」，落卡交给 Agent 的 `write_knowledge_card`（它要求这条提议
+   *   已确认且尚未落卡）。两条路都过同一道门。
+   */
+  async confirm(id: string, by: string, patch?: { content?: string; title?: string; summary?: string }): Promise<CardProposal | undefined> {
+    const previous = await this.get(id)
+    if (!previous || previous.status !== 'pending') return undefined
+    const next: CardProposal = {
+      ...previous,
+      ...(patch?.title !== undefined ? { title: patch.title } : {}),
+      ...(patch?.summary !== undefined ? { summary: patch.summary } : {}),
+      ...(patch?.content !== undefined ? { content: patch.content } : {}),
+      status: 'confirmed',
+      confirmedAt: new Date().toISOString(),
+      confirmedBy: by,
+      reviewedAt: new Date().toISOString(),
+      reviewedBy: by,
+      updatedAt: new Date().toISOString(),
+    }
+    // 人改过之后必须**再跑一遍**校验：提议阶段那一次是 Agent 自己补的，
+    // 这一次的修改来自另一个人（0021 §6.5 说清了为什么要两道都跑）。
+    next.issues = this.issuesOf(this.host.schema(), {
+      sourceRef: next.sourceRef, trigger: next.trigger, action: next.action,
+      entityType: next.entityType, entityId: next.entityId, title: next.title,
+      ...(next.summary ? { summary: next.summary } : {}),
+      content: next.content, sourceRefs: next.sourceRefs,
+      ...(next.metadata ? { metadata: next.metadata } : {}),
+    })
+    next.fingerprint = fingerprintOf(next)
+    await writeTextAtomic(join(this.dir, `${id}.json`), JSON.stringify(next, null, 2))
+    return next
+  }
+
+  /** 落卡成功之后回填。没有这一步，「已确认但没落卡」和「已经落卡了」分不开。 */
+  async markWritten(id: string): Promise<CardProposal | undefined> {
+    const previous = await this.get(id)
+    if (!previous) return undefined
+    const next: CardProposal = { ...previous, writtenAt: new Date().toISOString(), updatedAt: new Date().toISOString() }
+    await writeTextAtomic(join(this.dir, `${id}.json`), JSON.stringify(next, null, 2))
+    return next
+  }
+
+  /**
+   * 人点了「拒绝」。原因留档 —— 它同时是「下次不要再提同一条」的判据。
+   *
+   * 只有 `pending` 能被拒绝：一条已经确认（甚至已经落卡）的提议再被拒，会让
+   * 「卡片在库里、提议却是拒绝态」这种自相矛盾的状态出现在待办区里。
+   */
+  async reject(id: string, reason: string, by: string): Promise<CardProposal | undefined> {
+    const previous = await this.get(id)
+    if (!previous || previous.status !== 'pending') return undefined
+    const next: CardProposal = {
+      ...previous,
+      status: 'rejected',
+      reason: reason.trim() || '（没有写原因）',
+      reviewedAt: new Date().toISOString(),
+      reviewedBy: by,
+      updatedAt: new Date().toISOString(),
+    }
+    await writeTextAtomic(join(this.dir, `${id}.json`), JSON.stringify(next, null, 2))
+    return next
+  }
+
+  /** 删掉一条提议（清理用）。已落卡的提议删掉不影响卡片本身。 */
+  async remove(id: string): Promise<boolean> {
+    if (!/^p-[a-f0-9]{16}$/.test(id)) return false
+    try {
+      await unlink(join(this.dir, `${id}.json`))
+      return true
+    } catch { return false }
+  }
+}