前言¶
用 DSH 做数据库问答或运维根因分析时，常见做法是直接把表结构塞进提示词，或让模型自己猜列名与业务口径。表一多、术语和物理字段又对不齐时，SQL 和证据链很容易漂。DLR（Decoupled Logic Representation）把逻辑概念层和物理数据层拆开，并在 TSM（Three-Level Semantic Modeling）里按治理线分层挂载知识；仓库同时提供 TypeScript 语义服务（LanceDB + Neo4j）和面向 DSH 的 bundle dsh-tsm-agent。下面介绍它是什么、能做什么，以及如何在本地把后端和 DSH 接起来。
这是什么¶
DLR 是一种面向数据源的语义建模范式：两层模型（LE 逻辑实体 / PE 物理视图）配合 ARCS（投影锚定）与 PAS（语义路由），让智能体把自然语言问题稳定落到关系库上。项目在 TSM 框架内运行，三级为 L1 dlr（数据源级）、L2 consensus（领域共识）、L3 sop（业务逻辑）；知识是否进入某一级，由治理线决定。
维护者为 ljwzhaoxiaoniu，在 SkillHub 目录中归类为模型推理，当前 bundle 版本 v0.2.2（npm 包 dsh-tsm-agent）。仓库以多个 npm 包交付：语义核心 tsm-core-dlr、DSH 套件 dsh-tsm-agent、评测 dsh-tsm-eval，以及 BIRD mini-dev、Cloud-OpsBench 两个可切换场景包。
- 目录页：https://www.skillhub.cn/plugins/ljwzhaoxiaoniu/DLR
- 源码：https://github.com/ljwzhaoxiaoniu/DLR
核心功能¶
语义服务（tsm-core-dlr）¶
TypeScript 实现的语义后端：LanceDB 向量、图存储（内存或 Neo4j）、ONNX 编码器，通过 streamable HTTP 暴露 7 个 MCP 工具（含 dlr 相关能力；dlr-state 类场景另有 3 个）。默认 MCP 地址为 http://127.0.0.1:28795/mcp，可用环境变量 TSM_MCP_URL 覆盖。
经 dsh-tsm-agent 接入后，工具在 DSH 侧以 mcp__semantic-core__* 注册，主要包括：
| 工具 | 用途 |
|---|---|
dlr_semantic_query |
L1：召回问题涉及的业务实体（LE） |
get_pe_mapping / get_le_attrs |
物理视图列、ARCS、database_url |
dlr_search_consensus |
L2：术语与列/值的共识条目 |
dlr_search_sop |
L3：按题检索口径节（有则返回） |
get_full_data_info |
视图之外的物理列信息 |
execute_sql |
只读 SQL（子进程，20s 超时） |
DSH bundle（dsh-tsm-agent）¶
bundle 把 profile 接到运行中的 TSM Core Service，并附带与场景无关的 paradigm 技能、Web 状态浮层和 agent 规则（AGENTS.md）。贡献的顶层行包括：
mcp-semantic-core：MCP 客户端，指向语义服务（toolCallTimeoutMs: 60000、failOnStartupError: true）dlr-status：Web 浮层，展示后端健康与语义资产计数- agent preset
preset-dlr：persona、AGENTS.md、技能与 compaction（供交互会话选用；headless 不挂 preset，但 MCP 顶层行仍生效）
硬依赖 tsm-core-dlr 会随包安装（含原生依赖，体量约 200 MB）；服务进程仍需单独启动。场景数据来自可选的 tsm-scenario-* 包，通过 TSM_SCENARIO 指向包名或自带场景路径，bundle 本身与具体数据集解耦。
评测与基准场景¶
dsh-tsm-eval：用 dsh headless 跑场景试卷，以tsm grade打分，并生成可复现报告（结果、过程、session-log）。tsm-scenario-birdmini：BIRD mini-dev（11 库 / 500 题），公开跑分 500/500 判定正确（426 条与 gold 完全一致，74 条在 L3 条款下对数据集 gold 缺陷作裁定）。tsm-scenario-cloudopsbench：Cloud-OpsBench（754 例 Kubernetes RCA），JRA 753/754（99.87%）；证据链全闭合 740/754（98.1%）。上述基准在仓库架构下端到端跑通，逐题账本可审计。
公开材料中的模型组合为 DeepSeek-V4.1-Flash + TSM+DLR；BIRD 500 题批跑产出于较早的 dsh 0.1.7-alpha.1，作者在 npm 说明中注明未在升级后重跑，升级 dsh 后应先用 --dump-config 核对配置行。
安装与启用¶
环境要求（摘自仓库 Quickstart）：
| 项 | 说明 |
|---|---|
| Node.js + npm | 服务以 TypeScript 运行，常用 npx tsx / node；dsh-tsm-agent 要求 Node >= 20 |
| Neo4j 5.x | 本地或任意 Bolt 端点，配置 NEO4J_HOME 或 NEO4J_URI |
| ONNX 编码器 | 在检出内执行 bash "TSM Core Service/scripts/fetch-model.sh"（约 95 MB） |
| dsh | 文档示例为 @deepseek-ai/dsh@0.2.0-rc.2（alpha） |
| API Key | 复制 DSH-based Agent Service/dsh_dlr/.env.example 为 .env，填写 DEEPSEEK_API_KEY |
安装 bundle（每个 profile 一次）。推荐用 DSH 插件管理器（设置 → 插件 → 安装 bundle）或 agent 的 plugin_manager 工具（install_bundle），会同时完成装包与选中 bundle。CLI 只装包时，还需在插件管理器启用，或将包名加入 profile 的 dsh.profile.bundles：
dsh plugin --profile web add dsh-tsm-agent
若手头有仓库检出，也可从本地路径安装（路径按你的检出位置替换）：
dsh plugin --profile web add "<repo>/DSH-based Agent Service/dsh-tsm-agent"
可选场景与评测包按需安装，例如 tsm-scenario-birdmini、tsm-scenario-cloudopsbench、dsh-tsm-eval；使用时设置 TSM_SCENARIO=<包名>。
启动语义后端。有检出时可用脚本（幂等，会拉起 Neo4j 与 TS MCP，端口 28795）：
bash "DSH-based Agent Service/scripts/start_backend.sh"
cd "TSM Core Service" && npx tsx src/verify/precheck.ts
precheck 应列出 7 个工具。仅有 npm 安装、无检出时，可全局安装核心并用 CLI 起服务（首次还需拉模型并对已装场景执行 build）：
npm i -g tsm-core-dlr && tsm serve --http 28795
tsm fetch-model
tsm build
交互式 Web 会话可在配置好 .env 后：
bash "DSH-based Agent Service/dsh_dlr/run_web.sh"
典型用法¶
Headless 单题¶
在后端已启动、profile 已安装并启用 bundle 的前提下，可用仓库脚本对 BIRD mini-dev 跑单题（第二个参数为自然语言问题）：
bash "DSH-based Agent Service/dsh_dlr/run_one.sh" 1471 "Your natural language question here"
MCP 为顶层行，--profile headless 不会挂 preset-dlr，但语义工具仍可用。
切换场景¶
场景层可插拔：将 TSM_SCENARIO 指向自带三级源（及可选试卷）的 tsm-scenario-* 包。换场景后按仓库 docs/04-application.md 中的 checklist 重建索引并核对 MCP 工具与数据路径。
跑评测卷¶
安装 dsh-tsm-eval 后，可用其流程对场景试卷做 headless 执行与 tsm grade 判分，输出带过程与 session 日志的报告，便于对照基准账本（如 scenarios/birdminidev/DETAIL.md、scenarios/cloudopsbench/DETAIL.md）。
适用场景与注意¶
适合需要在 DSH 里做可审计的关系库 NL2SQL、或 Cloud 运维根因分析（证据链闭合）的团队：语义资产与 L1/L2/L3 分层由服务统一提供，模型侧主要通过 MCP 按跳查询，而不是一次性吞整张 schema。
使用前请注意：
- 权限：插件与 bundle 随当前 dsh 进程权限运行；安装前请阅读 GitHub 仓库 源码与 MIT 许可证，并确认 API Key、Neo4j、数据集路径等敏感配置。
- 依赖体积与服务分离：
tsm-core-dlr原生依赖较大，且必须单独serve；端点不可达时 MCP 行会因failOnStartupError: true直接失败。 - dsh 仍为 alpha：bundle 在
@deepseek-ai/dsh@0.2.0-rc.2上做过配置探测；版本变更后执行dsh --profile web --dump-config核对mcp-semantic-core、dlr-status、preset-dlr是否仍在。 - 数据准备：BIRD mini-dev 需自行按上游说明解压到
MINIDEV_sqlite/；Cloud-OpsBench 场景包自带分级源与上游 scorer 适配。
SkillHub（skillhub.cn）是社区插件目录，与 DeepSeek / 幻方无官方从属关系；收录信息（如星标、简介中的基准数字）可能与 GitHub README 略有出入，以你实际打开的文档与跑分账本为准。
结尾¶
DLR + TSM 把数据源语义、领域共识和业务 SOP 拆成可治理的三级结构，再用 tsm-core-dlr 和 dsh-tsm-agent 接到 DSH 的 MCP 与 preset 上；两个公开场景包提供了可复现的 NL2SQL 与 K8s RCA 基准。若你要在 Harness 里试同一套语义网关，可从目录页进入说明，或直接在 npm 安装 dsh-tsm-agent 并按上文启动 :28795 后端。
- 插件目录：https://www.skillhub.cn/plugins/ljwzhaoxiaoniu/DLR
- GitHub：https://github.com/ljwzhaoxiaoniu/DLR
