dsh-agent-vault 0.0.0-stage → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,114 @@
+# Changelog
+
+## 1.2.0 — 2026-10-21
+
+### 包名
+
+- npm 包名改为 **`dsh-agent-vault`**（`dsh-agent-memory` 已被他人占用，无法发布）。Loader 条目 id 仍是 `agent-memory`；仓库目录同步改为 `E:\Projects\dsh-agent-vault`。
+
+### 对话归属
+
+- 绑定智能体的会话从左侧工作区列表隐藏（客户端展示层过滤，不改数据，可关）；搜索仍可命中。
+- 侧栏工作区上方新增「智能体对话」区：按智能体分组列出绑定对话，点一条直接打开，可整体/按智能体折叠。
+- 智能体面板新增「对话」页签：列出该智能体的对话（工作区、时间、运行状态），可打开、解绑。
+- 「对话」页签的工作区下拉**选中即切换**；「新建对话」在所选工作区建会话并自动绑定。
+- 「续会话」继承源会话所在的工作区。
+
+### 自动归档
+
+- 交接后（续会话 / 检查点后同目录新建会话接管），旧会话自动转为**归档**：只读、可查看、不能继续。
+- 归档会话打开时显示「已归档（只读）」横幅，可直接取消归档。
+- **强归档**：DSH 原生归档，侧栏隐藏、面板灰色、不可打开；可转回归档。
+- 归档、取消归档、转强/转回，都在「对话」页签里操作；普通对话也可以手动归档。
+- 术语说明：此前的「弱归档」在界面上统一叫「归档」，不再出现「弱」字（内部级别名仍是 `weak`）。
+
+### 修复
+
+- `agent.newSession` 不再同时传 `workspaceId` 与 `cwd`（DSH 会拒绝）。
+- 归档调用改走 `workspaceRegistry.archiveSession(sessionId, options)`。
+- 旧主机（未重启）下按能力开关隐藏新入口，不露出必然报错的按钮。
+
+## 1.2.0-beta.5 — 2026-10-21
+
+### 修复
+
+- **弱归档改为插件层只读**：实测 DSH 原生归档的会话无法再被客户端打开（openSession 退回草稿页），不满足「可以查看」。现在弱归档不再调用 DSH 归档，会话保持可打开；由 `agent/pre-step` 返回 `{ kind: 'reject' }` 来阻止新的回合。
+- **强归档保留原生归档**：侧栏隐藏、面板灰色、不可打开；转回弱归档时会真正 unarchive。
+- 当前打开的弱归档会话会在底部显示「已归档（只读）」横幅，并带「取消归档」按钮。
+
+## 1.2.0-beta.4 — 2026-10-21
+
+### 修复
+
+- **自动归档没有生效**：归档调用把 `sessionId` 直接传给了 `workspaceController.archiveSession`，但那个 Remote 接收的是请求对象，结果归档成 `'undefined'` 并失败。改用 `workspaceRegistry.archiveSession(sessionId, { stopActivity: true })`（顺手加了空 id 防御）。
+- `archive.set` 同样改走 registry，取消归档时才真正 unarchive。
+
+### 变更
+
+- 面板「对话」页签：工作区下拉**选中即切换**（`uiWorkspace.openWorkspace`），不再需要单独的「切换过去」按钮。
+
+## 1.2.0-beta.3 — 2026-10-20
+
+### 新增
+
+- **自动归档（弱归档）**：续会话、或检查点之后在同一目录新建的会话接管工作时，旧会话自动变成**弱归档**——复用 DSH 原生 archive，历史可查看，但不能继续对话（DSH 的 pre-step 门禁会拦截新的回合）。
+- **归档级别**：弱归档显示在侧栏「智能体对话」和面板「对话」页签里；**强归档**在侧栏隐藏、在面板里灰色显示。
+- **手动切换**：对话页签里，弱归档可以「取消归档」或「转为强归档」；强归档可以「转为弱归档」；普通对话也可以手动归档为弱归档。
+- 新增 `archives.json` 记录级别（含 cwd/标题快照，归档后会话摘要不可用时仍能显示归属），以及 `archive.set` 主机操作。
+
+### 说明
+
+- 归档状态是 DSH 的工作区注册表在管；本插件只记录「弱/强」这一呈现级别。
+- 「取消归档」会真正从归档集移除，会话恢复可继续对话。
+
+## 1.2.0-beta.2 — 2026-10-20
+
+### 新增
+
+- **侧栏「智能体对话」区**：挂在工作区列表上方，按智能体分组列出已绑定对话（对话名 + 工作区 + 运行点），点一条直接打开；点标题打开智能体面板；可以整体折叠或按智能体折叠。数据来自新的 `bound.list` 主机操作。
+- 该区只在主机支持 `bound.list` 时出现（旧进程里不会留下空壳）。
+
+### 修复
+
+- `agent.newSession` 之前同时传 `workspaceId` 和 `cwd`，DSH 会拒绝（`session.create accepts workspaceId or cwd, not both`）；现在只传工作区。
+
+## 1.2.0-beta.1 — 2026-10-20
+
+### 新增
+
+- **绑定的对话不再挤在工作区列表里**：已绑定智能体的会话从左侧工作区列表隐藏，改在智能体面板的「对话」页签里按智能体查找。这是客户端展示层过滤（按会话 id 隐藏行），不改会话数据、不清选择、解除绑定即恢复；设置里可关闭。
+- **「对话」页签**：列出该智能体的对话（标题、工作区、最近时间、运行中），可打开、解绑。
+- **工作区选择**：在「对话」页签选择工作区，可「切换过去」（打开该工作区）或「新建对话」（在该工作区新建会话并自动绑定该智能体）。
+- **续会话继承工作区**：交接时新建的会话落在源会话所在的工作区，而不是最近使用的工作区。
+
+### 说明
+
+- 「隐藏」不写入任何归档状态；搜索结果仍能命中已隐藏的会话。
+- 主机新增 `workspace.list` / `agent.sessions` / `agent.newSession` 三个操作，和往常一样需要完整重启 DSH 才生效。
+
+## 1.1.0 — 2026-10-20
+
+首个 1.x 版本。相对 0.9.0：
+
+### 新增
+
+- **接力（交棒检查点）**：上下文压力到阈值时，在该步的系统提示里插入交接提醒；模型写完记忆和日志后，自动生成一条 `kind: "checkpoint"` 的私有日志，可选导出一份 markdown。
+- **面板「接力」页签**：开关、token 阈值、提醒间隔（步）、导出目录；实时列出各会话的压力与阶段（观察中 / 已到阈值 / 等待沉淀 / 已生成检查点）。
+- **重置**：等待沉淀或已生成检查点的会话可以单独重置阶段，检查点日志保留。
+- **续会话**：检查点落盘时记一个 30 分钟内有效的「下一会话」意图；在这个目录里新建的会话会自动绑定同一智能体、继承审批策略与模型。面板对已生成检查点的会话提供「续会话」按钮，一步新建并切过去。
+- 面板「日志」页签：查看、追加、删除该智能体的私有日志。
+- 讨论室：多房间、成员由用户点选、发言带发言人。
+
+### 测试
+
+`node test-*.mjs` 共 7 套，覆盖 store / host / 数据迁移 / 对话绑定 / 讨论室 / 日志 / 接力。
+
+### 已知限制
+
+- 自动切换会话（不经点击）与旧会话自动归档尚未实现，计划放在下一个版本。
+- 主机半边的改动需要完全退出重开 DSH 才生效；客户端半边的改动热更即可。
+- 「续会话」继承模型走 DSH 的 `sessionController.selectModel`，它会同时把该选择存成全局默认——这是 DSH 现有行为。
+
+## 0.9.0 及更早
+
+见 npm 上的历史版本。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The dsh-agent-memory authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,214 @@
-# Temporary Holding Version
+# dsh-agent-vault
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> npm 包名是 **dsh-agent-vault**（原 `dsh-agent-memory` 在 npm 上已被他人占用）。
+
+给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）用的智能体记忆与知识库插件。
+
+每个智能体有一段**可继承的短记忆**；所有智能体共用**一个详细的共享知识库**；每个对话可以单独绑定一个智能体，因此同一时间可以有多个对话分别处于不同角色。
+
+---
+
+## 它解决什么
+
+DSH 的会话本身是无状态的。跨任务时，你需要自己把上下文重新灌进去；而做完一件事之后，踩过的坑、验证过的命令、为什么这么选，通常散落在对话里，下次用不上。
+
+这个插件补两块：
+
+- **记忆**：智能体在任务完成或交接时，把结果压缩成一段很短的话（默认上限 4000 字）。这段记忆不自动生效——**由用户决定**把它读进哪个对话。
+- **知识库**：详细经验（路径、命令、坑、决策理由）。**由智能体自己决定**什么时候查、查什么、何时补充。
+
+两者权限刻意分开：模型没有任何"读记忆"的工具，只能写；知识库的读则只对模型开放，用户侧只能浏览和编辑。
+
+## 功能
+
+| 能力 | 说明 |
+|---|---|
+| 智能体管理 | 新建 / 改名 / 删除，互不影响 |
+| 短记忆 | 每个智能体一份，上限可配，面板里直接编辑，改动留审计日志 |
+| 共享知识库 | 所有智能体读写同一库，每条记录贡献者，支持搜索 / 标签 |
+| 按对话绑定 | 新建对话时在下拉里选智能体；各对话互不干扰 |
+| 记忆注入 | 只注入该对话绑定（或默认）智能体的记忆 |
+| 记忆不自动读 | 面板里没有任何"注入"入口，只有绑定；模型侧也没有读记忆的工具 |
+| 知识库自主查 | `agent_knowledge_search` / `read` / `write` 由模型自行决定调用 |
+| 讨论室 | 可建多个房间；用户指定哪些智能体加入，成员可中途加入或退出；每条发言标注是哪个智能体说的 |
+| 私有日志 | 每个智能体一份详细的日记式记录，**只有它自己能读写**，按需检索，不自动注入 |
+| 接力（检查点） | 上下文到阈值时提醒模型先写记忆和日志，两件都完成后自动把检查点写进该智能体的日志；可选额外导出 markdown；settle 后新会话自动继承绑定、审批策略与模型，面板「续会话」一键续到新会话 |
+| 自动归档 | 续会话/新会话接管后，旧会话自动转为**归档**（只读、可查看、不能继续）；面板「对话」页签可取消归档、转**强归档**（侧栏隐藏、面板灰色）或转回归档 |
+
+## 安装
+
+DSH 插件以 profile 包的形式安装。任选一种：
+
+### 方式一：从目录安装
+
+```bash
+dsh plugin --profile <你的 profile> add dsh-agent-vault
+```
+
+也可以直接从目录装：
+
+```bash
+dsh plugin --profile <你的 profile> add /path/to/dsh-agent-memory
+```
+
+### 方式二：手工加到 patch 层
+
+把仓库放到任意位置，然后确保 profile 的 `node_modules` 能解析到它（`pnpm add link:<路径>`），再在 profile 的 `cordis.patch.yml` 末追加：
+
+```yaml
+- insert:
+    - id: agent-memory
+      name: "dsh-agent-vault"
+```
+
+**装完必须完全退出并重开 DSH**，不要依赖热加载。
+
+## 配置
+
+配置写在插件条目上，全部可选：
+
+```yaml
+- insert:
+    - id: agent-memory
+      name: "dsh-agent-vault"
+      config:
+        memoryDir: "D:\\dsh\\agent-memory"   # 记忆与注册表根目录，默认 ~/.dsh/agent-memory
+        knowledgeDir: "E:\\Agent-knowledge"  # 知识库目录，默认 <memoryDir>/knowledge
+        memoryLimit: 4000                    # 记忆上限字数，500-20000
+        entryLimit: 48000                    # 单条知识上限字数，2000-200000
+```
+
+知识库目录也可以直接在面板「设置」里改，立即生效（不迁移已有内容）。
+
+## 数据布局
+
+```
+<memoryDir>/agents.json                 智能体注册表
+<memoryDir>/settings.json               知识库目录、默认智能体
+<memoryDir>/bindings.json               对话 → 智能体 绑定
+<memoryDir>/memory/<agentId>.md         该智能体的记忆
+<memoryDir>/memory/<agentId>.log.md     记忆写入审计（追加式）
+
+<knowledgeDir>/<entryId>.md             共享知识库条目（front matter 带 agent 贡献者）
+
+<memoryDir>/rooms/<roomId>/room.json     讨论室元数据（名称、成员）
+<memoryDir>/rooms/<roomId>/messages.jsonl 讨论室发言（每行一条，带发言人）
+<memoryDir>/journal/<agentId>.jsonl      私有日志（每行一条，只有该智能体可读）
+<memoryDir>/handoff.json                 接力配置（阈值、导出目录）
+<memoryDir>/handoff-state.json           每会话的接力阶段
+```
+
+全部是普通 Markdown / JSON，可以直接用编辑器改，也可以纳入 git。
+
+## 模型侧工具
+
+| 工具 | 作用 |
+|---|---|
+| `agent_memory_save` | 写该智能体的短记忆（覆盖式） |
+| `agent_knowledge_search` | 检索共享知识库；空查询列出最近条目 |
+| `agent_knowledge_read` | 读一条完整内容 |
+| `agent_knowledge_write` | 新增或按 `entry` 修订已有条目 |
+| `agent_room` | `action`: `list` / `read` / `say` / `join` / `leave`，参与讨论室 |
+| `agent_journal` | `action`: `list` / `search` / `read` / `write`，读写**自己的**私有日志 |
+
+工具通过调用会话的绑定解析智能体；显式传 `id` 时优先。`agent_journal` 永远只作用于调用方的智能体，**不接受其他智能体 id**，这就是隔离的实现方式。
+
+## 接力（交棒检查点）
+
+长时间任务会让单个会话堆到窗口边缘，越后面越贵、越容易复发早期已经修好的问题。接力做的事很简单：**在还来得及的时候，把这次工作沉淀成记忆和日志**。
+
+| 阶段 | 发生什么 |
+|---|---|
+| watching | 每步进入前用 `ctx.tokenMeter.measure(session).totalTokens` 量压力，低于阈值什么都不做 |
+| requested | 超过阈值：在该步的系统提示里插入一条交接提醒，要求模型先用 `agent_memory_save` 写记忆、再用 `agent_journal` 写一条详细日志 |
+| ready | 检测到记忆的 `memoryUpdatedAt` 与最近一条普通日志都**晚于这次提醒** → 生成检查点 |
+| settled | 检查点写进该智能体的日志（`kind: "checkpoint"`），本会话继续用，不再重复提醒 |
+
+要点：
+
+- **检查点就是一条日志**，不是工作区里的文件。它天然属于该智能体、天然隔离、天然能用 `agent_journal` 找回来。
+- 记忆或日志掉回阈值 90% 以下（例如手动压缩过），这次请求会被清掉，允许下次重新触发。
+- **提醒不换会话、不打断**：它只是在那一步的系统提示里多一段话，模型照常继续手上的工作。
+
+### 阈值
+
+只有一个 `triggerTokens`，默认 **300000**，是**绝对值、不按窗口自适应**。
+
+| 窗口 | 建议阈值 |
+|---|---|
+| 256K（官方默认） | 180000 |
+| 512K 及以上 | 300000–350000 |
+
+窗口越小越要往下调，否则永远不触发，看起来像插件没工作。
+
+### 配置
+
+面板「接力」页签可改，也可以直接写 `<memoryDir>/handoff.json`：
+
+```json
+{
+  "enabled": true,
+  "triggerTokens": 300000,
+  "remindEverySteps": 2,
+  "exportDir": ""
+}
+```
+
+`remindEverySteps` 控制提醒频率：超阈值后**每隔这么多步**才重复一次（默认 2）。第一次触发总会提醒，之后按这个间隔降噪；记忆和日志一落盘就彻底停止。`exportDir` 留空时就只写日志；填了会额外落一份 markdown（`checkpoint-<会话短 id>-<时间>.md`），方便用编辑器看或给别的工具读。
+
+### 重置
+
+「接力」页签的会话列表里，处于等待沉淀或已生成检查点的会话那一行会有「重置」。它只清掉该会话的阶段记录，让它重新从 `watching` 开始；已经写进日志的检查点**不会删除**。适合手动压缩过上下文、或者想在同一会话里再走一轮的时候。
+
+v1 只做「沉淀」，**不会自动切换会话**。检查点落盘后会记一个 30 分钟内有效的「下一会话」意图：在这个目录里新建的会话会自动绑定同一智能体，并继承审批策略与模型（`resume`、子智能体和已绑定的会话不会误消费）。面板的「续会话」按钮把意图刷新 + 新建会话合成一步，并让新会话落在源会话所在的工作区。自动切换（不经用户点击）和旧会话自动归档仍未实现，API 事实与剩余工作见 [docs/handoff-v2.md](docs/handoff-v2.md)。
+
+## 面板
+
+侧栏出现「智能体」图标，打开后：
+
+- 左侧：顶部可在「智能体 / 讨论室」之间切换
+- 智能体视图：列表显示记忆字数、贡献条数、被几个对话使用；右侧六个页签：记忆 / 对话 / 共享知识库 / 日志 / 接力 / 设置
+- 对话页签：按智能体收拢它的对话（标题、工作区、时间、运行状态），可「打开」「解绑」；顶部可选工作区并「切换过去」或「新建对话」（新建的会话自动绑定该智能体）
+- 讨论室视图：新建房间、点成员名字加入或移出、消息流、直接发言（Enter 发送）
+- 记忆页底部列出正在使用它的对话（显示**对话标题 + 短 id**），可一键解除绑定
+
+已绑定智能体的对话会从左侧工作区列表里隐藏（客户端展示层过滤，不改会话数据，搜索仍可命中）。设置页可以关掉这个隐藏行为。工作区上方还有一块「智能体对话」区，按智能体分组列出这些对话，点一下就能打开。细节与限制见 [docs/sessions-and-workspaces.md](docs/sessions-and-workspaces.md)。
+
+新建对话时，新会话那一行右侧会出现「智能体」下拉。
+
+讨论室的发言由**用户驱动**：在某个已绑定智能体的对话里让它「去讨论室说点什么」，它会用 `agent_room` 读上下文并发言；也可以由你直接在面板里发言。插件不做自动轮流发言。
+
+## 已知限制
+
+- **改动插件后必须完全重启 DSH。** 运行中热加载这类 Host 插件会让工具执行上下文失效（所有工具报 `cannot get requested service "sessionProjections" in inactive context`）。这是实测结论，与插件逻辑无关。
+- 知识库是全库共享：不做按智能体的隔离，只有贡献者标记（私有日志才是隔离的）。
+- 讨论室不自动调度发言，也不限制谁先说；顺序完全由使用方式决定。
+- 对话标题来源有两处：live 会话走 `sessionTitle` 服务，已关闭会话读投影缓存；两者都取不到时显示「未命名对话」。
+- 面板的视觉细节依赖宿主主题变量 `--dsw-alias-*`，换主题不会破版，但不会跟随自定义设计系统。
+
+## 开发
+
+纯 JavaScript，无构建步骤。两个半片：
+
+- `index.js` — Host：工具、提示词段落、`/api/agent-memory` 路由
+- `client.js` — 浏览器：面板与新建对话选择器（手写 ModuleLoader bundle）
+- `store.js` — 存储层，不依赖 Cordis，可单独测试
+- `rooms.js` — 讨论室存储
+- `journal.js` — 私有日志存储
+- `handoff.js` — 接力：配置、每会话阶段、检查点文本与导出
+
+测试（无需安装依赖）：
+
+```bash
+node test-store.mjs      # 记忆与知识库文件层
+node test-host.mjs       # 用 mock ctx 跑注册、工具与 HTTP 分发
+node test-migrate.mjs    # 旧「按智能体分目录」布局合并到共享库
+node test-binding.mjs    # 对话绑定与解析优先级
+node test-rooms.mjs      # 讨论室：成员、中途加入、发言顺序
+node test-journal.mjs    # 私有日志与跨智能体隔离
+node test-handoff.mjs    # 接力：阈值、requested→ready、检查点文本与导出
+```
+
+## 许可
+
+MIT，见 [LICENSE](LICENSE)。