Hindsight 记忆管家 With-With/dsh-hindsight-plugins

dsh-hindsight-plugins

DeepSeek Harness
GitHub Stars
License
Version
类型平台

DSH（DeepSeek Harness）的 Hindsight 外部记忆管家：设置页图形界面 + 官方适配器自动检测与自动安装 + 主动同步开关，装完即用，全程无需命令行。

🧠 底层使用官方 Hindsight 记忆系统（Coding Agents 集成）。
本插件是它的包装与管家，不修改官方运行时。

- ⚡ 一键安装（复制即用）
- ✨ 功能特性
- 📦 安装本插件
- 🚀 使用方法
- 🔧 工作原理
- 📡 HTTP 接口
- ⚙️ 配置
- 🔒 安全说明
- 🔄 已知限制
- 🛠️ 开发与维护
- 📝 更新日志
- 📄 许可

⚡ 一键安装（复制即用）

喂给 AI 的一句话（AI 具备命令执行能力即可，无需解释）：

安装 DSH 插件 dsh-hindsight-plugins（Hindsight 外部记忆管家）：克隆 https://github.com/With-With/dsh-hindsight-plugins 到 ~/.dsh/profiles/web/node_modules/dsh-hindsight-plugins，在 ~/.dsh/cordis.patch.yml 追加 - insert: 条目（id: hindsight-plugins，name: dsh-hindsight-plugins，config.autoInstall: true），然后重启 dsh web 并刷新页面。

或者直接复制命令执行：

| 平台 | 命令 |
| Windows (PowerShell) | git clone https://github.com/With-With/dsh-hindsight-plugins.git "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-hindsight-plugins" |
| macOS / Linux | git clone https://github.com/With-With/dsh-hindsight-plugins.git ~/.dsh/profiles/web/node_modules/dsh-hindsight-plugins |

克隆后还需注册 patch 条目（见下文 📦 安装本插件）并重启 DSH。也可以在 DSH插件市场 中一键安装（自动完成克隆 + 注册）。

✨ 功能特性

- 自动检测与自动安装：插件启动时检查官方 DSH 适配器（npx @vectorize-io/hindsight-coding-agents install dsh）是否已安装挂载；缺失时自动非交互执行官方安装器（地址依次取自：现有 coding-agent.json -> 本插件 sidecar 的内网地址 -> 插件配置 defaultApiUrl）。也可在界面点「一键安装官方适配器」，安装日志实时滚动
- 重复注册检测与一键收敛：精确审计所有补丁层的 id: hindsight 注册数（0 = 缺失 / 1 = 健康 / ≥2 = 重复）。重复会导致 dsh web 启动失败（duplicate loader entry id）--此时界面显示琥珀色警告与「一键收敛」按钮：保留 profile bundle 注册、移除官方安装器写入的 home 补丁行（改动前自动备份）。收敛只在用户点击或安装完成后执行，绝不明动
- 设置页 GUI：设置 -> 插件 -> 「外部记忆」标签页
- 状态卡：当前路由 + 写入范围（首行）、当前内/外网地址、Hindsight 服务端版本号（GET /version 官方同款端点）、Coding Agents 版本号、安装状态（绿/红）
- 「管理」弹窗：编辑内网地址 / 外网地址 / 当前路由（内网|外网），逐地址「测试」连通性，保存设置
- 双路由管理：内网/外网两套地址 + 一键切换；写入固定走 harnesses.dsh.apiUrl 分节（仅 DSH 生效），不影响 Codex 等其他客户端
- 主动同步开关（默认关闭）：区分两种同步方式
- 不主动同步（默认）：不自动写入会话记录；对话中明确要求记住的内容（"把这个存进记忆"）依然正常入库--被动同步不受影响
- 主动同步（开关开启）：AI 每轮答完后自动写入 Hindsight（官方 retainSessions 机制，服务端折叠去重，不浪费提取）
- 映射官方 harnesses.dsh.retainSessions（显式 true/false），对新会话生效；插件首次启动会把缺失的键迁移为显式 false
- 安全写入：原子写 + 改动前自动备份 coding-agent.json（*.hindsight-settings-backup），保留全部未知字段
- 未安装警示：适配器缺失时红色横幅 + 一键安装按钮 + 安装命令 + 官方文档链接 + 「?」帮助
- 零构建零依赖：宿主半边仅用 Node 内建模块（≥ 20），npm / 市场克隆 / 目录复制任何方式均可运行

📦 安装本插件

方式一：DSH 插件市场（推荐）

在 DSH插件市场 中搜索「hindsight」一键安装（本仓库带 dsh-plugin topic，市场索引自动收录）。

方式二：命令安装

dsh plugin --profile web add git+https://github.com/With-With/dsh-hindsight-plugins.git

方式三：手动挂载

本插件位于 ~/.dsh/profiles/web/node_modules/dsh-hindsight-plugins/（零运行时依赖，克隆/复制/目录联接均可），并在用户 patch 层（~/.dsh/cordis.patch.yml）注册：

- insert:
- id: hindsight-plugins
name: dsh-hindsight-plugins
config:
autoInstall: true # 启动时检测并自动安装官方适配器（默认开启） defaultApiUrl: 'http://192.168.1.100:18888' # 地址兜底（示例）

⚠️ 重启生效：首次安装后需重启 DSH（重新运行 dsh web）再刷新页面；宿主半边的后续代码更新同样需要重启（浏览器半边刷新即生效）。

前置条件：一台可达的 Hindsight 服务器（自建或云端）；无需任何 API Key。

🚀 使用方法

1. 重启 DSH 后打开 Web GUI，进入 设置 -> 插件 -> 外部记忆
2. 首次使用：
- 适配器已安装 -> 状态卡直接显示绿色「已安装」
- 适配器缺失 -> 红色横幅，点「一键安装官方适配器」（或等启动 3 秒后的自动安装）
3. 点「管理」：填写内网地址（如 http://192.168.1.100:18888）->「测试」连通 -> 选择当前路由 ->「保存设置」
4. 按需使用「主动同步」开关：开启 = 每轮自动入库；关闭 = 不主动同步，仅按需入库
5. 所有配置对新会话生效（官方适配器在会话启动时读取）

🔧 工作原理

设置 -> 插件 -> 「外部记忆」（浏览器半边，settings.plugins.tab slot） │ fetch /plugins/dsh-hindsight-plugins/{config,test,install,retain} ▼ 宿主半边（node，webServer 路由，仅接受 loopback） ▼ ~/.hindsight/dsh-route.json ← 双地址与当前路由（本插件 sidecar） ~/.hindsight/coding-agent.json ← 解析后的地址（harnesses.dsh.apiUrl 分节）+ retainSessions ▼ 官方 dsh.js 适配器（零改动）在会话启动时读取 -> 对新会话生效 ▼ Hindsight 服务器（自建 NAS / 云端）：会话写回 + 事实提取 + 知识页

主动同步的写回时机（官方机制）：DSH 无「会话结束」概念，等价物是 idle 写回--AI 每答完一轮即写入一次；服务端把同一会话的多次写回折叠成一次提取，频繁写回不浪费资源。

📡 HTTP 接口

| 接口 | 方法 | 说明 |
| /plugins/dsh-hindsight-plugins/config | GET | 读取路由、生效配置、适配器状态、安装进度、同步开关、服务端版本 |
| /plugins/dsh-hindsight-plugins/config | POST | 保存地址/路由（原子写 + 自动备份） |
| /plugins/dsh-hindsight-plugins/test | POST | 地址连通性探测（状态码 + 延迟） |
| /plugins/dsh-hindsight-plugins/install | POST | 一键安装官方适配器（启动时也会自动检测） |
| /plugins/dsh-hindsight-plugins/retain | POST | 主动同步开关（写 harnesses.dsh.retainSessions，对新会话生效） |
| /plugins/dsh-hindsight-plugins/dedupe | POST | 一键收敛重复注册（保留 bundle 注册、移除 home 行，自动备份） |

⚙️ 配置

| 键 | 默认 | 说明 |
| autoInstall | true | 启动时检测官方适配器，缺失则自动安装 |
| defaultApiUrl | '' | 自动安装时的地址兜底（现有配置与 sidecar 均无地址时使用） |

🔒 安全说明

- 路由仅接受 loopback Host 请求（与 DSH GUI 自身同一姿态），请勿将 DSH web 端口暴露到不可信网络
- 自动安装固定 --server self-hosted 非交互模式，绝不把记忆发往云端；5 分钟超时自动终止
- 安装日志完整记录并显示在界面横幅中
- 改动 coding-agent.json 前自动备份，保留全部未知字段

🔄 已知限制

- 宿主半边（路由/安装逻辑）改动需重启 dsh web 生效；浏览器半边（UI）刷新即生效
- 配置与同步开关均对新会话生效（官方适配器会话启动时读取）
- 服务端版本号由宿主中转获取（Hindsight 服务器无 CORS 头，浏览器直连不可行）；宿主未重启加载新版前显示「未知」
- 关闭主动同步只停止自动写回；手动入库文档、记忆检索、深度推理均不受影响
- 需要一台可达的 Hindsight 服务器（本插件不带服务器）

🛠️ 开发与维护

bash
node --check lib/index.js && node --check lib/client.js # 语法
npm pack # 打包 tgz

- 修改服务端逻辑：编辑 lib/index.js；修改页面 UI：编辑 lib/client.js（web2 模块格式，window.__ModuleLoader__.load）
- 浏览器半边即改即生效（刷新页面）；宿主半边更新需重启 dsh web

📝 更新日志

| 版本 | 变更 |
| v0.1.0 | 首个版本：设置页 GUI + 官方适配器自动检测/自动安装/一键安装 |
| v0.1.1 ~ v0.1.3 | 写入范围默认并固定为仅 DSH；管理弹窗精简；状态卡重排（版本/状态行、字体统一） |
| v0.2.0 ~ v0.2.2 | 服务端版本探测（GET /version）；发布前隐私清理 |
| v0.3.0 | 会话同步开关（POST /retain，映射官方 retainSessions） |
| v0.3.1 | 开关语义明确为「主动同步」：关闭 = 不主动同步，被动按需入库不受影响；README 按插件市场风格重写 |
| v0.3.2 | 防御官方安装器的裸 [] 补丁占位 bug（触发前清除、安装后修复） |
| v0.4.0 | 注册审计重写：adapterStatus 从字符串匹配升级为逐层精确计数 id: hindsight（0/1/≥2 三态）；重复注册时琥珀色警告 +「一键收敛」（POST /dedupe，保留 bundle 注册、剥离 home 标记块，自动备份）；手动安装完成后自动收敛一次；绝不明动清理 |
| v0.4.1 | 主动同步默认改为关闭：开关两态均显式写 retainSessions: true/false；插件启动时把缺失键迁移为显式 false（备份先行）；仅显式 true 视为开启 |
| v0.4.2 | 界面精简：「管理」按钮移至标题行右上角；「?」圆标改为「说明」按钮与其并排；移除同步开关切换提示语与底部操作提示语（开关状态本身即反馈） |
| v0.4.3 | 「说明」弹窗增加本项目 GitHub 地址链接 |

📄 许可

MIT