前言¶
在 DSH 里让 agent 做研究或执行任务时，它常会给自己起的流程起一个短名，例如「三件套」「跑一轮」。这些叫法只在当前项目语境下有意义：用户看到 agent 这样说时不知道指什么；换一轮对话后 agent 也可能忘掉当初的定义，于是重复解释、前后不一致。
社区插件 黑话单（仓库 zbc0315/dsh-jargon-list，npm 包 @tom2012/dsh-jargon-list）把「起名」落成一张可持久化的表：短名与详细含义写在项目工作区内，人和 agent 读写同一份数据，并在 Web 右侧栏提供浏览与增删改查。
这是什么¶
黑话单是面向 DeepSeek Harness Web 的 DSH 插件，维护者为 zbc0315，在生态目录中归类为 记忆。它不自动改系统提示，也不做全局词库；数据文件跟着当前会话所锚定的项目目录走，换项目即换表。
核心功能¶
人机共用一份数据¶
词条保存在工作区下的 .dsh/jargon.json。文件为 JSON，便于阅读、diff，并可随仓库提交。切换 DSH 会话或项目即切换黑话表，其它项目互不影响。
右侧栏页签¶
安装并在 Web 中刷新后，可通过以下方式打开：
- 会话标题栏右侧的「黑话单」图标按钮，直接在右侧栏打开页签；
- 右侧栏
+→ 指南卡片 → 「黑话单」。
页签内支持搜索、新增、就地编辑、删除。
Agent 侧工具¶
插件向 agent 注册三个工具：
jargon_list：查询词条；jargon_save：新增或更新；jargon_delete：删除。
用户可在面板操作，agent 可在任务中读写，双方针对同一文件；并发上同一词条为 last-write-wins，面板约每 2 秒轮询 revision，外部改动最多约 2 秒后可见。
数据字段（摘录）¶
单条词条包含 term（trim 后 1–80 字，同一文件内大小写/全半角不敏感唯一）、definition（trim 后 1–4000 字，换行保留）、createdAt / updatedAt，以及展示用字段 updatedBy（user | agent）。完整结构见仓库 README 中的示例。
安装与启用¶
插件在 package.json 中声明 engines.dsh 为 >=0.2.1-rc.5 <0.3.0-0，README 写明已在 0.2.1-rc.5 与 0.2.2-rc.1 上实测通过；0.3.x 未验证且会被版本范围挡在门外。安装前请确认本机 DSH 版本在支持区间内。
推荐从 npm 安装：
dsh plugin --profile web add @tom2012/dsh-jargon-list
也可让 agent 通过 plugin_manager 安装：action: install_bundle，target 传 @tom2012/dsh-jargon-list。装完后刷新 Web 页面即可使用右侧栏与 agent 工具。
插件以当前 DSH 进程的权限读写工作区文件；安装前建议查看 GitHub 仓库 源码与 MIT 许可证。当前包版本为 0.1.1（以 package.json 为准）。
典型用法¶
在面板里补一条黑话¶
打开右侧栏「黑话单」，新增词条。例如短名「三件套」，含义可写为：「研究前置三步：先查既有实现，再读相关文档，最后跑一次现状测试。」（与 README 示例一致，可按项目实际改写。）
让 agent 在任务里登记或查询¶
任务中若 agent 反复使用某个项目内简称，可让它调用 jargon_save 写入定义，或先用 jargon_list 核对是否已有记录，避免与用户理解不一致。文件损坏或结构不符时，读操作会报错并显示路径，写操作会被拒绝，需用户自行修复或删除该 JSON 文件。
行为与限制（使用前须知）¶
- 锚定项目目录：黑话单绑定会话 header 里的原始
cwd，不跟随 agent 在会话内的cd；在会话里切到别的目录不会把表「搬走」。 - 写入方式：原子替换（临时文件 + rename）；同一工作区进程内读改写串行。跨进程（同一工作区开两个 DSH 实例同时写）无锁，仅进程内串行。
- v1 不做：全局黑话表、自动注入系统提示、别名/标签/撤销历史；同一词条并发编辑无冲突提示。
结尾¶
黑话单解决的是「项目内临时简称」的沉淀与共享：数据落在 .dsh/jargon.json，人用右侧栏维护，agent 用三个工具同步读写。目录介绍见 SkillHub 插件页，源码与详细契约见 GitHub：zbc0315/dsh-jargon-list。
