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

package/src/client/WikiFlowCard.tsx

@@ -1,120 +1,93 @@
 /**
- * 「Wiki 抽取流程」卡片（issue 0024 的流程说明）。
+ * 「Wiki 抽取流程」卡片（issue 0024；0049 重写文案）。
  *
- * 它把"原文件 → Wiki 卡片"这段**单文档抽取**画成四个阶段，并明确标出每一段的
- * 实现状态——**没有实现的不画成已实现**：这张图是给人看的契约，不是宣传。
+ * 它把「原文件 → Wiki 卡片」画成四段。**这张图是给人看的契约**，所以 0049 做了三件
+ * 与内容有关的事：
  *
- * 与腾讯 WeKnora 四阶段 Map-Reduce 的对应关系写在每一段的"对应 WeKnora"一行里：
- * 我们是**单文档**抽取，所以它的「批内 Taxonomy 规划」退化成「按库复用已有类型」，
- * 「Pass 1..N 分块引文」在文档不长时与候选抽取合并成一次调用。
+ * 1. **段名改成动作**（抽取实体 / 合并实体 / 写入 wiki / 编译结果）。原来的
+ *    `Pass 0` / `归一` / `落卡` / `Finalize` 是实现的内部词，人得先学一遍才知道在说什么。
+ * 2. **撤掉状态徽标**（已实现 / 部分实现 / 待实现）。四段都实现了，徽标只剩下噪音；
+ *    哪一格真的没做完，由「架构」那一页统一说，不在这一张卡上重复一遍。
+ * 3. **删掉实现细节**（指纹、slug 命名空间、图上的边叫什么、WeKnora 的四段对应），
+ *    只留「这一段吃什么、吐什么、做哪几件事」。要看细节有 README 与架构页。
  */
 
 import type { ReactNode } from 'react'
 import {
   ArrowDown, Box, Check, FileText, GitBranch, Layers3, RefreshCw, ShieldCheck, Sparkles, Wrench,
 } from '@tita-data-agent/ui/icons'
-import { Badge, Card, cn } from '@tita-data-agent/ui/components'
+import { Card, cn } from '@tita-data-agent/ui/components'
 import { styles } from './styles.ts'
 
-type StageStatus = 'done' | 'partial' | 'todo'
-
 interface Stage {
   id: string
   icon: typeof FileText
   tone: 'blue' | 'violet' | 'green' | 'amber'
-  pass: string
-  title: string
+  /** 段名：**动词**，不是实现里的 pass 名。 */
+  name: string
   /** 这一段的输入 → 输出。 */
   io: string
-  /** 这一段做什么（要点，`**…**` 会被渲染成粗体）。 */
+  /** 这一段做哪几件事（`**…**` 会被渲染成粗体）。 */
   body: string[]
-  /** 是否调用模型。 */
-  llm: boolean
-  /** 与 WeKnora 四阶段的对应关系。 */
-  weknora: string
-  status: StageStatus
-  statusNote: string
+  /** 这一段的模型参与情况，一句话。 */
+  model: string
 }
 
 const STAGES: Stage[] = [
   {
-    id: 'candidates',
+    id: 'extract',
     icon: Sparkles,
     tone: 'violet',
-    pass: 'Pass 0',
-    title: '候选抽取：实体 / 概念 / 关系',
-    io: '一个 SourceRaw → 候选项列表',
+    name: '抽取实体',
+    io: '一份原始文档 → 实体清单',
     body: [
-      '每个候选项的身份是**三件事一起定**：类型 + 名称（slug）+ 证据分块。类型与名称必须同时决定，因为 slug 的命名空间就是 `<类型>/<名称>`。',
-      '关系抽两处：卡片之间的 wiki 链接（正文里的 `[[类型/名称|标题]]`），以及实体之间的**图谱边**（`03_compiled/knowledge_graph.json`，目前只有 `supported_by` 溯源边）。',
-      '**slug 稳定性**：文档里提到的实体如果已有对应页面，复用它的 slug，不要另起一个近义 slug。',
+      '模型按卡片类型的**必填小节与字段**写正文，并给一句话摘要。',
+      '规则同时跑一遍：抓小节标题、正文里的 `[[链接]]`，以及文档自己声明的关系。',
+      '模型不可用时整段退回规则抽取，并在报告里说清原因 —— 不静默降级。',
     ],
-    llm: false,
-    weknora: '对应它的 Pass 0（抽 entities + concepts，强制复用已有 slug）。',
-    status: 'partial',
-    statusNote: '已实现**规则抽取**（正文标题、[[链接]]、frontmatter 的 candidates / entities / concepts / relations），编译时自动跑、增量跳过没变的来源；模型驱动的候选工具（propose_wiki_cards）还没有 —— 所以「抽什么」目前由文档结构决定，不是由模型判断。',
+    model: '模型 + 规则',
   },
   {
-    id: 'normalize',
+    id: 'merge',
     icon: GitBranch,
     tone: 'blue',
-    pass: '归一',
-    title: '与已有 Wiki 合并：同指一物就复用',
-    io: '候选项列表 + 库内已有卡片 → 去重后的落点',
+    name: '合并实体',
+    io: '实体清单 + 库里已有的卡片 → 落点',
     body: [
-      '**判重按 slug 与别名，不按标题字符串**：标题可以改，slug 是稳定标识。',
-      '核心原则是「**相关 ≠ 相同**」——相关的话题不要合并，只有同指一物才合并。',
-      '命中已有 → 记下"增量合并到该页"；没命中 → 记下"新建"。',
-      'WeKnora 的「批内 Taxonomy 规划」在单文档场景退化成**库内复用**：优先沿用已有的类型与命名，不为了一个新页面另起一套。',
+      '**同指一物就并进已有卡片**，不新建。判据是类型 + 名称 / 标题 / 别名。',
+      '模型再判一次语义：同一件东西换个说法，不该落成两张卡。',
+      '**相关 ≠ 相同**：只是相关的话题不合并，关系另走图谱。',
     ],
-    llm: false,
-    weknora: '对应它的 Taxonomy 规划 + WikiDeduplicationPrompt（related ≠ same）；批内统筹改为库内复用。',
-    status: 'done',
-    statusNote: '已实现：按 entityId / title / metadata.aliases 建别名索引判重，同指一物就合并 source_refs（重复的出处不会写第二遍），关系候选不参与合并。',
+    model: '模型 + 规则',
   },
   {
     id: 'write',
     icon: FileText,
     tone: 'green',
-    pass: '落卡',
-    title: '写卡片：命中的增量合并，没命中的按模板新建',
+    name: '写入 wiki',
     io: '落点 + 证据 → 02_wiki/<类型>/<id>.md',
     body: [
-      '必须带 `source_refs`，且每个来源都要真实存在（写了不存在的来源会被直接拒绝）。',
-      '必填小节与必填字段按**类型 schema** 填；缺了要么被拒（严格模式）要么标成待补（report 模式）。',
-      '新建的卡片是 `unreviewed`，不自动当成已审核的知识。',
-      '正文必须**严格接地**：只写证据里有的东西，去重，不写自链接。',
+      '**直接入库**，状态是未审核 —— 入库在前、审核在后，不需要谁先确认。',
+      '缺必填小节或字段也照写，只在卡片上标成「待补」。',
+      '每个来源都必须真实存在；**正文只读**，编译追加，人只能加备注。',
     ],
-    llm: true,
-    weknora: '对应它的 Reduce：按 slug 增量合并页面，提示词硬约束接地 / 禁幻觉 / 去重 / 禁自链接。',
-    status: 'done',
-    statusNote: '已实现：write_knowledge_card + 类型 schema 与三层校验（0024）',
+    model: '编译落盘',
   },
   {
-    id: 'finalize',
+    id: 'compile',
     icon: Wrench,
     tone: 'amber',
-    pass: 'Finalize',
-    title: '收尾：索引、死链、交叉链接、质检',
-    io: '02_wiki → wikiNotes / 图谱 / 待补清单',
+    name: '编译结果',
+    io: '卡片 → 召回单元 / 图谱 / 索引页',
     body: [
-      '重建索引页、清理死链、补交叉链接——这几步**不调用模型**，纯靠规则与图算法。',
-      '跑三层校验（format / reference / semantic），产出"待补 N 张"清单，人可以按清单补。',
-      '之后才轮到编译：卡片 → wikiNotes → 向量 + 图谱。',
+      '切召回单元：长卡片按小节切开，图片跟着讲它的那一段走。',
+      '装配图谱：卡片到来源的溯源边，以及卡片之间的关系边。',
+      '给每张卡片补一块「相关」，把断链写成引用问题，并写一份索引页。',
     ],
-    llm: false,
-    weknora: '对应它的 Finalize（重建索引 / 清死链 / 补交叉链接，纯 SQL + 图算法）。',
-    status: 'partial',
-    statusNote: '部分实现：三层质检已实现；索引页 / 死链 / 交叉链接待实现',
+    model: '不调模型',
   },
 ]
 
-const STATUS_META: Record<StageStatus, { label: string; tone: 'success' | 'warning' | 'neutral' }> = {
-  done: { label: '已实现', tone: 'success' },
-  partial: { label: '部分实现', tone: 'warning' },
-  todo: { label: '待实现', tone: 'neutral' },
-}
-
 const TONE_CLASS: Record<Stage['tone'], string> = {
   blue: styles.wikiFlowBlue,
   violet: styles.wikiFlowViolet,
@@ -122,22 +95,22 @@ const TONE_CLASS: Record<Stage['tone'], string> = {
   amber: styles.wikiFlowAmber,
 }
 
-/** 三条判定规则 —— 对应"抽取 → 判类型 → 看是否已存在"这三步，但顺序与判据都被钉死。 */
+/** 三条判定规则。它们决定了卡片会不会被拆成两张，所以常驻在这一屏。 */
 const RULES: Array<{ order: string; title: string; body: string }> = [
   {
     order: '1',
-    title: '类型在抽取时就要定，不能留到最后再判',
-    body: '候选项的身份是「类型 + 名称 + 证据」。slug 的命名空间是 `<类型>/<名称>`，类型晚定一步，slug 就得重算一次。',
+    title: '类型在抽取时就要定',
+    body: '卡片的身份是「类型 + 名称」。类型晚定一步，名称就得重算一次。',
   },
   {
     order: '2',
-    title: '类型只能来自注册表，**不命中不要自创**',
-    body: '自创一个类型等于这张卡片没有 schema：没有必填小节、没有模板、校验不了。都不命中时落到 `concept`，或先在「Wiki 类型」里把它登记成正式类型再抽。',
+    title: '类型只能来自注册表',
+    body: '不命中就落 `concept`，不要自创 —— 自创等于这张卡片没有 schema。',
   },
   {
     order: '3',
-    title: '「是否已存在」按 slug 与别名判，不按标题',
-    body: '命中的走**增量合并**（旧版本先快照，回滚本身也可回滚），没命中的才新建 `draft`。相关不等于相同：别把相近的话题并成一条。',
+    title: '判重按名称与别名，不按标题',
+    body: '标题可以改，名称是稳定标识。相关不等于相同：相近的话题不要合并。',
   },
 ]
 
@@ -150,13 +123,11 @@ export function WikiFlowCard(): ReactNode {
   return <Card className={styles.kbCard}>
     <div className={styles.kbCardHead}>
       <div><h3><RefreshCw size={13} />Wiki 抽取流程（原文件 → Wiki）</h3></div>
-      <span className={styles.kbCount}>4 段 · 目前没有一段由管线自己调模型</span>
+      <span className={styles.kbCount}>4 段</span>
     </div>
     <p className={styles.kbHint}>
-      单文档抽取的完整链路。<b>与已落库的卡片合并是这条链路的中心</b>——它决定这次是"新建一页"还是"补进已有页面"，
-      也决定 slug 能不能稳定下来。状态徽标按代码现状标注：没实现的不画成已实现。
-      前两段现在由编译管线用**规则**完成（编译时自动跑，正文没变的来源按指纹跳过）；
-      设计里那两次模型调用（候选抽取工具、归一提示词）还没有，所以这两段标的是「部分实现」。
+      一份文档变成卡片要走的四段。<b>合并是这条链路的中心</b>：它决定这次是新建一页还是补进已有页面。
+      四段都在编译时自动跑，正文没变的来源按指纹跳过。
     </p>
 
     <div className={styles.wikiFlow}>
@@ -164,28 +135,23 @@ export function WikiFlowCard(): ReactNode {
         <FileText size={14} />
         <span>
           <strong>SourceRaw</strong>
-          <small>01_source_truth/*.md — 原始可追溯文档，本身不进召回</small>
+          <small>01_source_raw/*.md — 原始文档，本身不进召回</small>
         </span>
       </div>
 
-      {STAGES.map(stage => {
+      {STAGES.map((stage, index) => {
         const Icon = stage.icon
-        const status = STATUS_META[stage.status]
         return <div className={styles.wikiFlowStageWrap} key={stage.id}>
           <span className={styles.wikiFlowArrow} aria-hidden="true"><ArrowDown size={14} /></span>
           <div className={cn(styles.wikiFlowStage, TONE_CLASS[stage.tone])}>
             <div className={styles.wikiFlowStageHead}>
-              <span className={styles.wikiFlowPass}><Icon size={13} />{stage.pass}</span>
-              <strong>{stage.title}</strong>
-              <Badge tone={status.tone}>{status.label}</Badge>
-              <span className={styles.wikiFlowLlm}>{stage.llm ? '调用模型' : '不调用模型'}</span>
+              <span className={styles.wikiFlowPass}><Icon size={13} />{index + 1} · {stage.name}</span>
+              <span className={styles.wikiFlowLlm}>{stage.model}</span>
             </div>
             <p className={styles.wikiFlowIo}>{stage.io}</p>
             <ul className={styles.wikiFlowBody}>
               {stage.body.map(line => <li key={line}>{rich(line)}</li>)}
             </ul>
-            <p className={styles.wikiFlowNote}><b>对应 WeKnora：</b>{stage.weknora}</p>
-            <p className={styles.wikiFlowNote}>{stage.statusNote}</p>
           </div>
         </div>
       })}
@@ -194,7 +160,7 @@ export function WikiFlowCard(): ReactNode {
       <div className={styles.wikiFlowSink}>
         <Layers3 size={14} />
         <span>
-          <strong>Wiki 卡片 → wikiNotes → 向量 / 图谱</strong>
+          <strong>Wiki 卡片 → 召回单元 / 向量 / 图谱</strong>
           <small>02_wiki/&lt;类型&gt;/&lt;id&gt;.md → 03_compiled/* — 召回单元在编译段才产生</small>
         </span>
       </div>
@@ -213,11 +179,7 @@ export function WikiFlowCard(): ReactNode {
 
     <div className={styles.wikiFlowDiff}>
       <Box size={13} />
-      <span>
-        WeKnora 是<b>知识库级后台管道</b>（Redis 队列 + 每 KB 并发治理 + Neo4j），本仓库不照抄：
-        模型调用一律经 Agent，所以前两段由工具驱动、由人复核。<b>抽取粒度</b>
-        （focused / standard / exhaustive）这个旋钮值得抄——它把"抽多少"变成用户能理解的东西。
-      </span>
+      <span>四段与腾讯 WeKnora 的 Map-Reduce 四段对应。差别在单文档：它的批内统筹退化成按库复用已有类型，它的后台管道（队列 + 图数据库）不照抄 —— 模型调用一律经 Agent。</span>
     </div>
   </Card>
 }