dsh-sgme

dsh-sgme — SGME 记忆引擎 DSH 插件

把 SGME 拾光记忆引擎 接入 DeepSeek Harness（DSH），让 DSH 拥有多智能体共享的长期记忆与主动关怀能力。

你的 AI，从此记得你——聊过的事，它都记得，还会主动关心你。

能力

能力	说明
画像自动注入	agent/pre-step middleware：会话首步自动拉取 SGME 画像 + 相关记忆注入模型上下文（v2，2026-08-16 从"打日志"升级为真注入）
自动捕获	session-sync 监听会话事件，每轮对话自动 append 落盘（零 LLM 成本）
记忆检索	memory_search 检索 L1.5 标签化记忆池（带溯源）
知识库检索	wiki_search 检索 L2 场景知识库（比记忆更精炼）
技能按需注入	skill_search / skill_digest / skill_get / skill_list / skill_coldstart 五工具（v0.4.0）——对齐 SGME 1.1.0 范式：技能不预载，按需检索 → 拉全文注入
聚合答案	answer（v0.5.0）——跨会话计数/列举/时序推理（「我一共提过几次 X」），比记忆检索多一步 LLM 答案合成
运维观测	health / stats / config_get / config_update / refine_status / refine_trigger / refine_batch / signal_clear（v0.5.0）——连接自检、记忆水位、提炼监控与配置读写
技能写侧	skill_materialize（L3 字节保真落盘成真文件）/ skill_put / skill_delete / skill_rename（v0.5.0）
主动关怀	signal_pull / signal_claim / signal_ack 三工具，消费 SGME 关怀信号——信号消费 = 主动关怀，谁消费谁标记
DSH 规则注入	读取 ~/.dsh/dsg-rules/rules.md 注册为 dsg:rules system section（order -70）——身份/铁律/SGME手册/偏好/环境进稳定层，前缀缓存全命中（v0.2，2026-08-16）

前置条件

⚠️ 兼容性（DSH RC 支持矩阵，2026-10-04 实测）：

DSH 版本	验证状态
0.2.0-rc.2	✅ typecheck + 228 测试通过（开发基线，当前本机运行版）

peer 声明 ^0.2.0-rc.2 覆盖 rc.2 → <0.3.0 全部版本；DSH 处于 RC 快速迭代期，新 RC 发布后先跑一遍 rc-N 兼容验证再升级本插件（方法见发布流程文档「RC 兼容验证」一节），验证通过前不承诺新 RC 兼容。0.1.0-rc.6 ~ rc.8 的旧版支持见 dsh-sgme 0.5.x。

⚠️ 本插件依赖 SGME 本体（Python 服务 :9910），没有它插件是空壳——先装本体，再装插件。两种路径任选：

路径 A：Docker 一键部署（推荐）

git clone https://github.com/freehul/sgme.git
cd sgme
docker compose up -d                      # 首次自动构建镜像并启动（HTTP 9910）
curl http://localhost:9910/v1/health      # 返回 {"status":"ok"} 即就绪

需要本机已装 Docker；若 SGME 部署在其他机器/NAS，跳过本机安装，直接把下面的 SGME_BASE_URL 指过去即可。

路径 B：Python 本地开发

git clone https://github.com/freehul/sgme.git
cd sgme
python -m venv .venv                      # 需 Python 3.11+
.venv\Scripts\activate                # Windows；Linux/macOS: source .venv/bin/activate
pip install -e .
cp config/.env.example .env               # 填入 DEEPSEEK_API_KEY / VOLC_API_KEY 等密钥
python -m sgme                            # 启动服务（HTTP 9910 常驻）
curl http://localhost:9910/v1/health

注册 agent 拿密钥（两条路径都需要）：本体启动后运行 adapters/dsh/install.py，注册 DSH agent，把 SGME_AGENT_KEY / SGME_ADMIN_KEY 写入 .env。

服务地址：插件 baseUrl 由环境变量 SGME_BASE_URL 注入（缺省指向 NAS <NAS_IP>:9910，面向多 agent 共享场景）。本地部署时设 SGME_BASE_URL=http://127.0.0.1:9910 即可，无需改代码。

安装

# 安装到 profile（dsh plugin 转发 pnpm）
dsh plugin --profile <你的profile> add dsh-sgme

安装后验证（三步自检）

• 确认插件已挂载：dsh --profile <你的profile> --dump-config，输出应含 dsh-sgme；
• 一条命令自检：会话内输入 /sgme（或 /sgme status）——显示 SGME 连接状态、版本、LLM、记忆水位；不可达时直接给出本体安装指引；
• 首次对话观察：对话开始会自动注入画像与相关记忆；可先 /sgme 试试 确认检索链路。

冷启动提示：新装后记忆池是空的，前几轮对话后记忆才开始积累；wiki_search 可立即查到 SGME 自带的操作手册，skill_coldstart 可拉到技能检索协议 + SGME 操作手册。

故障排查

现象	原因	处理
/sgme status 显示不可达	SGME 本体未启动或地址不对	按「前置条件」装好本体，确认 curl /v1/health 返回 200；本地部署设 SGME_BASE_URL=http://127.0.0.1:9910
401 / key 无效	agent key 未注册或过期	运行 adapters/dsh/install.py 重新注册
插件加载报版本不兼容	dsh 版本与插件锁定版本不符	本插件面向 dsh 0.2.0-rc.2，升级 dsh 前先确认兼容
注入/检索超时或异常走外网	代理劫持 localhost	插件 fetch 显式禁用代理；检查系统代理是否拦截 127.0.0.1
日志去哪看	—	插件日志在 dsh stderr；SGME 日志在 logs/（本机）或 docker logs sgme（容器）

配置

cordis.patch.yml 默认值：

baseUrl: process.env.SGME_BASE_URL ?? 'http://<NAS_IP>:9910'   # 环境变量注入，缺省指向 NAS
agentKey: process.env.SGME_AGENT_KEY   # 环境变量注入，密钥不落盘
adminKey: process.env.SGME_ADMIN_KEY
agentId: dsh
injectMode: daily
syncOnTurnEnd: true

• baseUrl 与密钥均通过环境变量注入（符合 SGME 密钥不落盘铁律）；SGME_BASE_URL 缺省指向 NAS（<NAS_IP>:9910），SGME 部署在其他机器时改环境变量即可，无需改代码；
• 生产环境请用 SGME 的 adapters/dsh/install.py 注册 agent 后覆盖 dev key（install.py 已把 SGME_BASE_URL 一并写入 .env）。

用法

接入后，DSH 自动拥有 42 个工具（v0.6.1 起与 SGME 1.10.2 能力面对齐，适配器平级对账零漂移）：

检索与知识库（7）

• memory_search(query, limit, dimensions, match) — 查历史事实/偏好/决策，涉及「之前/以前/还记得」时必用；
• conversation_search(query, limit) — 检索 L0 原始会话正文（FTS 原文层），与 memory_search 互补（v0.6.0 起）；
• wiki_search(query, limit) — 查提炼后的场景知识（FTS5 BM25 + 中文分词）；
• wiki_pages(category, limit) — 按 category 列知识库手册目录（如 skill/sgme），渐进式披露 L2 索引层（W5）；
• wiki_page(page_id) — 按 page_id 拉取知识库手册全文（技能手册/踩坑记录），索引 skill 引导的加载通道（W5）；
• wiki_page_update(page_id, content, append) — 追加/覆盖知识库手册正文（W5 回写通道）；
• wiki_page_add(title, content, category, tags) — 新建知识库页面（幂等 upsert）。

技能层（5，v0.4.0 新增，对齐 SGME 1.1.0 范式）

• skill_search(query, limit) — 检索 SGME 技能库，只返回技能名与触发描述；
• skill_digest(name) — 技能摘要：字段 + 正文骨架 + uses 依赖，执行前审核用；
• skill_get(name, section) — 拉技能全文注入上下文（section 可只取一节省 token）；
• skill_list(limit, offset) — 分页浏览技能库索引；
• skill_coldstart() — 冷启动包：1 个《技能检索协议》+ SGME 操作手册。

⚠️ 技能不预载，按需「先 skill_search 检索 → 再 skill_get 拉全文」注入——这是 SGME 1.1.0 的既定范式（B114 技能去 wiki 化后，技能正文已不在 wiki 里，wiki 通道搜不到技能手册）。

主动关怀（3）

• signal_pull(signal_type, limit) — 会话开始拉未消费关怀信号；
• signal_claim(event_id) — 原子认领信号（谁消费谁标记）；
• signal_ack(event_id, status, result) — 写消费回执。

三池登记（3，Agent 主动维护）

• idea_add(content, priority, source_ref) — 创意池（仅用户主动提出才记）；
• demand_create(title, content, priority, project_id) — 待办池（跨项目统一，会话中遇到要办的事主动登记）；
• project_register(project_id, path, name, git_repo, milestone) — 项目池（用户立项时登记）。

角色与记忆纠错（8）

• inject(mode) — 按场景模式拉画像；
• role_list() / role_assemble(role_id, inject_mode) / role_active_get() / role_active_set(role_id) — 角色模板（换皮不换芯）；
• memory_get(memory_id) / memory_reject(memory_id, reason) / memory_unreject(memory_id) — 记忆详情、纠错与撤销纠错。

聚合答案（1，v0.5.0 对齐 T-149）

• answer(query, question_type, limit) — 聚合型问题直接拿答案（跨会话计数/列举/时序推理）；比 memory_search 多一步 LLM 答案合成，适合「我一共提过几次 X」「Y 是什么时候改的」。

运维观测与配置（7，v0.5.0）

• health() — 连接自检：版本 / LLM / 提炼水位与停摆 / 向量水位；
• stats() — 记忆与原始层计数、维度分布、提炼水位、已注册 agent；
• config_get(section) / config_update(section, values) — 读/写服务端运行时配置（热生效）；
• refine_status(limit, status) / refine_trigger(file_id, limit) / refine_batch(file_id, limit) — 提炼监控与触发（前者只读；后两者消耗 LLM 额度）。

信号清理与自进化（2，v0.5.0）

• signal_clear(signal_type, subscriber_id) — 批量清空未消费信号（幂等）；
• wiki_evolve_trigger(session_key, min_rounds) — 手动补触发自进化（每轮已自动触发）。

技能物化与写侧（4，v0.5.0 对齐 ST-36 M3）

• skill_materialize(name, dest_dir) — L3 字节保真落盘 <dest_dir>/<name>/SKILL.md，返回路径 + sha256（要按真文件路径执行脚本时用）；落盘在 SGME 服务端文件系统——跨机（agent 在本地、SGME 在远端）时产物不在本机，改用包通道 GET /v1/skills/{name}/package（或 skill_fetch.py --name <name> --dest <工作区> 一键下载校验解包）；
• skill_put(name, content, skip_limits) — 写入/覆盖技能（过 lint 门禁 + 三层查重后落盘并提交技能源仓）；
• skill_delete(name, hard, force) — 删除技能（默认软删；有入向引用需 force）；
• skill_rename(name, new_name) — 墓碑制改名。

凭据读侧（2，T-277 对齐 EP-11）

• credential_list() — 凭据键名 + 元数据（不含值；需服务端 credentials.enabled 已启用）；
• credential_get(name) — 取凭据单值（服务端记 read 审计）。⚠️ 值不得进入对话正文——标准姿势是客户端注入（sgme-cred run，值不落盘不进对话）；本工具仅限「必须显式查看」场景，取用后勿复述值。

⚠️ 写侧工具（config_update / skill_put / skill_delete / skill_rename / refine_* / signal_clear）需 Admin Key，且会真实改变服务端状态或消耗额度——工具描述内已加护栏，仅在用户明确要求时调用。

自进化（W4）：每个 turn 结束自动触发 SGME 经验回写（/v1/wiki/evolve/trigger，evolveEnabled 默认 true）——会话中的踩坑/新流程由 LLM 提炼后追加到知识库手册「踩坑记录」，多 agent 共享。

接入纪律

DSH 接入 SGME 后应遵守五条铁律（详见 SGME 接入文档）：

• 每轮对话结束 append 当前轮次；
• 会话结束 refine_trigger(async_mode=true)；
• 对话开始 inject / search 取画像与记忆；
• 主动关怀靠消费信号：signal_pull → signal_claim → 关怀 → signal_ack；
• 角色模板：role_list / role_assemble 换皮不换芯。

通信渠道兜底：当前会话是兜底通信渠道，任何主动消息都必须在当前会话也发一条，直到用户取消。

协议

• HTTP API（:9910）+ MCP（:9913），鉴权 X-API-Key；
• 事件对接：SSE 长连 GET /v1/events/stream / 游标拉取 GET /v1/events/pull（常驻 agent 首选 SSE）。

开发

pnpm install
pnpm run verify   # typecheck + test + build

许可证

MIT © 2026 freehul