@sparkelf/dsh-knowledge-base 0.1.24 → 0.1.26

package/lib/types/graphTypes.d.ts

@@ -0,0 +1,170 @@
+/**
+ * The read-only knowledge-graph shape shared by the Host scanner and the browser.
+ *
+ * A graph is an ordinary knowledge folder: `<scope>/知识图谱/<graph>/` with one
+ * visible sub-folder per topic and the relation documents under `.kg/links/`. The
+ * graph tab therefore speaks a DOMAIN model (scope → graph → topic) rather than the
+ * file tree's path model. Keeping the shape in one dependency-free module is what
+ * lets the Host build it and the canvas page render it without a second translation
+ * layer that could disagree about a field name.
+ *
+ * Paths here are VIEW-relative (`global/知识图谱/…`, `department/…`,
+ * `personal/知识图谱/…`): the personal owner segment is deliberately absent, exactly
+ * as the file tree shows it. The Host resolves the authoritative path first; the
+ * browser never needs to know the caller's uid.
+ *
+ * @module @sparkelf/dsh-knowledge-base/graph-types
+ */
+/** The folder name that marks a knowledge graph inside a scope. */
+export declare const KNOWLEDGE_GRAPH_FOLDER = "\u77E5\u8BC6\u56FE\u8C31";
+/** The hidden folder inside a graph that holds the relation documents. */
+export declare const KNOWLEDGE_GRAPH_META_FOLDER = ".kg";
+/** The trash folder `kg_del` moves topics into; never a topic itself. */
+export declare const KNOWLEDGE_GRAPH_TRASH_FOLDER = "_trash";
+/** One document inside a topic folder, as the detail panel lists it. */
+export interface KnowledgeGraphDocument {
+    /** Human title: the document's first H1, else the file name without extension. */
+    title: string;
+    /** File name alone, relative to the topic folder. */
+    file: string;
+    /** View-relative path, for opening the document from a future write surface. */
+    path: string;
+    /** ISO-8601 date (`YYYY-MM-DD`) from the file's modification instant. */
+    date?: string;
+    /** First paragraph after the H1, when the file has one. */
+    summary?: string;
+}
+/** One topic: a visible folder whose `index.md` is its card. */
+export interface KnowledgeGraphTopic {
+    /** Identity the relation documents reference. Front matter `id`, else folder name. */
+    id: string;
+    /** Card title. Front matter `title`, else the folder name. */
+    title: string;
+    /** Lifecycle state the prototype's cards colour. */
+    status: string;
+    /** 1–5 progress dots on the card. */
+    depth: number;
+    /** Optional grouping label shown as the first tag. */
+    domain?: string;
+    /** Remaining card tags. */
+    tags: string[];
+    /** First paragraph after the H1, shown on the card and in the detail panel. */
+    summary: string;
+    /** Free body from the card, H1 and summary removed; the detail panel renders it. */
+    body: string;
+    /** Visible folder name. */
+    folder: string;
+    /** View-relative topic folder path. */
+    path: string;
+    /** Documents beside `index.md`. */
+    documents: KnowledgeGraphDocument[];
+}
+/** One relation document under `<graph>/.kg/links/`. */
+export interface KnowledgeGraphLink {
+    /** Topic id at one end. */
+    a: string;
+    /** Topic id at the other end. */
+    b: string;
+    /** Short edge label; the canvas falls back to `a ↔ b` when absent. */
+    label?: string;
+    /** ISO-8601 date from front matter or the file. */
+    updated?: string;
+    /** First body paragraph, shown when the relation pill is opened. */
+    body: string;
+    /** File name under `<graph>/.kg/links/`, used by the Host-side del tool. */
+    file?: string;
+}
+/** One graph node under a scope. */
+export interface KnowledgeGraphNode {
+    /** Stable view-relative folder path; unique across the tree. */
+    id: string;
+    /** Display name: the graph folder's name. */
+    name: string;
+    /** Scope the graph lives in. */
+    scope: KnowledgeGraphScopeKey;
+    /** View-relative graph folder path. */
+    path: string;
+    /** Department display chain for a department graph, empty for the other scopes. */
+    group: string;
+    /** Topics in folder order. */
+    topics: KnowledgeGraphTopic[];
+    /** Relations whose two ends both resolve to topics in this graph. */
+    links: KnowledgeGraphLink[];
+    /** What the header states beside the breadcrumb. */
+    counts: {
+        topics: number;
+        links: number;
+        documents: number;
+    };
+    /**
+     * Authoritative path relative to the knowledge root, used by Host-side graph
+     * tools. Stripped before the tree is sent to the browser.
+     */
+    actualPath?: string;
+}
+/** One group inside a scope: the department chain for 部门, empty elsewhere. */
+export interface KnowledgeGraphGroup {
+    /** Stable key (the department code chain), empty for a flat scope. */
+    key: string;
+    /** Display label (department names, joined by ` / `). */
+    label: string;
+    /** Graphs directly in this group. */
+    graphs: KnowledgeGraphNode[];
+}
+/** One of the three knowledge scopes. */
+export type KnowledgeGraphScopeKey = 'global' | 'department' | 'personal';
+/** One scope level of the graph tree. */
+export interface KnowledgeGraphScope {
+    key: KnowledgeGraphScopeKey;
+    /** Groups under the scope; a flat scope carries one group with an empty key. */
+    groups: KnowledgeGraphGroup[];
+}
+/** The caller identity the tree names, without credentials. */
+export interface KnowledgeGraphCaller {
+    /** Stable user id, for tests and for a future owner label. */
+    userId: string;
+    /** Human label from DataOps. */
+    label: string;
+    /** The caller's organization chain, root first, when the backend reported one. */
+    departmentPathCodes?: string[];
+    /** Index-aligned display names for {@link departmentPathCodes}. */
+    departmentPathNames?: string[];
+}
+/**
+ * What `GET /knowledge-base/api/graph` answers.
+ *
+ * `scanned` counts graph folders the Host saw on disk; `visible` counts the ones
+ * that passed `canReadPath`; `denied` is the difference. The names of denied graphs
+ * never leave the Host, which is why this is counts rather than a refused list.
+ */
+export interface KnowledgeGraphTree {
+    scopes: KnowledgeGraphScope[];
+    caller: KnowledgeGraphCaller;
+    /**
+     * Authoritative knowledge root the scanner read.
+     *
+     * Returned for a future write surface that must reuse the Host's own resolver
+     * instead of building `personal/<uid>/…` in the browser. The panel already shows
+     * this value in its status header, so naming it here adds no disclosure.
+     */
+    actualRoot: string;
+    scanned: number;
+    visible: number;
+    denied: number;
+}
+/** An empty tree, for the loading and failure states. */
+export declare function emptyKnowledgeGraphTree(): KnowledgeGraphTree;
+/** Flatten the tree into the list the canvas page consumes. */
+export declare function knowledgeGraphsOf(tree: KnowledgeGraphTree): KnowledgeGraphNode[];
+/**
+ * Whether a graph or one of its topics matches the tree's in-place filter.
+ *
+ * This narrows what the Host already returned; it is not a permission filter and
+ * must never be used as one. Exported so the rule can be tested without rendering
+ * the tree.
+ *
+ * @param graph - one permission-filtered graph.
+ * @param needle - already lower-cased filter term.
+ * @returns true when the graph name or a topic title contains the term.
+ */
+export declare function knowledgeGraphMatches(graph: KnowledgeGraphNode, needle: string): boolean;

package/lib/types/index.d.ts

@@ -1044,6 +1044,8 @@ export declare const KNOWLEDGE_SKILL_NAME = "knowledge-base";
 export declare const KB_SUMMARIZE_SKILL_NAME = "kb-summarize";
 /** Third bundled skill: explicit document/directory vectorization. */
 export declare const KB_VECTORIZE_SKILL_NAME = "kb-vectorize";
+export declare const KNOWLEDGE_GRAPH_SKILL_NAME = "knowledge-graph";
+export declare const KNOWLEDGE_GRAPH_SKILL_DESCRIPTION = "\u8BFB\u5199\u56E2\u961F\u77E5\u8BC6\u5E93\u91CC\u7684\u77E5\u8BC6\u56FE\u8C31\uFF1A\u4E3B\u9898\u5361\u3001\u5173\u7CFB\u6587\u6863\u4E0E\u56DB\u4E2A\u52A8\u4F5C\u3002";
 /**
  * Short description shown in the skill list.
  *
@@ -1084,6 +1086,8 @@ export declare function knowledgeSkillPath(): string;
 export declare function kbSummarizeSkillPath(): string;
 /** Where the bundled `kb-vectorize` skill lives. */
 export declare function kbVectorizeSkillPath(): string;
+/** Where the bundled `knowledge-graph` skill lives. */
+export declare function knowledgeGraphSkillPath(): string;
 /**
  * Where this package's tutorial document lives, from either build layout.
  *

package/lib/types/views.d.ts

@@ -838,6 +838,16 @@ export interface KnowledgeAuditEntry {
     relPath: string;
     /** For a move, the destination path. */
     toRelPath?: string;
+    /** Model-facing tool that performed the action, when one did. */
+    tool?: string;
+    /** Graph the action belongs to, when the action is a graph operation. */
+    graphId?: string;
+    /** Topic id inside the graph, when the action names one. */
+    topicId?: string;
+    /** Short human intent (`new topic`, `move-to-trash`, ...). */
+    intent?: string;
+    /** One-line description of what changed, for review. */
+    diffSummary?: string;
     /**
      * Extra detail for actions that have more than one flavour.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sparkelf/dsh-knowledge-base",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "DataOps-backed knowledge base for DeepSeek Harness: a left-sidebar destination, Settings configuration, and index tooling over a mounted NAS view.",
   "type": "module",
   "main": "./lib/index.js",

package/skills/knowledge-graph/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: knowledge-graph
+description: 读写团队知识库里的知识图谱：主题卡、关系文档、四个动作和五个剧本。
+---
+
+# knowledge-graph
+
+知识图谱是知识库的导航层，不是第二套文档库。它只有三样东西：**图谱**（一个可见文件夹）、**主题**（图谱下的可见子文件夹 + `index.md` 卡）、**关系**（`index.md` 之间的一篇文档）。
+
+## 1. 目录长什么样
+
+```text
+<scope>/知识图谱/<graph>/
+  <主题>/
+    index.md                 # 主题卡：front-matter + 摘要 + 自由正文
+    <document>.md            # 文档，知识库能搜、能预览、能分享
+  .kg/
+    links/<a>--<b>.md        # 关系文档，点开头，KB 文件树和 FTS 跳过
+```
+
+- `<scope>` 是 `global` / `department/<部门链>` / `personal/<uid>`；个人路径由 Host 解析，**不要让模型拼 uid**。
+- 主题文件夹名可读、可改；关系引用 `index.md` 里的 `id`，不引用文件夹名，所以改名不断边。
+- 一个图谱一条 grant，覆盖主题文档与 `.kg`；写操作走 `kg_add` / `kg_set` / `kg_del`，不要用 shell 直接写文件。
+
+## 2. 主题卡与关系文档
+
+主题卡好例子：
+
+```markdown
+---
+id: task-bus
+title: 任务总线
+status: active
+depth: 4
+domain: dsh
+tags: [任务, 状态机]
+updated: 2026-10-31
+---
+
+# 任务总线
+
+DSH 的跨来源任务底座，任务卡是唯一状态载体。
+
+## 现在
+v0.1 设计稿评审完，正在拆实现任务。
+```
+
+坏例子：没有 `id`（关系会指向文件夹名，改名断边）；把全部正文塞进摘要（卡片会变成一堵墙）；`status` 写成自由文本（画布只能识别 active/paused/done）。
+
+关系文档好例子：
+
+```markdown
+---
+a: task-bus
+b: group-chat
+label: 任务来源
+updated: 2026-10-31
+---
+
+# 任务来源
+
+群聊把讨论转成任务；任务总线承接状态，不反向写群聊。
+```
+
+坏例子：`a`/`b` 指向不存在的 id（画布会丢弃这条边）；一篇文档写三段互不相关的关系（关系文档只表达两端之间的一件事）。
+
+## 3. 四个动作
+
+工具名与 `kg.py` 对齐：`kg_add` / `kg_get` / `kg_set` / `kg_del`。所有写动作**先返回草稿**，把草稿给用户看，用户确认后再带 `confirm: true` 调用。
+
+| 动作 | 做什么 |
+|---|---|
+| `kg_add` | `kind: topic` 新增一条线（文件夹 + 卡）；`kind: link` 新增一条关系 |
+| `kg_get` | 不带 `graph`/`id` 返回全部图谱总览；带 `graph` 返回该图谱；带 `graph`+`id` 返回卡、文档、关系 |
+| `kg_set` | 改一个主题的 `status` / `depth` / `title` / `domain` / 摘要 / 正文 |
+| `kg_del` | 把主题移到 `<graph>/_trash/`；有关联关系时需 `force: true` 一并移走，**不真删** |
+
+### 五个剧本
+
+1. **新建一条线**：`kg_get` 看当前图谱 → `kg_add {kind:"topic"}` 草稿 → 用户确认 → `confirm:true`。
+2. **接续**：`kg_get {graph,id}` 读卡与关系 → 更新正文/摘要 → `kg_set` 草稿 → 确认。
+3. **寻址**：`kg_get` 不带 id 看总览 → 按名称找 graph → `kg_get {graph,id}` 读一条线；不要用 `find`/`map` 另造工具。
+4. **沉淀**：把一次会话的结论写成文档（`kb_file_write` 到主题文件夹），再用 `kg_set` 更新卡摘要；图谱不复制文档内容。
+5. **复盘**：`kg_get` 总览 → 对每条线读 `kg_get {graph,id}` → 把 `status`/`depth` 调整回真实状态；`kg_del` 只移 `_trash`，不删。
+
+## 4. 扫历史会话（shell，不配工具）
+
+需要从旧会话里找线索时，直接读会话日志，不要新建 `scan` 工具：
+
+```sh
+zstd -dc ~/.dsh/sessions/<session>.jsonl.zst \
+  | rg -i '任务总线|group-chat|kg' \
+  | head -80
+```
+
+把命中的原文片段带回当前对话，再由 agent 写成主题卡或文档；工具只负责图谱的四个动作，不负责扫描历史。