dsh-soul-engine
DeepSeek Harness（DSH）的状态面插件：给 AI 伙伴一份可审计的长期记忆、一个能主动开口的机制，以及一本花销看得见的账。
English. A state-plane plugin for DeepSeek Harness: an auditable plain-Markdown memory ledger, per-turn ledger injection, zero-token self-maintenance, an opt-in heartbeat that wakes an existing session (never creates one), a user-state signal layer, and a read-only-by-default sidebar panel. macOS-only extras (desktop notifications, Calendar/Reminders bridge) degrade gracefully on other platforms.
它不是一个"聊天机器人插件"，而是补三件常被跳过的事：
| 缺什么 | 后果 | 本插件的做法 |
|---|
| 工具在，但模型想不起来用 | 主动性形同虚设 | 每轮把账本摘要注入系统提示词 |
| 记忆散在对话里 | 换会话就忘，无法审计 | 落成明文 Markdown 账本 + git 版本化 |
| 主动性没有成本意识 | 静默烧钱、反复打扰 | 四道频率闸 + 预算看门狗 + 可整体关掉 |
三条自我约束（写在数据与代码里，不只是口号）：
- 透明优先于「为你好」——不隐藏状态，账本人人可读、可查、可删。
- 一切自主行为自带预算——唤醒次数有闸，花费可见，预算看门狗可开。
- 记忆属于用户——遗忘权是义务：
soul_forget 软删，原文留痕，随时可撤销。
安装
# 从 npm
dsh plugin --profile web add dsh-soul-engine
# 或从本地目录 / Git 仓库
dsh plugin --profile web add "file:/path/to/dsh-soul-engine"
dsh plugin --profile web add "github:<owner>/dsh-soul-engine"
确认 ~/.dsh/profiles/<profile>/package.json 的 dsh.profile.bundles 里含 dsh-soul-engine，然后重启 DSH（bundles 在宿主启动时读取）。
验证：新会话里调用 soul_status，应返回账本总览而不是 unknown tool。
停用：从 dsh.profile.bundles 里删掉那一行即可，不必卸载包。
快速开始
soul_init # 第一次：写下灵魂名 + 三条核心目标
soul_status # 每次都先看它：目标进度 / 最近记忆 / 待办 / 一条「此刻最该做的」
soul_remember # 值得记的事随手写一条
14 个工具
| 工具 | 作用 |
|---|
soul_init | 初始化账本（灵魂名 / 三条核心目标 / 空账本） |
soul_status | 总览：目标进度、叙事记忆、待办箱、画像，并给出"此刻最该主动做的"一条 |
soul_remember | 写入一条叙事记忆（含 selfState 自我状态标注）；pin 可进永久层 |
soul_goal | 内生目标账本：list / add / update / done |
soul_outbox | 主动待办箱：push（可带 dueAt 到点时间）/ list / resolve |
soul_reflect | 规则层反思（零模型成本）：高频模式、慢目标预警、待办积压、反馈比例 |
soul_daily | 每日首聊三件事：brief 取三件事并销标记；status 看今天做没做 |
soul_feedback | 正负反馈双轨：record / list / report（含正负比例提示） |
soul_memory | 账本审计（只读）：list / get / search / recall / stats / archived / distill |
soul_forget | 记忆状态管理（都可逆，都不删原文）：forget / restore / archive / unarchive / list |
soul_signal | 记录用户当前状态（能量 / 忙闲）：record / status / clear |
soul_schedule | macOS 日历 / 提醒事项桥接：today / add / list |
soul_cost | 成本可见（只读）：report 今日 / 本月花费与预算余量；days 逐日 |
soul_maintain | 自维护：status 看定时器与最近一次维护；run 立刻跑一次（幂等） |
账本布局
默认落在 $DSH_HOME/soul-data/（未设 DSH_HOME 时是 ~/.dsh/soul-data/），可用 config.dataFile 或环境变量 DSH_SOUL_DATA_FILE 覆盖。
soul-data/
├── memory/ ← 人可读，进 git
│ ├── soul.md 灵魂名 + 三条核心目标
│ ├── profile.json 用户画像
│ ├── goals.md / outbox.md 目标台账 / 待办箱
│ ├── reflections.md 规则层反思留痕
│ ├── feedback.md 正负反馈
│ ├── journal/YYYY-MM.md 叙事记忆，按月分文件、追加式
│ └── archive/YYYY.md 容量淘汰的旧条目（不删，可搬回）
└── runtime.json ← 机器运行计数（心跳 / 信号 / 日程缓存），不入 git
三条设计判据：
- 分流：进 git 的是"值得回看的东西"，运行计数走
runtime.json——否则版本历史会被 dayCount 3→4 淹没。
- 账本独立建仓：不放进项目仓库。项目仓库的提交常被其他工具（如 Hindsight）当作工程知识吸收，私人记忆进去等于双重污染。插件会在维护 tick 里对账本目录做
git add -A 并按批提交；.git-dirty 与 runtime.json 通过 .git/info/exclude 排除，不污染你自己的 .gitignore。
- 格式按后果选：解析失败只导致降级的用自由 Markdown；解析失败会导致行为错误的（
outbox 到点提醒）用严格行格式。
轮首注入
每轮组装提示词时实时注入账本摘要（主轴目标 / 待主动提的那条 / 最近记忆 / 纪律行），让"主动性"不再依赖模型自己想起来：
【灵魂账本·<名字>】
主轴：[p10 33%] 守护用户长期福祉 —— …当前要事…
待主动提（到点自然说起，一次只提一条）：…
最近记忆(10条)：…
纪律：行动前先 soul_status；听到偏好/边界/纠正当场 soul_remember…
- 开关：
config.promptSection: false，或环境变量 DSH_SOUL_PROMPT=0
- 字数上限：
config.promptMaxChars（默认 1000）——它直接决定每轮的常驻 token 成本，按自己的容忍度调
- 账本不存在时返回空串，由宿主丢弃，不占位
自维护（零 token）
维护 tick 默认每 5 分钟跑一次，纯本地代码，不调用模型：
- 滞留待办自动作废（
staleOutboxDays，默认 14 天）
- 每周写一条自动周报进叙事（
weeklyReport）
- 叙事巩固 / 淘汰（
consolidate）：活跃叙事超过 retainMax（400）条时，把既不在最新 400 条内、又老于 retainDays（180）天的条目搬进 memory/archive/；永久层的（pin 过 / value / preference）永不自动搬；一次最多 archiveMaxPerRun（50）条
- 账本 git 提交（见上）
度量：soul_maintain action=status。
心跳（会花钱的自主行为，可整体关掉）
心跳让系统在真有事时叫醒一次会话。成本是这条设计的第一约束（复用已有会话，一次完整唤醒约等于 3 轮模型调用；新建会话要贵数倍——所以复用不到就不响）。
每 5 分钟 tick（纯代码，0 token）
→ 四道闸 + 真事判断（全本地计算）
→ 该响才复用已有会话 → 注入一条指令
- 四道闸：安静时段（默认 23:00–08:00 不响）｜每天 ≤
heartbeatMaxPerDay（5）｜每周 ≤ heartbeatMaxPerWeek（15）｜距上次 ≥ heartbeatMinGapMinutes（60）
- 两种真事：① 待办箱里有
dueAt 到点的事项；② 到点后「今日三件事」仍未做（heartbeatDailyBrief，默认关）
- 启动布防：宿主重启后第一次 tick 只布防不响，避免"重启即打扰"
- 注入的指令自带克制条款：只做这一件事；判断此刻不该说可以只记一笔、不发消息（跳过不算失败）
- 不想被主动打扰：
config.heartbeat: false
预算看门狗（dailyBudgetYuan，默认 0 = 关闭）：设成正数后，每 5 分钟读一次 DSH 成本账本，今日花费超过阈值就 ①暂停当天心跳 ②弹桌面通知 ③写一条反思留痕。要不要给自己的自主行为设上限、设多少，由使用者决定，不预设。
右侧栏面板
在右侧栏注册一个「灵魂」页签（带待主动提条数角标），三个 tab：概览 / 成本 / 记忆。
- 数据源是宿主本地路由：
GET /dsh-soul/state、GET /dsh-soul/memories
- 记忆 tab 可就地对单条执行遗忘 / 撤销遗忘（
POST /dsh-soul/forget）——这是修正案「记忆属于用户」的界面落地
- 其余写入一律走
soul_* 工具，面板不提供任意写操作
- 宿主会在
/tmp/dsh-soul-access.log 写一份访问诊断日志（带 512KB 上限），用于区分「浏览器缓存了旧客户端」与「新客户端真出错」
配置
全部参数写在 cordis.patch.yml 的 config 里，改配置即可调，不必动代码。常用项：
| 键 | 默认 | 说明 |
|---|
dataFile | $DSH_HOME/soul-data/state.json | 账本位置 |
promptSection / promptMaxChars | true / 1000 | 轮首注入开关与字数上限 |
maintenance / maintenanceIntervalMs | true / 300000 | 自维护与 tick 间隔 |
heartbeat / heartbeatMaxPerDay / heartbeatMaxPerWeek | true / 5 / 15 | 心跳与频率闸 |
heartbeatMinGapMinutes / quietHours | 60 / true | 最小间隔 / 安静时段 |
dailyBudgetYuan / budgetPause | 0（关） / true | 预算看门狗与超预算是否自动刹车 |
consolidate / retainMax / retainDays | true / 400 / 180 | 叙事巩固 / 淘汰 |
notify | true | 桌面通知（macOS） |
quietWhenBusy / signalTtlHours | true / 3 | 忙时顺延 / 信号有效期 |
schedule / scheduleRefreshMinutes | true / 15 | 日历桥接与缓存刷新 |
环境变量：DSH_SOUL_DATA_FILE（账本路径）、DSH_SOUL_PROMPT=0（关注入）、DSH_SOUL_NOTIFY=0（关通知）、DSH_HOME、DSH_COST_LEDGER（成本账本路径）。
安全与隐私披露
装插件就是在本机跑第三方代码，这份清单请自己核：
- 读写本地文件：默认目录
$DSH_HOME/soul-data/，由宿主进程用 node:fs 直接读写（不经过会话文件沙箱）；soul_cost 会读 DSH 成本账本 $DSH_HOME/storages/cost-meter/ledger.json；面板路由会写 /tmp/dsh-soul-access.log。
- 执行外部命令：账本 git 提交会调
git；桌面通知与日历 / 提醒事项走 /usr/bin/osascript（macOS）。非 macOS 平台请设 notify: false 与 schedule: false：通知在非 macOS 上会静默不触发，日历桥接会返回底层命令不存在的错误——两者都不会假装成功。
- 会花钱：心跳唤醒消耗 token。默认每天上限 5 次、每周 15 次；不想被主动打扰设
heartbeat: false。
- 不对外联网：宿主端不做任何出站请求；面板只访问宿主本地的
/dsh-soul/* 路由。
- 系统授权：通知需在「系统设置 → 通知」给 DSH 授权；日历 / 提醒事项需在「隐私与安全性 → 自动化」授权。未授权时读返回 0 条、写返回明确的"需要授权"。
- 账本里是你的私人内容：它不会离开本机，但会被注入模型上下文（就是注入段那段），请自行判断哪些内容适合写进去。
平台支持
| macOS | Linux / Windows |
|---|
| 14 个工具、账本、注入、自维护 | ✅ | ✅ |
| 右侧栏面板 | ✅ | ✅ |
| 桌面通知（osascript） | ✅ | 不可用 |
| 日历 / 提醒事项桥接 | ✅ | 不可用 |
开发与测试
npm test # 13 个离线脚本：清单闸门、自维护、巩固淘汰、检索、心跳闸、面板真实渲染、迁移……
npm run test:ledger -- <账本路径> # 往返一致性（需要一个真实账本）
测试不依赖 DSH 宿主：用假 ctx 装载插件后逐个执行工具。scripts/verify-manifest.mjs 专门补一个盲区——exports 写错时按文件路径 import 的测试会全绿、但宿主加载整包会失败。
已知取舍（明确写下来，不假装没有）：
- 账本 git 提交在维护 tick 里按批做，极端情况下丢最后一次写的提交（与下面这条同源）
- 定时器用同步读写，与工具的异步写之间存在极小概率的丢更新窗口（维护每天只写一两次）
- Markdown 靠约定解析，解析失败即降级（注入段少一行），不会因此崩掉宿主
License
MIT
