前言¶
在 DSH 里让智能体写代码时，同一个业务概念往往在类型名、字段名、注释和资源文案里各写各的。团队可以口头约定「以某某为准」，但 rename 进不了可 review 的 diff，例外也记不住。DSH 社区插件 dsh-semantic-drift（界面名 Semantic Drift Vocabulary / 语义漂移词表）把「项目里东西叫什么」收成一份跟仓库一起版本化的 YAML，用只读扫描标出代码与词表不一致之处，并在每次会话里把同一套命名规则注入智能体提示词。思路借鉴 kurapica/schema-node-csharp 的三点前提（语义应是独立、可版本化的产物；小词表比开放类型系统好维护；漂移必须可观测、可裁决），实现上不借用其 Meta/Property/Relation 模型或代码生成——一个词表文件、一个只读扫描器、一个面板、五个智能体工具。
这是什么¶
维护者 Yubickari，在 DSH 插件目录中归类为「记忆」。插件记录每个业务概念的点分 id、人类用语 terms、种类 kind、规范符号 canonical（及必要时 type、unit）和说明；对比代码树后报告重复定义、结构分叉、拼写变体、注释/资源里出现但代码未用的术语等；接受的例外写在词表里并带 reason 与最小 scope。它不自动改代码、不替团队决定是否提交 .dsh/semantics.yaml。
- 目录页：https://www.skillhub.cn/plugins/Yubickari/dsh-semantic-drift
- 源码与文档：https://github.com/Yubickari/dsh-semantic-drift
- 许可证：MIT（见仓库
LICENSE） - 依赖 DSH：
>=0.2.1-rc.3（见package.json中dsh.engines）
核心功能¶
版本化词表¶
词表默认路径为工作区内的 .dsh/semantics.yaml。写入前会做校验：例如 id 须唯一且形如 group.name，canonical.symbol 须为合法标识符且概念间不重复，terms 非空且不可跨概念共享，每条 accepted 须有 reason，glob 须可解析；YAML 语法错误会报告行列且不会落盘。保存行为是规范且幂等的；在原始编辑器里手改格式会保留。
只读漂移扫描¶
扫描不写源码。即使词表为空，结构类检测仍可在代码与代码之间比较（例如「同一类型被声明两次」），便于冷启动。注册概念后再扫，才会出现依赖词表的命名类发现。README 列出的检测方向包括：同类型重复声明（比较成员值而不只是名字）、两份拷贝已分叉、Parameterized 衍生拷贝（不应合并）、规范名的拼写变体（含代码从未使用的规范拼写）、术语出现在注释或资源但不在代码中。结构检测覆盖 C#、TypeScript、Python 的声明；其它文件主要贡献注释/字符串证据。插件是词法层面的，不保证语义等价；canonical.unit 会展示和校验字符串，但没有单位漂移检测器。
例外与裁决¶
接受某条 finding 时选择 scope（单文件、同名目录、整符号或自定义 glob），查看将静音的条数并填写 reason。例外写在词表文件中，可编辑、改写、删除或撤销；每条会报告当前实际静音多少 finding。
智能体侧¶
每个会话会注入一段提示：列出当前工作区概念及规则——命名前先查概念、按 canonical.symbol 拼写、缺概念先登记、 deliberate 偏离须记 reason。提供五个工具供智能体读、登记、扫描与裁决。提示词区块有 token 成本；可在面板设置里按 profile 关闭注入，扫描本身在无人请求时不产生该成本（具体数字见仓库 README「Token cost」）。扫描与注入均不强制执行，智能体仍可偏离，但偏离应被记录。
安装与启用¶
插件以当前 DSH 进程权限运行；安装前请自行查看源码与 MIT 许可证。社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系。安装方式与 README 一致：
# from npm
dsh plugin --profile desktop add dsh-semantic-drift
# from GitHub
dsh plugin --profile desktop add github:Yubickari/dsh-semantic-drift
# from a local checkout
dsh plugin --profile desktop add link:/path/to/dsh-semantic-drift
Web GUI 可在 Settings → Plugins → Install from source 完成同等操作。安装后刷新页面一次以便浏览器端加载，再在侧栏选择 Semantic Drift Vocabulary。仓库已提交 lib/，从 git 源安装无需 build。更新需再次执行 install（无插件内 updater），例如：
dsh plugin --profile desktop add dsh-semantic-drift@0.2.0
dsh plugin --profile desktop add github:Yubickari/dsh-semantic-drift#v0.2.0
更新后重启 DSH，在面板页脚或 GET /semantic-drift/health 查看版本；更新不会改动已有词表与 accepted 条目。
典型用法¶
下面步骤来自 README「Getting started」，可在工作区内复现。
- 打开工作区中的 Semantic Drift Vocabulary。
- 点击 Create vocabulary，生成带默认
exclude、无概念的.dsh/semantics.yaml。 - 点击 Scan。尚无概念时仍可能看到结构类 finding。
- 用 New concept 或工具
semantic_upsert登记概念，再扫描一次。 - 对有意保留的差异：选 scope，确认静音条数，填写 reason 接受 finding。
词表片段示例（字段含义见 README「The vocabulary file」）：
version: 1
meta:
project: demo
updated: 2026-10-25
exclude: ["**/node_modules/**", "**/bin/**", "**/obj/**"]
concepts:
- id: device.target_temperature
terms: ["target temperature", "set point"]
kind: quantity
canonical:
symbol: TargetTemperature
type: double
unit: "°C"
note: The temperature the device is asked to reach.
accepted:
- symbol: TargetTemp
path: src/Legacy/**
reason: public field kept for one release
terms 可用任意语言；扫描器在注释、字符串和资源文件中按纯文本匹配。
适用场景与边界¶
适合需要在多人、多会话、智能体协作下维持同一套业务命名，且希望 rename 与例外都能进 Git diff 的团队。一个工作区一份词表，无跨仓库视图。它不替代类型系统或静态分析的全语义能力，也不做自动 rename/merge。是否将 .dsh/semantics.yaml 纳入版本控制由项目自行决定。
结尾¶
dsh-semantic-drift 把业务概念收成可 review 的词表、用只读扫描暴露命名与结构漂移，并把同一规则放进每次智能体会话。安装与细节以仓库 README（含 README.zh.md）为准；浏览与安装入口亦可从目录页进入：https://www.skillhub.cn/plugins/Yubickari/dsh-semantic-drift ，源码：https://github.com/Yubickari/dsh-semantic-drift 。
