前言¶

在 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