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

package/lib/types/diagnosis/store.d.ts

@@ -1,29 +1,38 @@
-import { type AttributionCase } from './seed.js';
 import { type DiagnosisIssue } from './schema.js';
-import { cardPathOf, type DiagnosisCard } from './cards.js';
-import type { AttributionGraphData } from './types.js';
+import { type DiagnosisCard } from './cards.js';
+import type { AttributionCase, AttributionGraphData, DiagnosisRunRecord } from './types.js';
 import type { KnowledgeRuntime } from '../runtime.js';
 /** 读取顺序的显式来源，界面据此说明「现在看到的是哪一份」。 */
-export type DiagnosisSource = 'cards' | 'jsonl' | 'seed';
+export type DiagnosisSource = 'cards' | 'jsonl' | 'empty';
 export interface DiagnosisSnapshot {
     graph: AttributionGraphData;
     cases: AttributionCase[];
     issues: DiagnosisIssue[];
-    /** 数据是不是本次 ensure() 从 seed 写进去的。界面据此说明来源。 */
+    /** 数据是不是本次调用从内置示例写进去的（只有 `loadSample()` 会把它变成 true）。 */
     seeded: boolean;
     /** 旧知识根是否在本次被前向迁移成卡片。 */
     migrated: boolean;
     /** 读的是哪一份真相。 */
     source: DiagnosisSource;
-    /** 写卡片 / 迁移过程中发现的问题（写失败、迁移分歧）。必须能显示出来，不能只进日志。 */
+    /**
+     * 这个库还什么都没有 —— 界面据此显示空态（说什么会有、怎么开始），
+     * 而不是画一张空图。
+     */
+    canLoadSample: boolean;
+    /** 写卡片 / 迁移 / 读诊断日志过程中发现的问题。必须能显示出来，不能只进日志。 */
     problems: string[];
 }
-/** 只取运行时里真正要用的三件事：读根目录、落 SourceRaw、写卡片。 */
-type DiagnosisHost = Pick<KnowledgeRuntime, 'rootDir' | 'addSource' | 'writeCard'>;
+/**
+ * 只取运行时里真正要用的那几件事：读根目录、落 SourceRaw、写卡片、列来源。
+ *
+ * `loadSources` 是 v1.1 新增的：一次排查的产物现在是一条 `agent_diagnosis_case`
+ * 的 SourceRaw，归因图读的是它，而不是自造的 jsonl。
+ */
+type DiagnosisHost = Pick<KnowledgeRuntime, 'rootDir' | 'addSource' | 'writeCard' | 'loadSources'>;
 export declare class DiagnosisStore {
     private readonly host;
     constructor(host: DiagnosisHost);
-    private get dir();
+    private get legacyDir();
     private get cardsDir();
     /**
      * 幂等初始化。三种状态各自处理，互不覆盖：
@@ -32,27 +41,82 @@ export declare class DiagnosisStore {
      * 2. 没有卡片但有旧 jsonl → **前向迁移**：把旧图反推成卡片写出去，并**校验迁移无损**
      *    （重新编译一遍与旧图比对，不一致就不认这次迁移，继续按 jsonl 读 —— 宁可留在旧形态，
      *    也不要静默丢知识）；
-     * 3. 两者都没有 → 首次启动：先落手册与复盘的 SourceRaw，再把 seed 编译成卡片。
+     * 3. 两者都没有 → **什么都不写**。这个库还没开始做排查。
+     *
+     * 第 3 条原来是自动写入内置示例。实跑反馈把它改掉了：那份示例长得像真的业务文档，
+     * 而它落在用户自己的 `01_source_raw/` 与 `02_wiki/` 里 —— 新装一台机器，一打开
+     * 「智能归因」就凭空多出几份来源和几十张卡片。示例还在（`loadSample()`），
+     * 但改成**用户点一下才载入**。
+     *
+     * **v1.1 起连模板文件也不铺了**：模板卡由类型定义派生（0021 §6.6），落成磁盘文件会
+     * 造出「设置里改了、磁盘上那份没改」的第二真源。
      */
     ensure(): Promise<{
         seeded: boolean;
         migrated: boolean;
         problems: string[];
     }>;
+    /**
+     * 载入**内置示例**：一份排查手册 + 三篇复盘 + 三次排查日志 → SourceRaw → 卡片 → 图。
+     *
+     * 只有用户明确点了「载入内置示例」才走这里（`ensure()` 不再自动调用）。幂等：
+     * `addSource` 按 `externalId`、`writeCard` 按 entityId，点两次不会写出第二份。
+     *
+     * **它走的是「提议 → 确认」那条门，不是绕过它**（0021 §6.1）。区别只在确认者是谁：
+     * 用户点「载入内置示例」这个动作本身就是**对整批示例的确认**，所以这里给每条提议记下
+     * `confirmedBy = user:load-sample`，然后照常走 `writeCard`。这样做的两个好处：
+     * 待办区里能看到这批卡片是怎么来的；而「未确认不落 `02_wiki/`」这条规则没有被开一个
+     * 后门 —— 例外是**确认者的身份**，不是门的缺失。
+     */
+    loadSample(): Promise<{
+        seeded: boolean;
+        migrated: boolean;
+        problems: string[];
+    }>;
     snapshot(): Promise<DiagnosisSnapshot>;
     /**
-     * 图。
+     * 图 = **卡片那张图** + **一次排查的产物**。
      *
-     * 有卡片：`cardsToGraph(卡片)` + 一次排查的产物；没有卡片：按旧 jsonl 读。
-     * 两条路径都返回同一种形状，调用方不需要知道现在是哪一代。
+     * 两条来源严格分工：类型层与引用层（以及六种卡片边）全部来自卡片；`evidence` / `cause`
+     * 与四条执行边全部来自 `agent_diagnosis_case` 的 SourceRaw。合成一张图是**读**的时候
+     * 做的，不是写的时候 —— 写的时候合成，等于让一次执行的结果变成可复用的知识。
      */
+    private buildGraph;
+    /**
+     * 旧 `05_diagnosis/` 里的执行产物：`evidence.jsonl` / `causes.jsonl` / `edges.jsonl`。
+     *
+     * 只取**执行边**：卡片边由卡片投影出来，这里再读一遍就会出现重复边。同时按 id 去重
+     * —— 已经由 `agent_diagnosis_case` 解析出来的节点不重复加（新旧两代可能描述同一次排查）。
+     */
+    private readLegacyRunArtifacts;
     readGraph(): Promise<AttributionGraphData>;
     readCases(): Promise<AttributionCase[]>;
     /** 读 `02_wiki/diagnosis/**` 下的全部卡片。解析不出来的文件按「不是卡片」跳过。 */
     readCards(): Promise<DiagnosisCard[]>;
-    /** 写一批卡片。返回写失败的原因（schema 不认、出处不存在等），由调用方决定怎么显示。 */
-    private writeCards;
-    private seed;
+    /**
+     * 读全部 `agent_diagnosis_case` 来源，解析出排查记录。
+     *
+     * 块坏了、`runId` 缺了、`symptomId` 缺了就**跳过并如实报问题** —— 不猜。
+     * 一条坏日志不该让整张图读不出来，但它也不能被静默吞掉。
+     */
+    readRuns(): Promise<{
+        records: DiagnosisRunRecord[];
+        problems: string[];
+    }>;
+    /**
+     * 一次排查结束：写一条 `agent_diagnosis_case` 的 SourceRaw，并**直接写入**一张案例卡片。
+     *
+     * 0044：案例卡片原来只提议、等人确认。与编译那条链路一样改成直接入库 ——
+     * 一次排查的价值就在于「当时是怎么走的」，让它停在待办队列里等于把经验丢掉。
+     * 卡片会被标成 `unreviewed`，人在「知识库 → Wiki」里 review 它。
+     *
+     * 幂等：`externalId` = runId，同一次排查重跑不会写出第二条来源；卡片按 entityId 写入。
+     */
+    recordRun(record: DiagnosisRunRecord): Promise<{
+        sourceId?: string;
+        entityId?: string;
+        problems: string[];
+    }>;
     private migrate;
     /**
      * 落原始材料。
@@ -61,21 +125,27 @@ export declare class DiagnosisStore {
      * `addSource` 用 `externalId` 幂等，所以重复调用不会写出第二份。
      */
     private writeSources;
-    private readRunArtifacts;
-    private writeRunArtifacts;
-    /** 旧版的类型层快照。首次 seed 时也写一份：它让 `05_diagnosis/` 仍是一份可读的完整快照。 */
-    private writeLegacySnapshot;
+    /**
+     * 写一批卡片。返回写失败的原因（类型不认、出处不存在等），由调用方决定怎么显示。
+     *
+     * 0044：**直接写**，不再先提一条提议再确认再落卡。`confirmedBy` 现在只是一个
+     * 归因用的标签（载入示例时是 `user:load-sample`，迁移时是迁移逻辑），不再是准入凭证 ——
+     * 凭证这道门已经不存在了。留它是因为它进 `writeCard` 的 lineage 留痕，
+     * 而「这张卡片是哪一次动作产生的」仍然值得回答。
+     */
+    private writeCards;
+    private readLegacyCases;
     private readLegacyGraph;
     /**
      * 是否存在**值得迁移的旧知识根**。
      *
-     * 只看旧版的**类型层**分片，而且要求它真的有内容：`ensure()` 自己会为一次排查的产物
-     * （`evidence.jsonl` 等）建空占位文件 —— 若把空文件也算成「旧知识根」，首次启动会走进
-     * 迁移分支，然后在空图上白跑一趟。
+     * 只看旧版的**类型层**分片，而且要求它真的有内容：空文件不算「旧知识根」，
+     * 否则首次启动会走进迁移分支，然后在空图上白跑一趟。
      */
     private legacyShardFiles;
     private readLines;
-    private writeIfAbsent;
 }
-export { cardPathOf };
+/** 卡片正文：小节 + 结构化块。复用编解码里的同一套序列化，避免两处格式漂移。 */
+export declare function renderCardBody(card: DiagnosisCard): string;
+export {};
 //# sourceMappingURL=store.d.ts.map

package/lib/types/diagnosis/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/diagnosis/store.ts"],"names":[],"mappings":"AAEA,OAAO,EAA0B,KAAK,eAAe,EAAE,MAAM,WAAW,CAAA;AAExE,OAAO,EAAuD,KAAK,cAAc,EAAE,MAAM,aAAa,CAAA;AACtG,OAAO,EACS,UAAU,EACR,KAAK,aAAa,EACnC,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAmB,oBAAoB,EAAwC,MAAM,YAAY,CAAA;AAC7G,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AA0DrD,mCAAmC;AACnC,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAA;AAExD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,oBAAoB,CAAA;IAC3B,KAAK,EAAE,eAAe,EAAE,CAAA;IACxB,MAAM,EAAE,cAAc,EAAE,CAAA;IACxB,6CAA6C;IAC7C,MAAM,EAAE,OAAO,CAAA;IACf,yBAAyB;IACzB,QAAQ,EAAE,OAAO,CAAA;IACjB,gBAAgB;IAChB,MAAM,EAAE,eAAe,CAAA;IACvB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,2CAA2C;AAC3C,KAAK,aAAa,GAAG,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,CAAC,CAAA;AAElF,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,aAAa;IAEhD,OAAO,KAAK,GAAG,GAAkD;IACjE,OAAO,KAAK,QAAQ,GAAqE;IAEzF;;;;;;;;OAQG;IACG,MAAM,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAiB7E,QAAQ,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAoC5C;;;;;OAKG;IACG,SAAS,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAU1C,SAAS,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAY7C,yDAAyD;IACnD,SAAS,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAS3C,mDAAmD;YACrC,UAAU;YAoBV,IAAI;YAYJ,OAAO;IA4BrB;;;;;OAKG;YACW,YAAY;YAkBZ,gBAAgB;YAkBhB,iBAAiB;IAW/B,6DAA6D;YAC/C,mBAAmB;YAUnB,eAAe;IAe7B;;;;;;OAMG;YACW,gBAAgB;YAQhB,SAAS;YAMT,aAAa;CAM5B;AAsED,OAAO,EAAE,UAAU,EAAE,CAAA"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/diagnosis/store.ts"],"names":[],"mappings":"AAIA,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAA;AACpE,OAAO,EAEW,KAAK,aAAa,EACnC,MAAM,YAAY,CAAA;AAEnB,OAAO,KAAK,EACV,eAAe,EAAmB,oBAAoB,EAAwC,kBAAkB,EACjH,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAmDrD,mCAAmC;AACnC,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAA;AAEzD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,oBAAoB,CAAA;IAC3B,KAAK,EAAE,eAAe,EAAE,CAAA;IACxB,MAAM,EAAE,cAAc,EAAE,CAAA;IACxB,wDAAwD;IACxD,MAAM,EAAE,OAAO,CAAA;IACf,yBAAyB;IACzB,QAAQ,EAAE,OAAO,CAAA;IACjB,gBAAgB;IAChB,MAAM,EAAE,eAAe,CAAA;IACvB;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAA;IACtB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;;;GAKG;AACH,KAAK,aAAa,GAAG,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,aAAa,CAAC,CAAA;AAElG,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,aAAa;IAEhD,OAAO,KAAK,SAAS,GAAyD;IAC9E,OAAO,KAAK,QAAQ,GAAqE;IAEzF;;;;;;;;;;;;;;;;OAgBG;IACG,MAAM,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAMnF;;;;;;;;;;;OAWG;IACG,UAAU,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAOjF,QAAQ,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAsC5C;;;;;;OAMG;YACW,UAAU;IAgCxB;;;;;OAKG;YACW,sBAAsB;IAiB9B,SAAS,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAM1C,SAAS,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAQ7C,yDAAyD;IACnD,SAAS,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAW3C;;;;;OAKG;IACG,QAAQ,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,kBAAkB,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAYhF;;;;;;;;OAQG;IACG,SAAS,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;YA4BpG,OAAO;IAgCrB;;;;;OAKG;YACW,YAAY;IAkB1B;;;;;;;OAOG;YACW,UAAU;YAqBV,eAAe;YAQf,eAAe;IAgB7B;;;;;OAKG;YACW,gBAAgB;YAQhB,SAAS;CAKxB;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAG1D"}