dsh-brain/README.md

203 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# dsh-cloud-memory
把 DeepSeek Harness 接到 LongMemory 云端记忆服务:**每轮对话结束自动上报一条活动记录**(只上传元数据),并把云端记忆库变成 agent 可用的工具。
当前版本 **0.1.1**,含宿主端与浏览器端两部分:host 半负责活动上报与工具注册,`client/index.js` 提供「设置 → 插件 → 云端记忆」配置卡片。
## 它做什么
| 能力 | 说明 |
| --- | --- |
| 活动上报 | 监听 `session/event` 的 `turn/start`、`turn/end`,每个结束的回合调用一次 `POST /activity/turn`。上报字段只有 6 个:`client_id`、`conversation_id`、`turn_id`、`status`、`started_at`、`completed_at`。 |
| 幂等 | `turn_id` 为 `<sessionId>:<turn>`,服务端按 `turn_id` 去重,重试不会重复计数。 |
| 失败重试 | 网络错误与 5xx 进入待重试队列(上限 200 条),每 30 秒补发一次;4xx 不重试(说明载荷或令牌有问题)。 |
| 记忆工具 | `memory_search`、`memory_read`、`memory_add`、`memory_list`、`memory_projects` 五个工具直接读写云端记忆库。 |
| 配置页 | `GET /cloud-memory` 提供完整配置界面(本 profile 关闭了原生设置页,所以自带页面)。 |
**绝不上传**:提示词正文、工具输出、文件内容、本地路径、令牌。上报载荷在类型层面就只有六个字段,构造它的函数拿不到正文。
## 安装
```powershell
# 装进当前 profile(默认 desktop)
dsh plugin --profile desktop add dsh-cloud-memory
```
装好后确认 profile 的 `package.json` 里有两处:
```jsonc
{
"dependencies": { "dsh-cloud-memory": "^0.1.0" },
"dsh": { "profile": { "bundles": [ /* ..., */ "dsh-cloud-memory" ] } }
}
```
重启 DSH,在「设置 → 插件 → 云端记忆」里配置(备用入口:`http://127.0.0.1:<当次端口>/cloud-memory`)。
> `baseUrl` 默认是占位符 `https://your-memory-host/api/longmemory`。**首次使用必须先把它改成你自己的 LongMemory 服务地址**(配置页里填,或写进 `$DSH_HOME/cloud-memory.json`),否则上报与工具都会连接失败。
## 登录(推荐)
在设置卡里填云端面板的**普通用户**账号和密码,点「登录并获取令牌」:
```
密码 → POST /api/auth/login(一次性会话 cookie)
→ POST /api/auth/tokens ×2(activity:write、memory:write)
→ 只把两个 cmt_… 令牌写进 $DSH_HOME/cloud-memory.json
→ 密码与会话 cookie 立即丢弃
```
- 密码只在这一串请求里存在:不落盘、不写日志、不随 `/cloud-memory/status` 回显。
- 服务端只保存令牌哈希,令牌可单独撤销;改密码不影响已签发令牌。
- 服务地址不是 HTTPS(且不是 loopback)时插件拒绝发送密码。
- 管理员账号不能签发个人令牌(服务端 `403 management_only`),请用普通用户。
- 也可跳过登录,直接手填两个令牌(见下)。
## 配置
配置文件 `$DSH_HOME/cloud-memory.json`(默认 `%USERPROFILE%\.dsh\cloud-memory.json`),字段:
| 字段 | 默认 | 说明 |
| --- | --- | --- |
| `enabled` | `true` | 关闭后不上报、工具直接报错。 |
| `baseUrl` | `https://your-memory-host/api/longmemory` | 服务基址,自动去掉结尾斜杠。 |
| `clientId` | `dsh-desktop` | 上报时的 `client_id`。 |
| `requestTimeoutMs` | `8000` | 单次请求超时,1000–60000。 |
| `defaultK` | `10` | `memory_search` 未指定 `k` 时的条数。 |
| `activityToken` | — | `activity:write` 令牌,形如 `cmt_…`。 |
| `memoryToken` | — | `memory:read` / `memory:write` 令牌,形如 `cmt_…`。 |
| `skillsSyncEnabled` | `true` | 云端技能中心与本机技能目录的双向同步开关。 |
| `skillsDir` | 空 | 本机技能目录覆盖;为空时用 `$DSH_HOME/skills`。 |
两个令牌也可以用环境变量 `DSH_CLOUD_MEMORY_ACTIVITY_TOKEN`、`DSH_CLOUD_MEMORY_MEMORY_TOKEN` 覆盖。
> 一个 key 只有一种 scope,所以需要两个令牌:只做上报就只填活动令牌,只做检索就只填记忆令牌。
## Mnemon 集成(记忆空间 Provider)
自 0.2.0 起,本包同时是一个 Mnemon 记忆空间 Provider:Mnemon 管本地在场
(运行时记忆每轮注入),长期记忆的每一次读、写都实时穿透到 LongMemory——
云端是真源,本地不留长期副本。因此其他工具(Claude Code、Codex、看板)
刚写进 LongMemory 的记忆,DSH 里立刻能召回。
启用方式:在 Mnemon 的记忆空间来源配置里给 providers 列表加一行
(profile 覆盖或 bundle 配置均可),然后重启 DSH:
```yaml
providers:
- use: dsh-cloud-memory/mnemon-provider
instanceId: longmemory
```
之后在 Mnemon 的插件页会出现 LongMemory 的服务字段(Endpoint / Memory
token),留空即复用本插件已有的 `cloud-memory.json` 配置,一处配置两处生效。
每个记忆空间映射一个 LongMemory 项目:发现流程会自动列出账号下的全部
项目,外加一个不分项目的「全部」空间;也可以在空间上手动填 Project ID。
v1 范围:支持 发现 / 状态 / 搜索 / 浏览 / 写入 / 按 id 读取;暂不支持
删除(LongMemory 客户端接口没有删除操作)与图谱读取(接口未暴露,
返回空图谱且能力声明为关)。离线时长期记忆不可用,Mnemon 的本地
运行时记忆不受影响。
验证:`node verify-mnemon-provider.mjs`(对本地 stub 服务跑通
发现→写入→召回→项目隔离全流程)。
## 技能同步
自 0.3.0 起,插件在记忆之外还双向同步技能:云端技能中心是总汇,本机
技能目录(默认 `$DSH_HOME/skills`)是工作副本,本地的浏览、启停、分类
仍归 DSH 技能管理器。插件启动 5 秒后首跑,之后每 15 分钟对账一次;
结果与冲突列表见 `GET /cloud-memory/status` 的 `skills` 字段,聊天里
也可以用 `skill_list` 工具查看云端清单。
- **下行**:云端技能按平台自己的规矩落地——先验整包清单哈希、再逐
文件验 sha256,原子写入,并留下 `.manifest.json` 交付记录;云端标
记了「脚本已变更待确认」的包不会自动安装,先在看板里确认。
- **上行**:本地原创技能(管理器安装、导入或手写的)自动发布到云
端;之后的修改以新修订发布,带 `expected_revision` 守卫,云端被
别人先改过就报冲突、不强行覆盖。
防事故的规矩:云端交付的技能从不回传,本地改动它只报
`locally_modified` 冲突、原样不动;本地删除不删云端,且同版本不会
被重新拉回(云端出了新版才会再下来);同名技能两边都有时互不抢占,
报 `name_collision`。云端只接受固定布局(根目录只有 `SKILL.md`,
其余文件进 `references/`、`scripts/`、`assets/`,扩展名有白名单,
单文件 ≤512 KiB、整包 ≤2 MiB、≤100 个文件),不符合的本地技能报
`unsupported_layout`,不会为了迁就而裁剪文件。
验证:`node verify-skills-sync.mjs`(对本地 stub 技能中心跑通
下行安装、上行发布与修订、改云端技能报冲突、同名冲突、脚本待审、
布局拒绝、删除不传播全流程)。
## 技能管理(内置)
自 0.4.0 起,常用的本地管理也长在插件里,页面在 `/cloud-memory/skills`
(配置页有链接进入):
- **列表**:本机全部技能,标注来源(云端交付 / 本地已传云端 / 本地)
与云端修订号;
- **启停**:停用是把技能文件夹挪到 `$DSH_HOME/skills-disabled/` 暂存
——DSH 看不见它,自然不会加载;启用再挪回来。不碰 DSH 内部机制,
可靠且可逆。同步引擎认识暂存区:停用的云端技能不会被拉回技能目
录,云端出了新版会在暂存区里原地更新;
- **删除**:真删,文件夹直接删除、不可恢复(页面上会先弹确认)。
只删本地:云端副本不动,删掉的同版本也不会被同步重新拉回来;
- **从 git 安装**:粘贴 https:// 或 file:// 仓库地址,浅克隆后把仓
库里所有带 `SKILL.md` 的文件夹装进技能目录;不执行仓库里的任何
代码,同名技能跳过不覆盖。
范围就到 DSH 技能目录这一处:技能市场的发现中心、扫描其它工具
(Codex、Cursor 等)的技能目录不在内置范围——还需要那些的话继续
留着第三方管理器,两边不冲突;不需要的话现在可以卸掉它了。
验证:`node verify-skill-admin.mjs`(列表与来源判定、启停、真删、
git 安装与同名跳过、以及停用技能与同步引擎的配合共 15 项)。
## HTTP 接口
| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | `/cloud-memory` | 配置页面 |
| GET | `/cloud-memory/status` | 设置 + 上报计数 + 最近 50 条记录(令牌只返回掩码) |
| PUT | `/cloud-memory/config` | 应用设置补丁(令牌留空表示不修改) |
| POST | `/cloud-memory/login` | 账号密码登录,换取两个令牌并保存(密码不落盘) |
| POST | `/cloud-memory/test` | 分别校验两个令牌(活动令牌用空载荷探测,鉴权先于载荷校验,返回 400 即代表令牌有效,不会写入记录) |
| POST | `/cloud-memory/flush` | 立即补发待重试队列 |
写接口会校验同源 `Origin`,跨站请求返回 403。
## 状态语义
`TurnEndReason.kind` → 上报状态:
| kind | status | 说明 |
| --- | --- | --- |
| `completed` | `completed` | 正常结束;只有它计入热力图 |
| `aborted` / `interrupted` / `blocked` | `cancelled` | 用户中断或被阻止 |
| `error` / `max-tokens` | `failed` | 出错或超长截断 |
| `forked` | 不上报 | fork 不算用户跑完的一轮,计入会让热力图虚高 |
## 故障排查
- **热力图不涨**:看 `/cloud-memory/status` 的 `reporter.skipped` 与 `lastError`;常见原因是没配 `activityToken`、插件被 `enabled:false` 关掉,或令牌缺 `activity:write` scope。
- **工具报“未配置记忆令牌”**:填 `memoryToken`;写入还需要云端已配置 WebDAV 主存储(否则服务端 409 `storage_not_configured`)。
- **网络不可用**:上报会进队列,恢复后 30 秒内自动补发;也可以在配置页点“重试上报队列”。
- **令牌泄漏风险**:令牌只存在本机 JSON 文件里,页面只回显掩码(`cmt_act…0001`)。文件权限依赖用户目录 ACL(Windows 无 POSIX 位)。
## 开发与发布
```powershell
pnpm install # 首次
pnpm run build # tsc -p tsconfig.build.json → lib/
pnpm run typecheck
node scripts/release-prep.mjs --dry-run # 先看会改什么
node scripts/release-prep.mjs # 原地整备:脱敏 + 元数据 + LICENSE(幂等)
node scripts/pack-guard.mjs # 白名单与脱敏闸门,不通过直接 exit 1
pnpm publish --access public --no-git-checks
```
`prepack` 会先重建 `lib/`,`prepublishOnly` 会先跑 `pack-guard`:包里一旦出现 `AGENTS.md`、`TODO.md`、`*.mjs` 探测脚本、`tsconfig*.json`、本机路径、个人域名或令牌原文,发布立刻中止。
> lifecycle 脚本要求 `node` 在 `PATH` 里。若报 `'node' is not recognized`,先把 DSH 运行时自带 node 的 `bin` 目录加进 `$env:Path` 再发布。