dsh-intent-recognition

dsh plugin --profile web add dsh-intent-recognition

dsh-intent-recognition

[English](README.md) | 中文

DeepSeek Harness（DSH）意图识别插件：五层流水线路由架构 + 场景/意图管理 Web 界面 + 双版本存储（基础版本地文件开箱即用 / 高级版 PostgreSQL+pgvector）+ 可分发 API 服务 + DSH 生态路由（工具 / 工作流 / 子智能体 / Cordis 服务）。

用户 Query
   │
   ▼
┌─ 层1 规则硬过滤 ───────────── 问候 / 退出 / 指令 / 关键词强匹配（词库+正则+黑名单+白名单）
│      │ 未命中
├─ 层2 向量检索 ─────────────── pgvector 余弦相似度，把意图库压缩为 Top5–Top10 候选
│      │
├─ 层3 Jev 概率精判 ─────────── 高置信直接路由 → 中置信 → 层4；低置信 → 层5
│      │
├─ 层4 轻量微调模型 ─────────── BERT / 小参数 LLM，仲裁高相似意图与边界 case
│      │
└─ 层5 LLM 结构化兜底 ───────── 多意图叠加 / 跨轮上下文 / 槽位抽取 / 未知 Query，JSON 结构化输出

每一层都可在服务配置中单独关闭，关闭的层会被流水线直接跳过。

定位：控制面 + 数据面

本插件在 DSH 中分两层发挥作用：

• 控制面（管理 UI）：左侧边栏「意图识别」面板（与「插件」入口同级，可在侧边栏 More 菜单中固定/取消固定），同时保留 设置 → 意图识别 分区，两处渲染同一管理界面，用于维护意图库、配置模型、创建/运行服务。只是工具，不参与对话。
• 数据面（被消费的服务）：真正和 DSH 对话链路对接的部分。运行中的服务通过下面两种方式被消费：

消费方式 · 说明 · 适用

Agent 工具（推荐） · 每个运行中的服务自动注册一个工具 intent_recognize_<服务名>，DSH 主 Agent 可直接调用；高置信命中时工具内直接执行路由 · 用户和 DSH 对话，意图服务做分发

Cordis 服务 · ctx.intentRecognition.predict(service, query, context)，供其他插件程序化调用 · 下游插件自己集成

功能

• 开箱即用：默认基础版（本地文件存储），安装后无需准备数据库即可建意图、配模型、跑服务；需要向量检索时随时在页面升级为高级版，已有数据自动迁移。
• 意图管理：按场景创建意图类别（名称/编码/描述/示例/关键词/黑白名单/路由配置），Excel 导入（合并/覆盖）与导出，一键重建示例向量（高级版）。
• 模型配置：向量模型、Jev 模型、轻量微调模型、LLM 全部页面化配置（OpenAI 兼容接口或自定义 http JSON 接口），支持连通性测试。
• 服务管理：按场景创建 API 服务，五层独立开关与参数（阈值/TopK 等），服务可 运行 / 停止 / 删除 / 复制；每个服务独立 API Key；内置在线测试台与调用日志。
• 向量检索实验室（高级版）：层2 复盘专用页签——召回测试（输入问题看每条切片命中分数与意图聚合结果，可参照服务的阈值/TopK）、切片浏览（示例文本/维度/构建模型/时间，可删脏切片）、覆盖率概览（各场景意图/示例/切片数量与缺口，就地重建）。
• 路由执行：意图可配置路由（无 / DSH 工作流 / 子智能体 / Cordis 服务），服务级 route_mode 控制自动执行或仅建议。
• 存储双版本：基础版 = 本地 JSON 文件（零依赖）；高级版 = PostgreSQL + pgvector（向量与业务数据同库），页面内一键升级/降级。
• Agent 集成：运行中的服务自动注册/注销 intent_recognize_<slug> 工具；可选向系统提示词注入当前可用意图服务清单。

页签按使用顺序排列：意图管理 → 模型配置 → 服务管理 → 向量检索（高级版）→ 数据库。首次打开且尚未创建服务时，页面顶部会出现三步上手引导；基础版下「向量检索」页签带 🔒，点开会看到升级说明。

界面预览

意图管理 · 服务管理

 · 

向量检索实验室 · 模型配置

 · 

在线测试台（五层 trace） · 会话中的 Agent 工具调用

 · 

安装

前置：Node.js ≥ 20，已安装 DSH（npm i -g @deepseek-ai/dsh）。无需准备数据库——默认基础版开箱即用。

# 1. 安装插件
dsh plugin --profile web add dsh-intent-recognition

# 或从本地目录 / tarball 安装
dsh plugin --profile web add ./dsh-intent-recognition
dsh plugin --profile web add ./dsh-intent-recognition-0.7.0.tgz

# 2. 重启 dsh web（桌面版：重启应用或刷新页面 Ctrl+R）
#    —— 客户端 bundle 只在页面启动时按启动图加载，安装后必须刷新才会出现
# 3. 点击左侧边栏「意图识别」图标打开管理面板（或 设置 → 意图识别）
# 4. 按「意图管理 → 模型配置 → 服务管理」顺序配置即可使用
# 5. 需要向量检索时：打开「数据库」页签填入 PostgreSQL 地址升级为高级版，
#    已有场景/意图/模型/服务会自动迁移，无需重建

桌面版从 npm 官方源安装的实际流程（插件 → 添加插件 → 输入包名 dsh-intent-recognition，安装源选 npm 官方源）：

添加插件 · 安装中 · 安装完成（运行中）

 ·  · 

存储版本切换时机：基础版零配置直接用；需要向量检索（层2）时再到「数据库」页签升级高级版。升级即时生效，本地数据自动迁移（保留 id 与 API Key）；也可随时「切回基础版」，本地数据保持原样。

桌面版注意：安装/升级本插件后，如果侧边栏没有出现「意图识别」入口，先刷新页面（Ctrl+R 或重启应用）。这是 DSH 的启动图机制决定的：页面只在启动时加载一次插件客户端清单，官方插件管理页在安装后也会弹出「刷新」提示。刷新后入口仍缺失时，再检查 设置 → 意图识别 分区是否存在——两者同源，都不存在说明客户端未加载，请在插件详情页确认组件「运行中」。

侧边栏入口通过 DSH 的 sidebar.panellist + main 面板插槽注册，与官方「插件」「计划任务」入口同一机制：点击图标在主区域打开完整管理页；不想显示时，在侧边栏 More 菜单里取消固定即可（外壳内建能力，无需插件配置）。

本包声明了 dsh.bundle.patch，dsh plugin add 会自动把它挂进 profile 的 bundle 层栈，无需手工编辑 cordis.patch.yml。

存储版本：基础版 / 高级版

v0.7.0 起插件内置两个存储版本，首次打开面板时顶部横幅会说明当前版本：

· 基础版（默认） · 高级版

存储 · 本地 JSON 文件（与连接配置同目录，如 data.json） · PostgreSQL + pgvector

需要数据库 · 否，开箱即用 · 是（页面配置，即时生效）

层1 规则 / 层3 Jev / 层4 微调 / 层5 LLM · ✅ · ✅

层2 向量检索、向量实验室、重建向量 · ❌（页签 🔒，运行时自动跳过并在 trace 中注明） · ✅

适用 · 个人试用、规则为主的场景 · 意图多、表述多样、需要语义召回的场景

• 升级：「数据库」页签填入 PostgreSQL 连接信息，「测试并保存」即切换到高级版。默认勾选「迁移本地数据」，已建的场景/意图/模型/服务保留原 id 与 API Key 复制进数据库，Agent 工具与 API 调用方无感。重复迁移幂等（已存在的行自动跳过）。升级后记得在意图管理页重建向量以启用层2。
• 降级：「数据库」页签的「切回基础版」把存储切回本地文件——本地数据保持升级前的原样（升级后在高级版里新增的数据不会回写本地），PostgreSQL 连接配置保留以便再次升级。
• 版本判定顺序（启动时）：显式切回基础版的选择 > 页面保存的数据库连接 > 补丁里的 databaseUrl（能连通才算高级版）> 基础版兜底。任何情况下插件都能加载、面板都能打开。

数据库连接（高级版）

「意图识别 → 数据库」页签管理存储版本与高级版连接：顶部「存储版本」卡片显示当前版本、本地数据文件位置与各表记录数；高级版下提供表单（主机/端口/库名/账号/密码/SSL）或直接粘贴连接串，支持测试连接（同时探测 pgvector 扩展是否可用）、测试并保存（持久化 + 存储热切换，全程无需重启插件或桌面端）、清除页面配置（回退到补丁连接串或基础版）、切回基础版、迁移本地数据到此数据库（本地有数据时可随时补迁移）。

数据库未连接时（高级版），面板顶部会给出红色横幅引导到「数据库」页签；保存后存储热切换、即时生效：

未连接引导横幅 · 数据库页签（已连接）

 · 

• 生效优先级：显式切回基础版的选择 > 页面保存的连接 > cordis.patch.yml 的 databaseUrl（探测连通才算数）> 基础版兜底。页面保存的连接不可达时不会静默回退基础版（避免数据写岔），面板照常打开、管理接口返回 503，修复连接或手动「切回基础版」即可恢复。
• 持久化位置：%APPDATA%/dsh-intent-recognition/（Windows）、~/Library/Application Support/dsh-intent-recognition/（macOS）、~/.config/dsh-intent-recognition/（Linux）；可用环境变量 DSH_INTENT_RECOGNITION_CONFIG 覆盖。该目录下：connection.json（高级版连接，密码回显脱敏为 ，PUT 提交 表示沿用）、data.json（基础版数据）、storage.json（显式切回基础版的标记）。文件权限均为 0600。
• pgvector：autoMigrate 开启时，保存成功后会自动 CREATE EXTENSION IF NOT EXISTS vector 并建表；测试连接会提前提示目标实例是否安装了 pgvector。未安装 pgvector 的库可以连接，但层2 向量检索不可用（会在页面提示）。
• 数据库维护：连接配置下方提供检查数据库 / 创建数据库 / 删除数据库。检查用于确认连接串指向的库是否已存在；创建会一次性完成**建库 + 安装 pgvector 扩展 + 初始化全部 ir_* 表；删除是高危操作，弹窗会红色警示并要求完整输入数据库名二次确认**（系统库 postgres/template0/template1 不允许删除）。维护操作使用同一组凭据连接到该实例的 postgres 维护库执行，因此当前业务库不存在时也能创建它。

插件配置（cordis.patch.yml）

字段 · 默认值 · 说明

databaseUrl · postgres://postgres:postgres@127.0.0.1:5432/dsh_intent · 高级版兜底连接串（页面配置优先于它；探测连通才进入高级版，否则回落基础版），库内需可用 pgvector（CREATE EXTENSION vector，插件自动执行）

embeddingDim · 1024 · 向量维度，必须与实际使用的向量模型一致；修改后需重建

…(truncated)