dsh-hindsight-plugins

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 并刷新页面。

或者直接复制命令执行：

克隆后还需注册 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 接口

⚙️ 配置

🔒 安全说明

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

🔄 已知限制

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

🛠️ 开发与维护

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

📝 更新日志

📄 许可

MIT