nanpaidashi/dsh-honcho-sync

@nanpaidashi/dsh-honcho-sync

面向 DeepSeek Harness 的 Honcho 记忆插件——为你的 AI 提供持久化的跨会话记忆，由自托管的 Honcho v3 服务提供支持。

功能说明

- 自动同步：每一轮对话都会自动同步到 Honcho（带防抖）。同步游标在重启后依然保留。
- 混合召回：并行地对原始消息和推理结论（显式/演绎/归纳）进行语义搜索。
- 记忆注入：会话开始时，相关的 peer 卡片、表征（representations）和语义召回结果会被注入到系统提示词中。
- 25 个工具：完整的 Honcho v3 API 接口以 DSH 工具的形式暴露——搜索、档案、会话管理、peer 管理、结论、dreaming、队列监控。

环境要求

- 带 web profile 的 DeepSeek Harness（DSH）
- 一个正在运行的 Honcho v3 实例（自托管）
- Node.js >= 18

安装

从 npm 安装
dsh plugin --profile web add npm:@nanpaidashi/dsh-honcho-sync dsh web

或从 GitHub 安装
dsh plugin --profile web add link:https://github.com/nanpaidashi/dsh-honcho-sync dsh web

然后重启 DSH：

systemctl --user restart dsh-web
或：dsh web --restart

升级

如果你安装的是较早版本（v0.6.x 或 v0.7.0）：

重新运行相同的安装命令——它会拉取最新版本并覆盖
dsh plugin --profile web add npm:@nanpaidashi/dsh-honcho-sync dsh web
或
dsh plugin --profile web add link:https://github.com/nanpaidashi/dsh-honcho-sync dsh web

systemctl --user restart dsh-web

安装是幂等的：它会就地替换插件源文件。你的配置（设置面板）和同步状态（~/.dsh/honcho-sync-state.json）都会被保留——不会丢失数据，也无需重新配置。

v0.8.0 → v0.8.1 更新日志

- 上下文效率：将注册的工具从 25 个减少到 4 个（honcho_recall、honcho_ask、honcho_remember、honcho_context）——每个会话可节省约 7K token 的工具 schema 注入
- 注入质量：新增 _filterRepresentation()——从表征注入中移除 Pattern [medium]/[low] 块、Premises/Sources 溯源链，以及孤立的 Type/Sources 行
- 注入质量：新增 _assembleByPriority()——按优先级（peer-card > session-summary > semantic-recall > representation）组装记忆上下文各部分，而非固定顺序
- 注入预算：injectionMaxChars 默认值 8000 → 4000，reprMaxObs 默认值 8 → 4
- 工具描述：将所有工具描述缩短至约 100 个字符

v0.7.x → v0.8.0 更新日志

- DSH 0.1.0-rc.8 兼容性：新增 normalizeToolParameters()，用于将旧式参数简写转换为标准 JSON Schema
- DSH 0.1.0-rc.8 兼容性：新增 output.render，返回内容块数组（DSH >= 2026 所要求）
- README：移除了设置面板的相关引用——配置通过 ~/.config/systemd/user/dsh-web.service 中的环境变量完成
- 修复了 conclusions/query 需要 filters 参数的问题
- 修复了 /search、/peers/list、/summaries 的响应解析
- 修复了 POST /conclusions 的请求体格式
- 修复了 schedule_dream 参数名（dream_type）
- 新增 4 个工具：honcho_conclude、honcho_conclude_list、honcho_conclude_query、honcho_message_get
- 混合召回现在会并行搜索消息和结论

卸载

1. 从 DSH 中移除插件
dsh plugin --profile web remove honcho-sync dsh web

2. （可选）删除同步状态文件
rm ~/.dsh/honcho-sync-state.json

3. 重启 DSH
systemctl --user restart dsh-web

注意： 移除插件并不会删除你的 Honcho 数据。所有消息、结论和对等方卡片都保留在你的 Honcho 服务器上。插件只是桥梁——你的记忆是安全的。

配置

没有设置面板。 所有配置都通过 DSH 服务文件中的环境变量完成。

第 1 步：编辑 DSH 服务文件

对于 systemd（Linux）
nano ~/.config/systemd/user/dsh-web.service

将这些环境变量添加到 [Service] 部分：

[Service]
Environment="HONCHO_URL=http://localhost:8000"
Environment="HONCHO_WORKSPACE=my-workspace"
Environment="HONCHO_USER_PEER=user"
Environment="HONCHO_AGENT_PEER=agent"

第 2 步：应用更改

systemctl --user daemon-reload
systemctl --user restart dsh-web

配置参考

| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| HONCHO_URL | Honcho API 基础 URL | （必填） |
| HONCHO_WORKSPACE | Honcho 工作区名称 | （必填） |
| HONCHO_USER_PEER | 代表用户的对等方 ID | user |
| HONCHO_AGENT_PEER | 代表智能体的对等方 ID | agent |

注意： 高级选项（防抖、召回预算、超时）使用合理的默认值，很少需要调整。如果你确实需要自定义它们，请编辑 src/index.mjs 顶部的 DEFAULTS 对象。

Honcho 服务器设置

如果你还没有运行 Honcho：

使用 Docker 快速开始
docker run -d --name honcho \
-p 8000:8000 \
-e HONCHO_API_KEY="your-api-key" \
plasticlabs/honcho:latest

或从源码自托管（生产环境推荐）
参见：https://github.com/plastic-labs/honcho#self-hosting

创建工作区和对等方：

curl -X POST http://localhost:8000/v3/workspaces/my-workspace \
-H "Authorization: Bearer $HONCHO_API_KEY" \
-H "Content-Type: application/json"

curl -X POST http://localhost:8000/v3/workspaces/my-workspace/peers \
-H "Authorization: Bearer $HONCHO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"id": "user"}'

curl -X POST http://localhost:8000/v3/workspaces/my-workspace/peers \
-H "Authorization: Bearer $HONCHO_API_KEY" \
-H "Content-Type: application/json" \
- d '{"id": "agent"}'

工具

记忆
| 工具 | 描述 |
|------|-------------|
| honcho_recall | 混合语义搜索（消息 + 结论）。快速（2-5 秒）。 |
| honcho_ask | 与对等方进行深度辩证推理。较慢（2-5 分钟）但更全面。 |
| honcho_remember | 将事实/陈述保存到 Honcho 记忆。 |
| honcho_context | 获取会话的压缩对话上下文。 |

搜索
| 工具 | 描述 |
|------|-------------|
| honcho_search | 搜索所有会话（无日期过滤）。 |
| honcho_session_search | 在特定会话内搜索。 |

档案
| 工具 | 描述 |
|------|-------------|
| honcho_profile | 获取对等方的卡片（身份、属性、关系）。 |
| honcho_representation | 获取对等方的表示（压缩的观察结果）。 |

会话
| 工具 | 描述 |
|------|-------------|
| honcho_session | 列出会话。 |
| honcho_session_create | 创建新会话。 |
| honcho_session_clone | 克隆现有会话。 |
| honcho_session_peers | 列出/添加/移除会话中的对等方。 |
| honcho_session_summaries | 获取会话摘要（压缩的上下文）。 |
| honcho_session_context | 获取完整对话上下文。 |

对等方
| 工具 | 描述 |
|------|-------------|
| honcho_peer | 列出所有对等方。 |
| honcho_peer_create | 创建或获取对等方。 |
| honcho_peer_list | 列出所有对等方（别名）。 |

消息
| 工具 | 描述 |
|------|-------------|
| honcho_message_send | 向会话发送消息。 |
| honcho_message_get | 按 ID 获取消息。 |

结论
| 工具 | 描述 |
|------|-------------|
| honcho_conclude | 创建显式结论。 |
| honcho_conclude_list | 列出结论。 |
| honcho_conclude_query | 对结论进行语义搜索。 |

管理
| 工具 | 描述 |
|------|-------------|
| honcho_status | 健康检查 + 队列统计。 |
| honcho_dream | 触发 dream（card_refresh 或 omni）。 |
| honcho_queue | 检查处理队列状态。 |

会话策略

- per-directory（默认）：每个工作目录拥有自己的 Honcho 会话（例如 dsh-home-user-project）。不同目录中的对话相互隔离。
- global：所有对话共享一个会话，无论目录如何。

自动同步与持久化

- 消息通过可配置的防抖进行同步（默认 3 秒）。
- 同步游标持久化到 ~/.dsh/honcho-sync-state.json —— 在 HMR 和 DSH 重启后仍然保留。
- 重启时，仅同步自上次游标以来的新事件（无重复）。

记忆注入

当启用 autoRecall 时，在每个会话的第一条用户消息上：

1. 获取两个对等方的对等方卡片（档案）
2. 获取表示并去重（移除语义重叠）
3. 使用用户的消息作为查询运行语义搜索查询
4. 结果被包裹在  标签中并注入到系统提示中

隐私
- 所有数据都保留在你的 Honcho 服务器上。不会向第三方传输数据。
- 该插件不会记录消息内容。
- 配置（URL、workspace、peer ID）存储在 DSH 设置中，而不是插件源码中。

故障排查

| 症状 | 修复方法 |
|---------|-----|
| 启动时出现 HONCHO_URL is required | 在 ~/.config/systemd/user/dsh-web.service 中通过环境变量设置。 |
| 没有进行同步 | 检查 autoSync 是否为 true，验证 Honcho URL 是否可访问，检查日志：journalctl --user -u dsh-web \| grep honcho |
| 召回返回为空 | 确保 Deriver 已处理消息（检查 honcho_queue），首次同步后等待几分钟 |
| 401 Unauthorized | 检查服务器配置中的 Honcho API key |
| 找不到会话 | 验证 workspace 名称与你的 Honcho workspace 完全一致 |

许可证

MIT

中文说明

Honcho 记忆插件，为 DeepSeek Harness 提供持久化跨会话记忆，基于自托管的 Honcho v3 服务。

功能

- 自动同步：每轮对话自动同步到 Honcho（带防抖）。同步游标跨重启持久化。
- 混合召回：同时搜索原始消息和推理结论（显式/演绎/归纳），并行执行。
- 记忆注入：会话开始时，将相关的 peer 卡片、表征和语义召回结果注入系统提示词。
- 25 个工具：覆盖 Honcho v3 完整 API — 搜索、画像、会话管理、peer 管理、结论、做梦、队列监控。

依赖

- DeepSeek Harness (DSH) web profile
- 一个运行中的 Honcho v3 实例（自托管）
- Node.js >= 18

安装

从 npm
dsh plugin --profile web add npm:@nanpaidashi/dsh-honcho-sync dsh web

或从 GitHub
dsh plugin --profile web add link:https://github.com/nanpaidashi/dsh-honcho-sync dsh web

然后重启 DSH：

systemctl --user restart dsh-web
或: dsh web --restart

升级

如果你安装过旧版本（v0.6.x 或 v0.7.0）：

重跑同一条安装命令 — 会拉取最新版并覆盖
dsh plugin --profile web add npm:@nanpaidashi/dsh-honcho-sync dsh web
或
dsh plugin --profile web add link:https://github.com/nanpaidashi/dsh-honcho-sync dsh web

systemctl --user restart dsh-web

安装是幂等的：原地替换插件源码文件。你的配置（环境变量）和同步状态（~/.dsh/honcho-sync-state.json）会保留 — 无数据丢失，无需重新配置。

v0.8.0 → v0.8.1 变更

- 上下文效率：注册工具从 25 个精简到 4 个（honcho_recall、honcho_ask、honcho_remember、honcho_context）— 每会话节省约 7K tokens 的工具 schema 注入
- 注入质量：新增 _filterRepresentation() — 从表征注入中过滤 Pattern [medium]/[low] 块、Premises/Sources 溯源链、孤立 Type/Sources 行
- 注入质量：新增 _assembleByPriority() — 按优先级组装 memory-context（peer-card > session-summary > semantic-recall > representation）
- 注入预算：injectionMaxChars 默认 8000 → 4000，reprMaxObs 默认 8 → 4
- 工具描述：所有工具描述精简到 ~100 字符

v0.7.x → v0.8.0 变更

- DSH 0.1.0-rc.8 兼容：添加 normalizeToolParameters() 将旧式参数简写转换为标准 JSON Schema
- DSH 0.1.0-rc.8 兼容：添加 output.render 返回 content blocks 数组（DSH >= 2026 要求）
- README：移除设置面板说明 — 配置通过 ~/.config/systemd/user/dsh-web.service 中的环境变量完成
- 修复 conclusions/query 需要 filters 参数
- 修复 /search、/peers/list、/summaries 响应解析
- 修复 POST /conclusions 请求体格式
- 修复 schedule_dream 参数名（dream_type）
- 新增 4 个工具：honcho_conclude、honcho_conclude_list、honcho_conclude_query、honcho_message_get
- 混合召回现在并行搜索消息和结论

卸载
1. 从 DSH 移除插件
dsh plugin --profile web remove honcho-sync dsh web

2.（可选）删除同步状态文件
rm ~/.dsh/honcho-sync-state.json

3. 重启 DSH
systemctl --user restart dsh-web

注意： 卸载插件不会删除你的 Honcho 数据。所有消息、结论和 peer 卡片仍然保留在你的 Honcho 服务器上。插件只是桥梁 — 你的记忆是安全的。

配置

没有设置面板。 所有配置通过 DSH 服务文件中的环境变量完成。

第一步：编辑 DSH 服务文件

systemd (Linux)
nano ~/.config/systemd/user/dsh-web.service

在 [Service] 部分添加环境变量：

[Service]
Environment="HONCHO_URL=http://localhost:8000"
Environment="HONCHO_WORKSPACE=my-workspace"
Environment="HONCHO_USER_PEER=user"
Environment="HONCHO_AGENT_PEER=agent"

第二步：应用更改

systemctl --user daemon-reload
systemctl --user restart dsh-web

配置参考

| 变量 | 说明 | 默认值 |
|------|------|--------|
| HONCHO_URL | Honcho API 地址 | (必填) |
| HONCHO_WORKSPACE | Honcho 工作区名称 | (必填) |
| HONCHO_USER_PEER | 用户 peer ID | user |
| HONCHO_AGENT_PEER | Agent peer ID | agent |

注意： 高级选项（防抖、召回预算、超时）使用合理的默认值，很少需要调整。如需自定义，编辑 src/index.mjs 顶部的 DEFAULTS 对象。

Honcho 服务器搭建

如果你还没有运行 Honcho：

Docker 快速启动
docker run -d --name honcho \
-p 8000:8000 \
-e HONCHO_API_KEY="your-api-key" \
plasticlabs/honcho:latest

或从源码自托管（生产环境推荐）
参考: https://github.com/plastic-labs/honcho#self-hosting

创建工作区和 peers：

curl -X POST http://localhost:8000/v3/workspaces/my-workspace \
-H "Authorization: Bearer $HONCHO_API_KEY" \
-H "Content-Type: application/json"

curl -X POST http://localhost:8000/v3/workspaces/my-workspace/peers \
-H "Authorization: Bearer $HONCHO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"id": "user"}'

curl -X POST http://localhost:8000/v3/workspaces/my-workspace/peers \
-H "Authorization: Bearer $HONCHO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"id": "agent"}'

工具列表

记忆
| 工具 | 说明 |
|------|------|
| honcho_recall | 混合语义搜索（消息 + 结论）。快（2-5秒）。 |
| honcho_ask | 与 peer 深度辩证推理。慢（2-5分钟）但全面。 |
| honcho_remember | 保存事实/陈述到 Honcho 记忆。 |
| honcho_context | 获取会话的压缩上下文。 |

搜索
| 工具 | 说明 |
|------|------|
| honcho_search | 跨所有会话搜索（无日期过滤）。 |
| honcho_session_search | 在特定会话内搜索。 |

画像
| 工具 | 说明 |
|------|------|
| honcho_profile | 获取 peer 卡片（身份、属性、关系）。 |
| honcho_representation | 获取 peer 表征（压缩观察）。 |

会话
| 工具 | 说明 |
|------|------|
| honcho_session | 列出会话。 |
| honcho_session_create | 创建新会话。 |
| honcho_session_clone | 克隆现有会话。 |
| honcho_session_peers | 列出/添加/移除会话中的 peer。 |
| honcho_session_summaries | 获取会话摘要（压缩上下文）。 |
| honcho_session_context | 获取完整对话上下文。 |

Peer
| 工具 | 说明 |
|------|------|
| honcho_peer | 列出所有 peer。 |
| honcho_peer_create | 创建或获取 peer。 |
| honcho_peer_list | 列出所有 peer（别名）。 |

消息
| 工具 | 说明 |
|------|------|
| honcho_message_send | 向会话发送消息。 |
| honcho_message_get | 按 ID 获取消息。 |

结论
| 工具 | 说明 |
|------|------|
| honcho_conclude | 创建显式结论。 |
| honcho_conclude_list | 列出结论。 |
| honcho_conclude_query | 跨结论语义搜索。 |

管理
| 工具 | 说明 |
|------|------|
| honcho_status | 健康检查 + 队列统计。 |
| honcho_dream | 触发做梦（card_refresh 或 omni）。 |
| honcho_queue | 查看处理队列状态。 |

会话策略

- per-directory（默认）：每个工作目录对应独立的 Honcho 会话（如 dsh-home-user-project）。不同目录的对话互相隔离。
- global：所有对话共享一个会话，不区分目录。

自动同步与持久化

- 消息以可配置的防抖间隔同步（默认 3 秒）。
- 同步游标持久化到 ~/.dsh/honcho-sync-state.json — 跨 HMR 和 DSH 重启保留。
- 重启后只同步游标之后的新事件（无重复）。

记忆注入

当 autoRecall 启用时，每个会话的首条用户消息触发：

1. 获取两个 peer 的卡片（画像）
2. 获取表征并去重（语义重叠移除）
3. 以用户消息为查询执行语义搜索
4. 结果包裹在  标签中注入系统提示词

隐私

- 所有数据保留在你的 Honcho 服务器上。无第三方数据传输。
- 插件不记录消息内容。
- 配置（URL、工作区、peer ID）通过环境变量存储在 DSH 服务文件中，不在插件源码里。

故障排查

| 症状 | 解决方案 |
|------|----------|
| 启动时 HONCHO_URL is required | 通过设置面板或环境变量配置。如果设置异步加载，此消息无害。 |
| 没有同步发生 | 检查 autoSync 是否为 true，确认 Honcho URL 可达，查看日志：journalctl --user -u dsh-web \| grep honcho |
| 召回返回空 | 确认 Deriver 已处理消息（检查 honcho_queue），首次同步后等待几分钟 |
| 401 Unauthorized | 检查 Honcho 服务器配置中的 API key |
| Session not found | 确认 workspace 名与 Honcho 工作区完全一致 |

许可

MIT