前言¶

在 DSH 工作流中，artifacts、verified-fact records、actions、reports 之間可能存在引用關係。只看單個對象或報告，不足以確認某個節點是否可解析、是否仍匹配預期內容、上下游證據是否完整。dsh-lineage 用於構建本地可驗證的對象圖：節點引用在 workspaceRoot 內解析，引用對象字節計算 SHA-256，並報告 verified、missing、stale 狀態。

下面介紹它的定位、能力、安裝方式和典型用法。

這是什麼¶

dsh-lineage 是 dongsheng123132 維護的插件，倉庫爲 dongsheng123132/dsh-lineage，許可證爲 MIT。package.json 聲明版本 0.2.0，要求 Node.js 22+，並聲明 optional peer dependency @deepseek-ai/dsh-tools。

它面向 artifacts、verified-fact records、actions 和 reports，構建本地可驗證對象圖。引用對象會被哈希，但對象內容不會被複制到 ledger 或 reports。SHA-256 用於證明 identity，不用於證明 truth；插件報告對象是 present、missing 還是 changed，不會發明斷言。

核心功能¶

對象圖驗證¶

dsh-lineage 支持以下檢查：

• DAG validation
• upstream/downstream closure
• missing/stale disclosure
• 區分 verified、missing、stale
• 檢測 dangling references、invalid relation types、cycles

missing 或 stale 對象不會被靜默提升爲 fact。

Append-only ledger¶

事件輸入是顯式 JSONL。每個事件包含 idempotencyKey，類型爲 put-node 或 put-edge。

重放規則：

1. 同一 key/event 重放安全
2. 同一 key 使用不同內容會 fail closed
3. 事件文件不被更新

路徑與寫入邊界¶

插件的路徑和寫入邊界如下：

• 所有路徑要求 workspace-relative
• 拒絕 traversal 和 symlink components
• 寫入只發生在顯式 ledgerDir 或 artifactDir 內

事件 schema 會拒絕 claims、chat、prompts、messages、raw content、text、credentials、tokens、cookies、authorization 等鍵。

DSH 工具¶

插件註冊以下 DSH 工具：

• dsh_lineage_inspect
• dsh_lineage_ingest
• dsh_lineage_query
• dsh_lineage_verify

Standalone MCP server¶

插件提供 standalone stdio MCP server，暴露：

• lineage_events_inspect
• lineage_events_query

MCP 只接受最多 1 MiB 的 inline structural events。它不解引用 object paths，也不讀取或寫入文件系統。persistent append-only ingestion 和 object-hash verification 只通過 workspace-bounded DSH tool 和 CLI surfaces 提供。

安裝與啓用¶

先確認 Node.js 版本不低於 22：

node --version

下面在 DSH 中安裝插件：

dsh plugin --profile lineage add github:dongsheng123132/dsh-lineage

安裝完成後，可以通過上面列出的 dsh_lineage_* 工具調用 lineage 能力。除 optional @deepseek-ai/dsh-tools peer 外，沒有運行時依賴或安裝生命週期腳本。

典型用法¶

先準備 workspace 內的 JSONL 事件文件，例如 lineage.events.jsonl。

ingest¶

ingest 將事件寫入顯式 ledger：

dsh-lineage ingest --root /workspace --ledger ledger --events lineage.events.jsonl

inspect¶

inspect 檢查 ledger 與當前 workspace 下的對象狀態：

dsh-lineage inspect --root /workspace --ledger ledger

query¶

query 用於查詢節點相關的上游或下游 closure：

dsh-lineage query --root /workspace --ledger ledger --node report:proof --direction upstream

verify¶

verify 用於按節點方向檢查 closure，並驗證對象證據：

dsh-lineage verify --root /workspace --ledger ledger --node report:proof --direction upstream --artifact-dir artifacts

也可以用 Node 直接運行倉庫內入口：

node bin/dsh-lineage.mjs ingest --root . --ledger ledger --events examples/lineage.events.jsonl
node bin/dsh-lineage.mjs verify --root . --ledger ledger --node fact:normalized-v1 --direction both --artifact-dir artifacts

經過上面的步驟，可以完成從事件寫入到對象證據檢查的流程。

適用場景與注意¶

適合以下場景：

• 需要爲 artifacts、verified-fact records、actions、reports 維護本地可驗證引用
• 需要區分 verified、missing、stale
• 需要避免把聊天原文、原始內容、憑據類字段混入事件
• 需要選擇 DSH 工具、CLI 或 standalone MCP 的不同邊界

使用前注意：

• 要求 Node.js 22+
• @deepseek-ai/dsh-tools 是 optional peer dependency
• 插件以當前 dsh 進程權限運行，安裝前應檢查源碼與 MIT 許可證
• MCP 只處理 inline structural events，不訪問文件系統
• persistent append-only ingestion 和 object-hash verification 通過 DSH tool 或 CLI 提供

結尾¶

dsh-lineage 提供一組本地可執行的血緣證據檢查：引用解析、SHA-256 比對、closure 查詢、ledger 重放、missing/stale 披露。

已覈實資料未提供目錄頁地址。GitHub 倉庫地址：

https://github.com/dongsheng123132/dsh-lineage