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

package/src/wiki-finalize.ts

@@ -0,0 +1,310 @@
+/**
+ * 编译的收尾段（issue 0049）：**索引页、断链检查、相关卡片**。
+ *
+ * 三段都不调用模型，全是规则与图算法 —— 它们是「已经落盘的卡片」上的确定性计算，
+ * 所以可以重复跑，跑出来的东西逐字相同。这一点是它们能被信任的前提：一次重编不会
+ * 让索引页改一个字，也不会让卡片的相关列表换一批。
+ *
+ * ## 三段各自解决什么
+ *
+ * 1. **相关卡片**（`planRelated`）—— 卡片之间原来只有图上的边，正文里什么都没有，
+ *    人打开一张卡片看不到它跟谁有关系。现在把关系**写进正文末尾的一块**，并且
+ *    整块替换（不是追加）：追加会让卡片每编译一次长一截。
+ * 2. **断链检查**（`deadLinksOf`）—— 正文里的 `[[类型/名称]]` 原来没有任何人校验，
+ *    指向一张不存在的卡片也照样写着。这是「三层校验」里 `reference` 那一层的实际内容
+ *    （0044 之前它定义了但没有任何产生者）。
+ * 3. **索引页**（`buildWikiIndex`）—— 知识库原来没有「这里有什么」的落盘入口：
+ *    卡片列表只在界面上，不打开界面就没有目录。
+ *
+ * ## 为什么相关块带一个 HTML 注释标记
+ *
+ * 卡片正文是**只读**的（编译追加，人和 Agent 都不能改），而模型写卡片时完全可能
+ * 自己写一个 `## 相关` 小节。靠小节名去删，会把模型写的正文当成编译产物删掉。
+ * 所以块首带 `<!-- compiled:related -->`：只删带标记的那一块，别的一个字不碰。
+ *
+ * ## 为什么只认 wiki 链接语法
+ *
+ * 相关块里写的是 `[[类型/标题|标题]]`，不是 markdown 相对链接。两个理由：卡片没有
+ * 自己的页面地址，写 `../concept/x.md` 在面板里点开是 404；而 `[[…]]` 是这套知识库
+ * 自己的引用语法（来源文档里的 `[[链接]]` 会被 Pass 0 读成关系候选），断链检查认它，
+ * `grep` 也认它。
+ *
+ * @module
+ */
+
+import { buildAliasIndex, candidateKey, normalizeCandidateName } from './extract.js'
+import type { KnowledgeCard } from './types.js'
+
+/** 卡片之间的关系来源：来源里写明的关系，还是「同一份来源编译出来的」。 */
+export type RelatedReason = 'relation' | 'source'
+
+export interface RelatedEntry {
+  /** 图上的节点键 `<entityType>:<entityId>`，与 `knowledge_graph.json` 同一套键。 */
+  key: string
+  entityType: string
+  entityId: string
+  title: string
+  reason: RelatedReason
+}
+
+/**
+ * 一张卡片最多列几条相关。
+ *
+ * 上限是**有意的**，不是省略号：一份来源编译出十张卡片时，两两相连是 90 条，
+ * 那样每张卡片的末尾都会挂一份比正文还长的清单，人就不看了。关系优先于同源。
+ */
+export const MAX_RELATED = 8
+
+/** 相关块的标记行。删块只认它，不认小节名。 */
+export const RELATED_MARK = '<!-- compiled:related -->'
+
+export const RELATED_HEADING = '## 相关'
+
+/** 正文里的 wiki 链接：`[[类型/名称]]`、`[[类型/名称|显示文字]]`、`[[名称]]`。 */
+const WIKI_LINK = /\[\[([^\]|]+)(?:\|[^\]]*)?\]\]/g
+
+/** 卡片正文里出现的 wiki 链接目标（原样，未归一）。 */
+export function wikiLinkTargets(content: string): string[] {
+  const targets: string[] = []
+  for (const match of content.matchAll(WIKI_LINK)) {
+    const target = (match[1] ?? '').trim()
+    if (target) targets.push(target)
+  }
+  return targets
+}
+
+/**
+ * 去掉正文末尾的相关块。**只删带标记的那一块**，没有标记时原样返回。
+ *
+ * 相关块永远在末尾（`applyRelatedSection` 只往末尾写），所以找到标记就是找到块首。
+ */
+export function stripRelatedSection(content: string): string {
+  const at = content.indexOf(RELATED_MARK)
+  if (at < 0) return content
+  return content.slice(0, at).replace(/\s+$/, '')
+}
+
+/** `[[类型/标题|标题]]` 里的目标：标题里的 `|` 与 `]` 会破坏语法，去掉。 */
+export function wikiLinkOf(entityType: string, title: string, fallbackId: string): string {
+  const clean = title.replace(/[|\]]/g, '').trim() || fallbackId
+  return `[[${entityType}/${clean}|${clean}]]`
+}
+
+function linkTargetOf(entry: RelatedEntry): string {
+  return wikiLinkOf(entry.entityType, entry.title, entry.entityId)
+}
+
+const REASON_LABEL: Record<RelatedReason, string> = {
+  relation: '来源里写明的关系',
+  source: '同一份来源',
+}
+
+export function renderRelatedSection(entries: RelatedEntry[]): string {
+  const lines = entries.map(entry => `- ${linkTargetOf(entry)} · ${REASON_LABEL[entry.reason]}`)
+  return `${RELATED_MARK}\n${RELATED_HEADING}\n${lines.join('\n')}`
+}
+
+/**
+ * 把相关块写到正文末尾。**幂等**：先删旧块再写新块，所以重复调用结果相同；
+ * 一条相关都没有时不留空块（留一个只有标题的小节比没有更难看）。
+ */
+export function applyRelatedSection(content: string, entries: RelatedEntry[]): string {
+  const base = stripRelatedSection(content)
+  if (entries.length === 0) return base
+  return `${base}\n\n${renderRelatedSection(entries)}`
+}
+
+/** 卡片的节点键，与图、与关系候选同一套写法。 */
+export function cardKey(card: { entityType: string; entityId: string }): string {
+  return `${card.entityType}:${card.entityId}`
+}
+
+/**
+ * 相关卡片计划：`卡片键 → 相关条目`（双向）。
+ *
+ * 两个来源，优先级不同：
+ * 1. **关系**（`relations`，即 Pass 0 从来源文档里抽出的 `relates_to`）—— 强，双向都记；
+ * 2. **同源**（两张卡片引用了同一份 SourceRaw）—— 弱，只补前面没覆盖到的。
+ *
+ * 弱的那一类是有用的：知识库刚建起来时，关系一条都没有，而「这几张卡来自同一篇文章」
+ * 恰好是人最需要的导航。它不该盖过写明的关系，所以排在后面、并且有上限。
+ */
+export function planRelated(
+  cards: Array<Pick<KnowledgeCard, 'entityType' | 'entityId' | 'title' | 'sourceRefs'>>,
+  relations: Array<{ fromKey: string; toKey: string }>,
+): Map<string, RelatedEntry[]> {
+  const byKey = new Map(cards.map(card => [cardKey(card), card]))
+  const planned = new Map<string, RelatedEntry[]>()
+  const seen = new Map<string, Set<string>>()
+
+  const add = (fromKey: string, toKey: string, reason: RelatedReason): void => {
+    if (fromKey === toKey) return
+    // **两端都要真实存在**：来源文档里可以写一条指向还没建出来的实体的关系，
+    // 但那张卡片不存在，就不能凭空给它挂一份相关清单（它的键在卡片清单里没有对应物，
+    // 索引页也会据此写出一行点不开的目录）。
+    if (!byKey.has(fromKey)) return
+    const target = byKey.get(toKey)
+    if (!target) return
+    const keys = seen.get(fromKey) ?? new Set<string>()
+    if (keys.has(toKey)) return
+    keys.add(toKey)
+    seen.set(fromKey, keys)
+    const bucket = planned.get(fromKey) ?? []
+    bucket.push({ key: toKey, entityType: target.entityType, entityId: target.entityId, title: target.title, reason })
+    planned.set(fromKey, bucket)
+  }
+
+  // 关系：双向都记。来源文档里「A 提到 B」本来就意味着两边互相能找得到。
+  for (const relation of relations) {
+    add(relation.fromKey, relation.toKey, 'relation')
+    add(relation.toKey, relation.fromKey, 'relation')
+  }
+
+  // 同源：按来源分组，组内两两相连。标题排序，所以同源那几条的顺序不随文件系统变。
+  const bySource = new Map<string, Array<Pick<KnowledgeCard, 'entityType' | 'entityId' | 'title' | 'sourceRefs'>>>()
+  for (const card of cards) {
+    for (const sourceRef of card.sourceRefs) {
+      const bucket = bySource.get(sourceRef) ?? []
+      bucket.push(card)
+      bySource.set(sourceRef, bucket)
+    }
+  }
+  for (const bucket of [...bySource.values()].sort((left, right) => cardKey(left[0]!).localeCompare(cardKey(right[0]!)))) {
+    const ordered = [...bucket].sort((left, right) => left.title.localeCompare(right.title, 'zh'))
+    for (const card of ordered) {
+      for (const other of ordered) add(cardKey(card), cardKey(other), 'source')
+    }
+  }
+
+  // 上限：关系排在前面（它们先入桶），所以截断只会截掉同源那几条。
+  for (const [key, entries] of planned) planned.set(key, entries.slice(0, MAX_RELATED))
+  return planned
+}
+
+export interface DeadLink {
+  /** 出现这条断链的卡片键。 */
+  key: string
+  entityId: string
+  entityType: string
+  /** 原样的链接目标，报给用户看的就是它。 */
+  target: string
+}
+
+/**
+ * 断链：正文里 `[[…]]` 指向一张不存在的卡片。
+ *
+ * 判据与抽取的判重**同一套**（`buildAliasIndex`：类型 + entityId / 标题 / 别名），
+ * 所以「抽取时认得是同一张卡」与「链接能解析」不可能给出两个答案。自链接不算断链：
+ * 卡片提到自己不是错误，只是没有信息量。
+ *
+ * 裸名字（`[[GMV 口径]]`）不带类型，所以按名字在**所有类型**里找一遍 —— 找不到才算断。
+ *
+ * 类型 id 自己可以带 `/`（`diagnosis/check-point` 就是一个真实类型），所以
+ * `[[diagnosis/check-point/主键唯一性]]` 不能只按**第一个** `/` 切：那样切出来的类型是
+ * `diagnosis`，名字是 `check-point/主键唯一性`，一个都查不到 —— 卡片之间那几条相关链接
+ * 会被整批报成断链。这里从最长的类型前缀开始试（即从左往右逐个 `/` 切）。
+ */
+export function deadLinksOf(cards: KnowledgeCard[], index?: Map<string, KnowledgeCard>): DeadLink[] {
+  const resolved = index ?? buildAliasIndex(cards)
+  const byName = new Map<string, KnowledgeCard>()
+  for (const card of cards) {
+    for (const name of [card.entityId, card.title, ...aliasesOf(card)]) {
+      const normalized = normalizeCandidateName(name)
+      if (normalized && !byName.has(normalized)) byName.set(normalized, card)
+    }
+  }
+  const resolveTarget = (target: string): KnowledgeCard | undefined => {
+    for (let at = target.indexOf('/'); at > 0; at = target.indexOf('/', at + 1)) {
+      const hit = resolved.get(candidateKey({ type: target.slice(0, at), name: target.slice(at + 1) }))
+      if (hit) return hit
+    }
+    return byName.get(normalizeCandidateName(target))
+  }
+  const dead: DeadLink[] = []
+  for (const card of cards) {
+    const self = cardKey(card)
+    for (const target of wikiLinkTargets(card.content)) {
+      // 解析得到就不算断链 —— 自链接（卡片提到自己）也走这一条。
+      if (resolveTarget(target) !== undefined) continue
+      dead.push({ key: self, entityId: card.entityId, entityType: card.entityType, target })
+    }
+  }
+  return dead
+}
+
+function aliasesOf(card: KnowledgeCard): string[] {
+  const raw = card.metadata.aliases
+  if (typeof raw === 'string') return [raw]
+  if (!Array.isArray(raw)) return []
+  return raw.filter((item): item is string => typeof item === 'string')
+}
+
+/** 三层校验里 `reference` 那一层的报错文案（写进卡片的 `schema_issues`）。 */
+export function deadLinkIssue(target: string): { level: 'reference'; field: string; message: string } {
+  return { level: 'reference', field: 'links', message: `正文里的 [[${target}]] 指向一张不存在的卡片` }
+}
+
+export interface WikiIndexInput {
+  cards: KnowledgeCard[]
+  related: Map<string, RelatedEntry[]>
+  deadLinks: DeadLink[]
+}
+
+/**
+ * 索引页：**不打开界面也能知道这个库里有什么**。
+ *
+ * 它是派生文件（每次编译重算），所以落在 `03_compiled/`，不落在 `02_wiki/` ——
+ * 后者的每一份 `.md` 都会被当成一张卡片读进卡片清单，把索引页放进去，它会变成一张
+ * 标题叫「知识库索引」的卡片，而且每次编译都变一次。
+ *
+ * 内容按类型分组（类型是这套 schema 的一等公民），每张卡片一行：链接 + 状态 + 待补数。
+ * 断链单独一节列在末尾 —— 它是「要动手修」的东西，不该混在目录里。
+ *
+ * **刻意不写生成时间与版本号。** 写了它们，这份文件每次重建都会变一个字节，而增量
+ * 编译要靠「索引页变了没有」判断这一轮要不要真的落盘 —— 一个永远在变的产物会让
+ * 增量编译永远判定「有变化」，空操作那条路就再也走不到。新鲜度由文件本身的
+ * 修改时间与 `build-manifest.json` 回答，不需要在正文里再写一遍。
+ */
+export function buildWikiIndex(input: WikiIndexInput): string {
+  const { cards, related, deadLinks } = input
+  const byType = new Map<string, KnowledgeCard[]>()
+  for (const card of cards) {
+    const bucket = byType.get(card.entityType) ?? []
+    bucket.push(card)
+    byType.set(card.entityType, bucket)
+  }
+  const relatedLinks = [...related.values()].reduce((sum, entries) => sum + entries.length, 0)
+  const missing = cards.reduce((sum, card) => sum + issuesOf(card).length, 0)
+
+  const lines: string[] = []
+  lines.push('# 知识库索引', '')
+  lines.push(`- 卡片 ${cards.length} 张 · 类型 ${byType.size} 个 · 相关链接 ${relatedLinks} 条 · 断链 ${deadLinks.length} 条`)
+  lines.push(`- 待补 ${missing} 项`)
+  lines.push('', '这个文件由编译生成，不是手写的。它列出库里现有的卡片；改卡片请改 `02_wiki/` 下的那一份。', '')
+
+  for (const type of [...byType.keys()].sort((left, right) => left.localeCompare(right))) {
+    const bucket = [...byType.get(type)!].sort((left, right) => left.title.localeCompare(right.title, 'zh'))
+    lines.push(`## ${type}（${bucket.length} 张）`, '')
+    for (const card of bucket) {
+      const issues = issuesOf(card).length
+      const facts = [card.status, issues > 0 ? `待补 ${issues}` : undefined].filter(Boolean).join(' · ')
+      lines.push(`- ${wikiLinkOf(card.entityType, card.title, card.entityId)} · ${facts}`)
+      if (card.summary?.trim()) lines.push(`  ${card.summary.trim().replace(/\s+/g, ' ')}`)
+    }
+    lines.push('')
+  }
+
+  if (deadLinks.length > 0) {
+    lines.push(`## 断链（${deadLinks.length} 条）`, '')
+    for (const link of deadLinks) lines.push(`- ${link.entityType}/${link.entityId} 里的 [[${link.target}]] 找不到对应卡片`)
+    lines.push('')
+  }
+
+  return `${lines.join('\n').replace(/\n+$/, '')}\n`
+}
+
+/** 卡片上的待补项（`metadata.schema_issues`）。索引页只数个数，不搬全文。 */
+function issuesOf(card: KnowledgeCard): unknown[] {
+  const raw = card.metadata.schema_issues
+  return Array.isArray(raw) ? raw : []
+}

package/src/wiki-types.ts

@@ -5,15 +5,19 @@ import type { CardSchemaIssue, WikiFieldSpec, WikiSectionSpec, WikiTypeDef } fro
  * Wiki 卡片类型的出厂定义与校验（issue 0024）。
  *
  * 这一层回答的是"**SourceRaw → Wiki** 能生成什么、每类长什么样"。它不是生成器：
- * 生成仍由模型完成（`write_knowledge_card`），这里提供的是**判据 + 骨架 + 校验**。
+ * 生成由模型完成（`extract-model.ts` 的编译器，或 Agent 的 `propose_wiki_cards`），
+ * 这里提供的是**判据 + 骨架 + 校验**。
  *
  * 三个设计判断：
  *
- * 1. **schema 就是提示词。** 类型定义、示例、必填小节都随 `write_knowledge_card` 的工具
- *    描述下发（与 0023 同一机制），所以用户改完类型下一轮模型就看到新规则。
+ * 1. **schema 就是提示词。** 类型定义、示例、必填小节、模板都会下发 —— 0044 起直接下发给
+ *    编译器的抽取提示词（`extract-model.ts` 的 `renderTypeSpec`），所以用户改完类型，
+ *    下一次编译写出来的卡片骨架就变了。改 schema 因此是一件真的会改变产物的事。
  * 2. **模板决定这套 schema 能不能被用起来**（0021 的判断）。`template` 由 `sections` 派生，
  *    不手写第二份，否则又是一处"校验通过但人照着抄还是错"。
  * 3. **校验分三层**：格式 / 引用 / 语义。混成同一个"校验失败"，人就学不会怎么写卡片。
+ *    0044 起校验**不再拦截写盘**（缺信息也入库），它只把问题写进 `metadata.schema_issues`，
+ *    由面板显示成「待补」。
  */
 
 /** 出厂 wiki 类型：6 个通用类型 + diagnosis 的 5 个类型族。 */
@@ -191,9 +195,10 @@ export const WIKI_TYPE_RULES = [
   '所有类型都不命中时，才按语义新起一个类型 id（小写英文，可带 `命名空间/名字`），并在知识库设置里把它登记成正式类型。',
   '一张卡片只讲一件事：概念讲定义、指标讲口径、手册讲做法、案例讲发生过的事。混在一起时要拆成多张卡片。',
   '卡片必须引用真实存在的 SourceRaw：`source_refs` 写了不存在的来源会被直接拒绝。',
-  '必填小节与必填字段来自类型定义；缺了它们卡片仍然可写（report 模式），但会被标成待补。',
-  '**写卡片之前先提提议**：用 `propose_wiki_cards` 把草案挂到触发它的那条 SourceRaw 上，由人在「知识库 → Wiki」的待办区确认之后才落卡。未确认的草案不落 `02_wiki/`、不进编译、不参与召回、不在图上出现。',
-  '`write_knowledge_card` 只接受**已确认且尚未落卡**的提议（带 `proposal_id`）—— 它没有「未确认也能写」这条路径。',
+  '必填小节与必填字段来自类型定义；**缺了它们卡片照样入库**，会被标成待补，后面有涉及到的文档再慢慢补。',
+  '**入库在前、review 在后**（0044）：卡片一编译就直接写进 `02_wiki` 并立刻可召回，不需要任何人先确认。',
+  '**正文只读**：卡片正文由编译产出（新文档会追加进来），人和 Agent 都不能手工改它。要指出问题就加备注（`annotate_wiki_card`，异常点用 `kind: anomaly`）。',
+  'review（`review_wiki_card`）在入库之后做，它抬高卡片的召回评分；两个动作都可逆，review 不是准入凭证。',
 ].join('\n')
 
 /** 新增 / 编辑类型时提交的草稿。 */
@@ -303,7 +308,8 @@ function hasSection(content: string, label: string): boolean {
 /**
  * 三层校验：format / reference / semantic。
  *
- * 只报问题，不决定是否写入——是否拦截由 `wikiSchemaMode` 决定（strict 拒绝 / report 标记）。
+ * 只报问题，**不决定是否写入**：0044 起卡片一律直接入库，问题写进 `metadata.schema_issues`，
+ * 由面板显示成「待补」。
  */
 export function validateCardAgainstType(
   type: WikiTypeDef,

package/lib/types/proposals.d.ts

@@ -1,166 +0,0 @@
-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[];
-}
-export declare function triggerLabel(trigger: ProposalTrigger): string;
-/**
- * 提议的身份：**同一件事重跑不会产生第二条**。
- *
- * 它**刻意不含 `sourceRef`**。同一张卡片常常由多份来源共同支撑（同一份口径在两篇文档里
- * 都写了、一次排查与它的复盘各指一遍）—— 把来源算进身份，同一条提议就会按来源裂成
- * 好几条，人 review 时要在队列里连着点头三次，而且每次点的都是同一件事。
- *
- * 来源没有被丢掉：它是**多值**的。`sourceRef` 记「最先触发它的那一条」，
- * `sourceRefs` 累积全部触发它的来源（见 `upsert` 的合并规则）。
- */
-export declare function proposalIdOf(input: Pick<ProposalInput, 'action' | 'entityType' | 'entityId'>): string;
-/**
- * 内容指纹。
- *
- * 它只包含**会改变卡片内容的东西**（标题、正文、出处）：状态流转、时间戳不参与 ——
- * 否则一次无意义的写入就会让「拒绝过的那条」重新冒出来。
- */
-export declare function fingerprintOf(input: Pick<ProposalInput, 'entityType' | 'entityId' | 'title' | 'content' | 'sourceRefs'>): string;
-/** 卡片正文的指纹，用来发现「提议之后卡片又被人改过」。 */
-export declare function contentHashOf(content: string): string;
-export interface ProposalStoreHost {
-    /** 记忆段根（`<agentRoot>/memory/<库 id>`）。 */
-    memoryRoot: string;
-    /** 当前生效的卡片 schema。提议阶段与确认阶段各跑一遍校验。 */
-    schema: () => ProposalSchema;
-}
-export declare class CardProposalStore {
-    private readonly host;
-    constructor(host: ProposalStoreHost);
-    private get dir();
-    /** 全部提议，新的在前。读不动就返回空 —— 提议是可重建的待办，不是数据。 */
-    list(): Promise<CardProposal[]>;
-    get(id: string): Promise<CardProposal | undefined>;
-    pending(): Promise<CardProposal[]>;
-    /**
-     * 写入一批提议。返回真正**新增或更新**的那些（被指纹判重挡掉的不会出现在结果里）。
-     *
-     * 三条判重规则，按已有提议的状态分：
-     * - `pending`：原地更新（来源可能又长了一节，正文跟着变），保留 `createdAt`；
-     * - `confirmed` / `written`：指纹相同就跳过（人已经说过是了，不必再问一遍）；
-     * - `rejected`：指纹相同就跳过（不重复打扰人），**指纹变了才重新提**（知识确实变了）。
-     */
-    upsert(inputs: ProposalInput[]): Promise<CardProposal[]>;
-    /** 提议阶段的三层校验。缺字段 / 图断了 / 知识没用，各报各的。 */
-    private issuesOf;
-    /**
-     * 人点了「通过」。
-     *
-     * **确认与落卡是两件事**，所以这里只标状态、不写卡片：
-     * - 面板上的主操作是「确认并写入」，它先调这里再调 `writeCard`；
-     * - 副操作是「仅确认」，落卡交给 Agent 的 `write_knowledge_card`（它要求这条提议
-     *   已确认且尚未落卡）。两条路都过同一道门。
-     */
-    confirm(id: string, by: string, patch?: {
-        content?: string;
-        title?: string;
-        summary?: string;
-    }): Promise<CardProposal | undefined>;
-    /** 落卡成功之后回填。没有这一步，「已确认但没落卡」和「已经落卡了」分不开。 */
-    markWritten(id: string): Promise<CardProposal | undefined>;
-    /**
-     * 人点了「拒绝」。原因留档 —— 它同时是「下次不要再提同一条」的判据。
-     *
-     * 只有 `pending` 能被拒绝：一条已经确认（甚至已经落卡）的提议再被拒，会让
-     * 「卡片在库里、提议却是拒绝态」这种自相矛盾的状态出现在待办区里。
-     */
-    reject(id: string, reason: string, by: string): Promise<CardProposal | undefined>;
-    /** 删掉一条提议（清理用）。已落卡的提议删掉不影响卡片本身。 */
-    remove(id: string): Promise<boolean>;
-}
-//# sourceMappingURL=proposals.d.ts.map

package/lib/types/proposals.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"proposals.d.ts","sourceRoot":"","sources":["../../src/proposals.ts"],"names":[],"mappings":"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"}