@restregular/dsh-memory 0.26.0 → 0.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,15 @@
2
2
 
3
3
  本项目的版本记录。安装 id 与 npm 版本一一对应。
4
4
 
5
+ ## 0.27.0 — 范围外命中「先索引后审批」:检索不再自动弹审批;作用域目录默认描述
6
+
7
+ - **问题**:普通限制下 `memory_search` 撞到范围外命中会**立刻弹审批**,Agent 完全没有判断依据——它还不知道范围外有什么、值不值得读,用户就要先回答一次「允许 / 拒绝」。一次跨作用域的检索动辄打断用户;而审批卡上列的正文快照又太重,多数时候用户看完只是拒绝。反过来,`scopeCatalog` 里的作用域描述全靠创建者手写,没写过的目录条目一律「(未填写用途)」,Agent 想靠目录判断「这个域是干什么的」时没有信息。
8
+ - **检索默认只给索引**:范围外命中不再触发审批,改为在结果里新增 `outOfScope` 字段——命中了哪些作用域、各几条(`scopes` 聚合),加上每条的**记忆索引**(`records`:id / score / 作用域 / 类型 / 标签 / 更新时间 / 短摘要,**不含正文**)。渲染上索引独立成块,尾部注明这是「目录印象」并给出取正文的路径。`withheld` 的口径同步细分:未发起审批的范围外命中报 `out-of-scope`(新原因,提示「索引已列出,确认后再显式申请」),审批后的结局(partial / rejected / timeout)与 absolute / read-disabled / scope-disabled 沿用原口径。
9
+ - **审批改为显式发起**:`memory_search` 新增 `requestApproval` 参数(默认 false)。Agent 看完索引确认确有需要的内容后,带 `requestApproval=true` 重发同一次查询——这时才向用户发起审批,允许的条目照旧并入 `records`(0.26 行为),没被允许的继续留在索引里。`memory_get` 拿范围外 id 读正文**本来就是显式访问**,审批路径不变;`memory_scopes request` 申请作用域会话权限的路径也不变。绝对限制下**不返回任何索引**(没有审批放行路径,索引只会引诱越权尝试);普通限制下的 description 必填校验照旧——校验的是「这次调用的用途」,与要不要弹审批无关。
10
+ - **作用域目录默认描述**:`memory_scopes list` 里没写过用途的作用域不再显示「(未填写用途)」,按类型给一句默认说明——global「跨项目共享的通用事实与偏好」、project「绑定当前工作区路径的共享记忆」、session「仅本会话可见的过程记忆」、custom「按名字聚合的跨会话记忆(建议创建时写明用途)」。Agent 手写过的 `scopeDescription` 永远优先,默认描述不落盘、不写进 scope-meta。
11
+ - **讲清楚**:注入的「记忆系统」常驻段新增两步口径(先看索引 → 确认后再 requestApproval=true / memory_scopes request,并提醒「不要凭索引摘要直接引用范围外内容」);可见域等级说明里 normal 的描述同步改写;`memory_search` 的工具说明与参数说明同步。
12
+ - 测试:改写 4 处断言旧行为的用例(tools / access / scope-service / session-visibility),新增「默认只给索引不弹审批」「requestApproval=true 恢复审批」「absolute 无索引」「拒绝后索引保留」「默认描述 + 手写优先」等用例;`source/memory-local/test/multiprocess.test.ts` 按惯例未在受限沙箱跑(需真起子进程)。
13
+
5
14
  ## 0.26.0 — 作用域参数接受 `custom:` 展示前缀:自动归一,不再写「幽灵授权」
6
15
 
7
16
  - **问题(真机复现)**:0.25.10 / 0.25.11 把所有工具输出、注入摘要与面板统一改成展示名 `<类型>:<名字>` 后,自定义作用域在 Agent 眼里只以 `custom:dsh-plugin-dev` 出现;但参数层只放行 `project:` / `session:` 两种前缀,`custom:` 属于键空间之外。于是 `memory_scopes request({ scopes: ['custom:dsh-plugin-dev'] })` 被 `canonicalScope` 原样收下、`grants.add` 只校验权限不校验键形态 —— 一条永远匹配不到记录的 grant 就这样落盘:申请结果渲染成 `custom:custom:dsh-plugin-dev → 已授予`(`scopeDisplayName` 对未知键无条件补 `custom:`),目录里又查不到(`scopeCatalog` 不含 grants),下一次 `memory_search` 重新弹审批。本机 `grants/session-91f4b9f7….json` 里同时躺着 `custom:dsh-plugin-dev` 与 `dsh-plugin-dev` 两条,相隔 35 秒。根因还包括:`memory_scopes request` 是唯一跳过 `normalizeScopeInput` 的作用域入口(其余工具都过 `resolveScope`)。
package/README.md CHANGED
@@ -39,7 +39,7 @@ JSONL 落盘 · 本机向量检索 · 五个模型工具 · 自动召回 · 硬
39
39
 
40
40
  | 能力 | 说明 |
41
41
  | --- | --- |
42
- | **六个工具** | `memory_save` / `memory_search` / `memory_list` / `memory_get` / `memory_forget` / `memory_scopes`。`memory_search` 只回印象(8 位 id / 作用域 / 类型 / 标签 / 短摘要),正文和元数据用 `memory_get` 的 `fields` 按需取;同一会话里已出现过的条目只回 id。`description` 字段在普通限制下必填,审批卡会展示它。`memory_scopes` 只读目录:给作用域名字 / 用途 / 当前可读可写状态,不返回任何正文。**作用域参数传裸名**(`handbook`):0.26.0 起工具输出里的展示名 `custom:handbook` 粘进参数会被自动归一,`project:` / `session:` 本来就直接可用 |
42
+ | **六个工具** | `memory_save` / `memory_search` / `memory_list` / `memory_get` / `memory_forget` / `memory_scopes`。`memory_search` 只回印象(8 位 id / 作用域 / 类型 / 标签 / 短摘要),正文和元数据用 `memory_get` 的 `fields` 按需取;同一会话里已出现过的条目只回 id。范围外命中默认只给索引(`outOfScope` 字段,0.27.0 起),确认后带 `requestApproval: true` 重发才弹审批。`description` 字段在普通限制下必填,审批卡会展示它。`memory_scopes` 只读目录:给作用域名字 / 用途 / 当前可读可写状态,不返回任何正文。**作用域参数传裸名**(`handbook`):0.26.0 起工具输出里的展示名 `custom:handbook` 粘进参数会被自动归一,`project:` / `session:` 本来就直接可用 |
43
43
  | **四种作用域** | 会话 / 项目 / `global` / 自定义名。默认写进当前会话,读默认合并会话 + 项目 + global;项目作用域可起别名。自定义作用域**首次由 Agent 创建时必须带 `scopeDescription`**(一句话用途),可选带 `scopeRule` 写一条初始规则;元数据存在 `<storeDir>/scope-meta/`,删光记录也不会丢 |
44
44
  | **作用域目录与绝对隔离** | `memory_scopes` 列出范围内 / 范围外的名字与用途;normal / none 下还带**初始化记录正文**(每个作用域最多 3 条,方便 Agent 直接读到“这个作用域主要放什么”)。绝对限制下范围外作用域**仍可发现**,但正文(含初始记录)永不可读、不可写、不可申请(没有任何审批放行路径);普通限制下范围外条目可申请,`memory_scopes request` 走审批后写入**本会话**授权(默认只读,写权限必须单独申请),子 Agent 沿父会话继承 |
45
45
  | **会话授权(grants)** | Agent 申请、用户批准的例外单独存在 `<storeDir>/grants/<session>.json`,不并入可见域策略;只读 / 可写独立、可撤销、只在本会话(及子 Agent)生效;`absolute` 下授权不生效,作用域被删除重建后按创建代次自动失效 |
@@ -49,7 +49,7 @@ JSONL 落盘 · 本机向量检索 · 五个模型工具 · 自动召回 · 硬
49
49
  | **硬性规则** | `kind: rule` 进系统提示常驻段;行首带 8 位 id,注入的是摘要,需要全文时用 `memory_get`;旧会话会收到新增 / 编辑提醒;超预算有明确警告,不静默丢弃 |
50
50
  | **记忆权限** | 输入框旁的「记忆权限」按钮设置本会话可读的作用域 + 限制等级(绝对 / 普通 / 无限制);每个作用域一行就是一条设置:**勾选**表示本会话可访问,行内**【绑定】/【可读】/【可写】**控制工作区默认可见与读写权限——**【绑定】点一下立即保存**(0.25.13 起),绑定到当前工作区后新会话默认可见,可读 / 可写独立影响工具读写;Agent 通过 `memory_scopes request` 申请到的范围外授权**也用勾选呈现**(名称右边挂一个「AI」气泡,样式与你自己勾选的行区分开),取消勾选只是草稿,**点「保存」才真正撤销**(0.25.4 起),且按钮数字 / 「已选」都把 AI 授权算进去(0.25.5 起)并**实时轮询**——浮窗关着,Agent 刚拿到的授权也会让按钮数字自己变(0.25.6 起);**整张作用域卡片都能点选**,点名称 / 计数 / 留白等同点勾选框(0.25.7 起),本会话那一行直接叫「**session:当前会话**」(0.25.8 起,0.25.10 起带类型前缀);**所有作用域名都以 `global:` / `project:` / `session:` / `custom:` 开头**(0.25.10 起);浮窗挂在页面根层,不会被输入框上方的浮动按钮盖住(0.25.8 起);Agent 及其子 Agent 都按它检索、注入与 `memory_get` |
51
51
  | **修正版编辑** | 面板里编辑一条记忆 = 新建一条修正版并通过 `supersedes` 指向旧记录,旧记录不原地修改;记录页「是否被修正」筛选默认隐藏旧版本,可切到全部 / 只看已修正 |
52
- | **范围外审批** | 普通限制下,工具命中可见域外的记忆时会在**对应会话的输入框上方**出现审批卡(样式与系统权限审批一致):展示工具、Agent 说明、查询关键词与范围外记忆摘要,支持逐条勾选 / 全选 / 取消全选(「允许选中的 N 条」或整单「允许一次」)或「拒绝」;点记忆 ID 直接跳到面板「记录」页并展开该条。**0.25.14 起**审批等待期间还会像系统审批 / ask 工具一样,在该会话的侧边栏行显示黄色圆点与「待审批」(含后台会话;回答或超时后撤销),其它插件也能从宿主 `uiSession.sessionStatus` 读到这条阻塞 |
52
+ | **范围外审批** | 普通限制下,`memory_search` 撞到可见域外的记忆**默认只返回索引**(作用域聚合 + 条目印象,不含正文,0.27.0 起),不自动弹审批;Agent 确认索引里确有需要的内容后,带 `requestApproval=true` 重发查询才会发起审批。需要正文时的另一条路是 `memory_get`(拿 id 显式读取,审批路径不变)或 `memory_scopes request`(申请整个作用域的本会话权限)。发起后,审批卡在**对应会话的输入框上方**出现(样式与系统权限审批一致):展示工具、Agent 说明、查询关键词与范围外记忆摘要,支持逐条勾选 / 全选 / 取消全选(「允许选中的 N 条」或整单「允许一次」)或「拒绝」;点记忆 ID 直接跳到面板「记录」页并展开该条。**0.25.14 起**审批等待期间还会像系统审批 / ask 工具一样,在该会话的侧边栏行显示黄色圆点与「待审批」(含后台会话;回答或超时后撤销),其它插件也能从宿主 `uiSession.sessionStatus` 读到这条阻塞 |
53
53
  | **上下文去重** | `memory_search` / `memory_list` 返回过的条目记进会话上下文状态;同一版本再次命中只回记忆 ID(`memory_search` 的裸 ID 与带摘要条目之间空一行),并提示用 `memory_get` 取全文(内容更新后重新给摘要) |
54
54
  | **状态记忆** | `kind: state` 默认 7 天 TTL;注入带「状态,使用前验证」;过期后默认不进检索 / 摘要 / 召回,但 `memory_get` 与面板仍可取 |
55
55
  | **流程索引** | `kind: procedure` 的目录进系统提示:按当前工作区 + 触发词(工具名 / 关键词)列 `id · 触发词 → 标题`,需要时再用 `memory_get` 取全文 |
@@ -101,7 +101,7 @@ JSONL 落盘 · 本机向量检索 · 五个模型工具 · 自动召回 · 硬
101
101
  - **状态按钮(0.23.0 / 0.23.1,绑定即存 0.25.13)**:作用域列表每行有【绑定】、【可读】|【可写】。**默认范围自带的会话 + 项目 + global 显示为已绑定且不可取消**;**绑定**按钮用于把其它作用域额外并入当前工作区的默认范围(没有显式覆盖的新会话可见)——**点一下立即保存**(`POST /memory/api/bindings`),不用再点「保存」,写入失败会回滚按钮状态并在浮窗里报错;**可读 / 可写**是会话级,独立控制该作用域的读取与写入(关掉可读 → 搜索 / 读取跳过并说明原因;关掉可写 → 保存 / 删除被拒绝并说明原因),这两项仍是草稿,点「保存」才生效。绑定是工作区级设置(只影响本工作区**新会话**的默认范围),当前会话读什么并没有变,所以**绑定变化不注入上下文提示**。
102
102
  - **限制等级**:
103
103
  - **绝对限制**:可见域外的读取 / 写入 / 删除一律不执行;命中被挡住时会明确告诉 Agent 是「绝对限制」以及怎么调整(不再假装记忆不存在)。
104
- - **普通限制**(默认):可见域内正常返回;命中范围外记忆时,工具会暂停并在**该会话**的输入框上方显示审批卡,展示 Agent 的查询关键词与范围外记忆摘要;读审批可以逐条勾选,只允许其中一条或多条。用户拒绝 / 5 分钟未回答时,工具结果里会明确写出真实原因(「用户拒绝了本次访问」/「审批超时」),模型不会误以为记忆不存在。范围外写入 / 删除同样走审批。
104
+ - **普通限制**(默认):可见域内正常返回;命中范围外记忆时**默认不弹审批**——结果里给一份范围外索引(命中了哪些作用域、各几条,加每条的 id / 类型 / 标签 / 短摘要印象,不含正文),Agent 确认索引里确有需要的内容后,带 `requestApproval=true` 重发查询或用 `memory_scopes request` 申请作用域权限,**这时**才在该会话的输入框上方显示审批卡,展示 Agent 的查询关键词与范围外记忆摘要;读审批可以逐条勾选,只允许其中一条或多条。用户拒绝 / 5 分钟未回答时,工具结果里会明确写出真实原因(「用户拒绝了本次访问」/「审批超时」),模型不会误以为记忆不存在。范围外写入 / 删除照旧直接走审批。
105
105
  - **无限制**:不启用范围白名单,可以读写任意作用域(选择仍会保存,供下次切换)。
106
106
  - **Agent 授权 = 勾选 + 「AI」气泡(0.25.3 – 0.25.6)**:作用域行就是「勾选该作用域 + 【绑定】/【可读】/【可写】」这一组控件,不再有独立的「Agent 授权」行与浮窗上方的解释文本。Agent 通过 `memory_scopes request` 审批得到的授权直接体现为该作用域的**勾选**,名称右边挂「AI」气泡(`title` 写明只读 / 可写);**AI 授权的行用自己的样式**——虚线边框 + 中性底色,勾选框是虚线描边(透明底、蓝勾),不会和你自己勾选的实心蓝底行混淆。**取消勾选只是草稿**——气泡改标「AI·待撤销」,**点「保存」才真正撤销**(保存时先 `POST /grants` 撤销,再保存可见范围),Agent 下一次 pre-step 收到「记忆权限已更新」。**计数**:输入框按钮上的数字与弹窗头部「已选」都是「可见范围 ∪ AI 授权」的作用域数,AI 授权算进去。继承自父会话的授权标「AI·继承」,本会话取消勾选会被拒绝并提示到父会话操作;「取消全选」只是把可撤销的授权标记为待撤销。目录里已不可见的作用域仍占一行(标「目录中已不可见」)。列表里**已勾选(按保存过的状态)的排在上面、未勾选的排在下面**,组内按名称字母排序;**保存后才按新状态重排**。**数字实时**:本会话授权按 3 秒轮询,浮窗没打开时 Agent 刚拿到的授权也会让输入框按钮数字自己变(0.25.6 起)。**草稿不跨关闭**:点浮窗外面 / Esc / 再点按钮关掉浮窗时,未保存的勾选与「AI·待撤销」标记一律丢弃,重开只显示服务端真值(没保存就还原,不记住草稿)。
107
107
  - **不再按记忆类型收窄**:0.19.1 起只按作用域限制;旧配置里的 `kinds` 会被忽略,同一作用域下的事实 / 规则 / 流程等都可读。
@@ -269,7 +269,9 @@ memory_save({
269
269
  })
270
270
  ```
271
271
 
272
- 用途会出现在 `memory_scopes` 的目录里:
272
+ 用途会出现在 `memory_scopes` 的目录里;没写过用途的作用域会按类型给一句**默认描述**
273
+ (0.27.0 起:global = 跨项目共享、project = 绑定当前工作区、session = 仅本会话可见、
274
+ custom = 按名字聚合,建议创建时写明用途),手写过的 `scopeDescription` 永远优先:
273
275
 
274
276
  ```js
275
277
  memory_scopes({ action: "list", description: "看看有哪些作用域、各自干什么" })
@@ -278,6 +280,12 @@ memory_scopes({ action: "list", description: "看看有哪些作用域、各自
278
280
  绝对限制下**目录可见但正文不可读**:范围外作用域仍显示名字与用途(方便判断要不要让用户
279
281
  调整范围),但记录数、正文、申请入口都不会返回。
280
282
 
283
+ **范围外命中先看索引(0.27.0)**:普通限制下 `memory_search` 撞到范围外记忆**默认不弹审批**,
284
+ 结果里的 `outOfScope` 字段给出索引——命中了哪些作用域、各几条,加每条的
285
+ id / score / 类型 / 标签 / 短摘要(不含正文)。确认索引里确有需要的内容后,再显式发起:
286
+ 带 `requestApproval: true` 重发同一次查询(立即弹审批),或用 `memory_get` 拿 id 读正文 /
287
+ `memory_scopes request` 申请作用域权限。不要凭索引里的摘要就直接引用范围外内容。
288
+
281
289
  **申请本会话权限(0.24.0 / D3)**:普通限制下,Agent 可以对**范围外**作用域发申请;
282
290
  默认只申请只读,写权限必须显式列出:
283
291
 
@@ -603,6 +611,7 @@ npm run verify # 构建到 .verify/,不落 packages/
603
611
 
604
612
  ## 更新日志
605
613
 
614
+ - **0.27.0** —— 范围外命中「先索引后审批」:普通限制下 `memory_search` 不再自动弹审批,结果新增 `outOfScope` 索引(作用域聚合 + 条目印象,不含正文),`requestApproval: true` 显式发起审批;`withheld` 新增 `out-of-scope` 原因;`memory_scopes` 目录给没写用途的作用域按类型补默认描述。
606
615
  - **0.22.3** —— 审批卡高度与宿主审批卡同口径(去掉额外的 `46vh` 上限),矮窗口下详情行固定后条目列表仍有滚动空间。
607
616
  - **0.22.2** —— 修复审批卡条目不显示 Agent 查询 / 说明:两行原来带 `overflow:auto`,在 flex 列里会被长列表压成 0 高;现在锁 `flex:none`,只让列表滚动。
608
617
  - **0.22.1** —— 审批卡可折叠(strip 上「折叠 / 展开」,折叠后动作行仍可用),读审批条目整行点击即可选中。
@@ -131,7 +131,7 @@ const NUDGE_TEXT =
131
131
 
132
132
  const VISIBILITY_LEVEL_TEXT = {
133
133
  absolute: '绝对限制:可见域外的记忆一律查不到,即使工具内部命中也不会返回;范围外也写不进去。',
134
- normal: '普通限制:可见域外的记忆命中时会向用户发起一次审批;用户拒绝或超时则不返回。写入 / 删除范围外同样需要审批。',
134
+ normal: '普通限制:可见域外的记忆命中时默认只返回索引(outOfScope 字段),不自动弹审批;Agent 确认需要正文后带 requestApproval=true 才向用户发起一次审批。写入 / 删除范围外同样需要审批。',
135
135
  none: '无限制:可以读写所有作用域(当前选择仅作为下次切换的偏好保留)。',
136
136
  }
137
137
 
@@ -8,6 +8,8 @@ export const POLICY_TEXT = `## 记忆系统
8
8
 
9
9
  memory_search 只返回印象(ID、作用域、类型、标签和少量摘要);判断相关后再用 memory_get(ids, fields) 取正文。fields 省略 = content + scope + kind + tags;只要摘要用 ["summary"],只要正文用 ["content"],需要重要度 / 时间 / 触发词等再显式加上对应字段。
10
10
 
11
+ 搜索命中作用域外记忆时默认**不弹审批**:结果里的 outOfScope 字段给出范围外索引(命中了哪些作用域、各几条、条目印象,不含正文)。只有确认索引里确有需要的内容时,再用 memory_search 带 requestApproval=true 重新发起同一次搜索(这时才弹审批),或用 memory_scopes(action="request") 申请该作用域的本会话权限;不要凭索引里的摘要就直接引用范围外内容。
12
+
11
13
  需要知道有哪些作用域、各自用来做什么、当前能不能读/写时,用 memory_scopes(action="list")。它只返回目录元信息(名字 / 用途 / 访问状态)与初始化记录正文,不返回普通记忆正文;范围外作用域在绝对限制下仍可发现,但正文(含初始化记录)永不可读、不可申请。
12
14
 
13
15
  需要长期使用范围外作用域时,用 memory_scopes 的 action="request" 申请本会话权限:默认只读,写权限必须在 permissions 里显式列出;审批卡默认只勾只读。批准后本会话(及子 Agent)可直接读写该作用域,不必每次审批;一次性访问仍直接调用 memory_search / memory_get。
@@ -17,6 +17,7 @@
17
17
  import { MemoryStore, newId, scopeFileName, } from './store.js'
18
18
  import {
19
19
  canonicalWorkspacePath,
20
+ defaultScopeDescription,
20
21
  isCustomScope,
21
22
  normalizeScopeInput,
22
23
  normalizeScopeKey,
@@ -3329,10 +3330,13 @@ export class LocalMemoryService {
3329
3330
  : 'restricted'
3330
3331
  const name = meta?.name ?? this.names.nameOf(scope)
3331
3332
  const initialRecords = policy.level === 'absolute' ? undefined : this.initialRecordsOf(scope)
3333
+ // 0.27.0:scope-meta 没写用途时按作用域类型给默认描述,
3334
+ // 让目录里每一条都自带「这个域是干什么的」。
3335
+ const description = meta?.description ?? defaultScopeDescription(scope)
3332
3336
  out.push({
3333
3337
  scope,
3334
3338
  ...(name !== undefined ? { name } : {}),
3335
- ...(meta !== undefined ? { description: meta.description } : {}),
3339
+ ...(description !== '' ? { description } : {}),
3336
3340
  origin: meta?.origin ?? scopeKind(scope),
3337
3341
  ...(inScope ? { records: stat?.records ?? 0 } : {}),
3338
3342
  inScope,
@@ -292,6 +292,20 @@ export function scopeDisplayName(scope , humanName ) {
292
292
  return `${scopeTypePrefix(scope)}${name}`
293
293
  }
294
294
 
295
+ /**
296
+ * 0.27.0:内置作用域的**默认用途描述**。scope-meta 里没写过 description 时,
297
+ * 作用域目录(memory_scopes list)用它兜底,让每类作用域条目都带一句
298
+ * 「这个域是干什么的」,而不是统一的「(未填写用途)」。
299
+ * 自定义作用域的用途应该由创建者写(memory_save 的 scopeDescription),
300
+ * 这里只给最通用的说明。
301
+ */
302
+ export function defaultScopeDescription(scope ) {
303
+ if (scope === 'global') return '全局作用域:跨项目共享的通用事实与偏好;适合放与具体仓库无关的长期记忆。'
304
+ if (scope.startsWith('project:')) return '项目作用域:绑定当前工作区路径的共享记忆;同一路径下的所有会话可读写。'
305
+ if (scope.startsWith('session:')) return '会话作用域:仅本会话可见的过程记忆;换会话后经目录发现、不默认读取。'
306
+ return '自定义作用域:按名字聚合的跨会话记忆;创建时建议用 memory_save 的 scopeDescription 写明用途。'
307
+ }
308
+
295
309
  /** 写路径遇到只读 scope 时的错误码('all' 不能写)。 */
296
310
  export const SCOPE_NOT_WRITABLE = 'SCOPE_NOT_WRITABLE'
297
311
 
@@ -62,11 +62,12 @@ import { canonicalWorkspacePath, normalizeScopeInput, resolveScopeRef } from '..
62
62
 
63
63
  /**
64
64
  * 被可见域挡住、没有返回给模型的原因。
65
+ * - out-of-scope = 普通限制下「作用域不在范围内」,检索默认不自动弹审批(0.27);
65
66
  * - rejected / timeout / unavailable / partial = 普通限制审批的结局;
66
67
  * - absolute = 绝对限制下作用域根本不在范围内(0.23 起不再假装"不存在");
67
68
  * - read-disabled = 作用域在范围内但「可读」开关被关掉(0.23)。
68
69
  */
69
-
70
+
70
71
 
71
72
 
72
73
 
@@ -461,6 +462,27 @@ function withheldReasonFor(
461
462
  return 'read-disabled'
462
463
  }
463
464
 
465
+ /**
466
+ * 0.27.0:普通限制下**没有发起审批**的范围外命中给模型的原因。
467
+ * 与 withheldReasonFor 的差别:「整个作用域不在范围内」(普通限制下本可审批、
468
+ * 现在只给索引)不再报成 read-disabled,而是 'out-of-scope';
469
+ * absolute / read-disabled / scope-disabled 照旧如实聚合。
470
+ */
471
+ function outOfScopeReason(
472
+ decide ,
473
+ policy ,
474
+ denied ,
475
+ ) {
476
+ if (denied.length === 0) return undefined
477
+ const reasons = denied.map((item) => readDenyReason(decide, policy, item.scope, item.kind))
478
+ if (reasons.includes('absolute')) return 'absolute'
479
+ if (reasons.includes('scope-disabled')) return 'scope-disabled'
480
+ // readDenyReason 把「SCOPE_NOT_IN_RANGE + 普通限制」也归成 read-disabled;
481
+ // 这里按"作用域是否在范围里"细分:不在范围 = out-of-scope(可申请)。
482
+ const hasOutOfScope = denied.some((item) => !scopeInPolicy(policy, item.scope))
483
+ return hasOutOfScope ? 'out-of-scope' : 'read-disabled'
484
+ }
485
+
464
486
  /**
465
487
  * memory_save 的 supersedes 参数说明(模型可见)。
466
488
  * 检索 / 列表 / 摘要 / 规则索引里给的 id 都是 8 位短 id,而 supersedes 在 provider
@@ -973,6 +995,12 @@ function applySummaryDedupe(opts , exec , records
973
995
 
974
996
                              
975
997
 
998
+
999
+                         
1000
+                               
1001
+                      
1002
+
1003
+
976
1004
 
977
1005
 
978
1006
 
@@ -991,6 +1019,22 @@ function applySummaryDedupe(opts , exec , records
991
1019
 
992
1020
 
993
1021
 
1022
+ /**
1023
+ * 0.27.0:范围外命中的**记忆索引**(不含正文)。普通限制下检索不再自动弹审批,
1024
+ * 而是给模型一个「范围外有哪些作用域、命中了什么条目」的目录印象;
1025
+ * 要读正文时由 Agent 用 requestApproval=true 显式发起审批,或走 memory_scopes request。
1026
+ */
1027
+
1028
+
1029
+
1030
+
1031
+
1032
+
1033
+
1034
+             
1035
+
1036
+
1037
+
994
1038
 
995
1039
 
996
1040
 
@@ -998,12 +1042,17 @@ function applySummaryDedupe(opts , exec , records
998
1042
                                
999
1043
 
1000
1044
 
1045
+
1046
+                        
1047
+                                
1048
+
1049
+
1001
1050
 
1002
1051
 
1003
1052
  export function memorySearchTool(opts ) {
1004
1053
  return {
1005
1054
  name: 'memory_search',
1006
- description: 'Search saved memories by keyword or meaning (lexical + local vector recall). Returns id/scope/kind/tags and a short summary; use memory_get for full content.',
1055
+ description: 'Search saved memories by keyword or meaning (lexical + local vector recall). Returns id/scope/kind/tags and a short summary; use memory_get for full content. Out-of-scope hits return an index (outOfScope field) instead of auto-raising approval; pass requestApproval=true only after confirming the index holds what you need.',
1007
1056
  parameters: {
1008
1057
  query: { type: 'string', required: true },
1009
1058
  scope: { type: 'string', description: SCOPE_DESCRIPTION },
@@ -1011,6 +1060,7 @@ export function memorySearchTool(opts )
1011
1060
  includeSuperseded: { type: 'boolean', description: '默认 false;true 时把已被 supersede 的旧版本也返回(历史核对)' },
1012
1061
  summaryChars: { type: 'number', description: `每条摘要的字数上限(默认 ${DEFAULT_SUMMARY_CHARS},20~2000)` },
1013
1062
  description: { type: 'string', description: DESCRIPTION_PARAM_DESCRIPTION },
1063
+ requestApproval: { type: 'boolean', description: '默认 false:范围外命中只返回索引(outOfScope 字段),不自动弹审批;true = 立即向用户发起审批,允许的条目并入 records。确认索引里有值得读的内容后再传 true。' },
1014
1064
  },
1015
1065
  async execute(args , exec ) {
1016
1066
  const service = svc(opts)
@@ -1059,8 +1109,12 @@ export function memorySearchTool(opts )
1059
1109
  const outside = hits.filter((hit) => !recordAllowed(decide, policy, hit.record.scope, hit.record.kind))
1060
1110
  // 只有“作用域不在范围里”才可能审批;absolute 与 read:false 都不 requestable。
1061
1111
  const needsApproval = outside.filter((hit) => recordRequestable(decide, policy, hit.record.scope, hit.record.kind))
1112
+ // 0.27.0:普通限制下范围外命中**不再自动弹审批**。先把索引交给模型
1113
+ //(outOfScope 字段),要读正文时由 Agent 显式传 requestApproval=true。
1114
+ // 绝对限制 / 不可读 / 已关闭作用域照旧只进 withheld(它们没有审批路径)。
1115
+ const wantsApproval = args.requestApproval === true
1062
1116
  let verdict
1063
- if (needsApproval.length > 0 && level === 'normal') {
1117
+ if (needsApproval.length > 0 && level === 'normal' && wantsApproval) {
1064
1118
  verdict = await askOutOfScope(
1065
1119
  service,
1066
1120
  agent,
@@ -1100,9 +1154,36 @@ export function memorySearchTool(opts )
1100
1154
  if (denied > 0) {
1101
1155
  const approvedIds = new Set(approvedOutside.map((hit) => hit.record.id))
1102
1156
  const deniedRecords = outside.filter((hit) => !approvedIds.has(hit.record.id))
1103
- const reason = withheldReasonFor(decide, policy, deniedRecords.map((hit) => ({ scope: hit.record.scope, kind: hit.record.kind })), verdict)
1157
+ // 0.27.0:普通限制下没发起审批的范围外命中 = 'out-of-scope'(索引已在
1158
+ // outOfScope 字段给出);审批后的结局(partial/rejected/timeout)与
1159
+ // absolute / read-disabled / scope-disabled 沿用原口径。
1160
+ const reason = verdict !== undefined
1161
+ ? withheldReasonFor(decide, policy, deniedRecords.map((hit) => ({ scope: hit.record.scope, kind: hit.record.kind })), verdict)
1162
+ : outOfScopeReason(decide, policy, deniedRecords.map((hit) => ({ scope: hit.record.scope, kind: hit.record.kind })))
1104
1163
  if (reason !== undefined) result.withheld = { count: denied, reason }
1105
1164
  }
1165
+ // 0.27.0:范围外索引(不含正文)——命中了哪些作用域、各几条、条目印象。
1166
+ // 只在普通限制下给出:absolute 没有任何审批放行路径,索引只会引诱越权尝试。
1167
+ // 未发起审批(默认)或审批没全过时都会给出,模型据此决定要不要显式发起。
1168
+ const pendingOutside = outside.filter((hit) => !approvedOutsideIds.has(hit.record.id))
1169
+ if (pendingOutside.length > 0 && level === 'normal') {
1170
+ const scopeCounts = new Map ()
1171
+ for (const hit of pendingOutside) {
1172
+ scopeCounts.set(hit.record.scope, (scopeCounts.get(hit.record.scope) ?? 0) + 1)
1173
+ }
1174
+ result.outOfScope = {
1175
+ scopes: [...scopeCounts].map(([scope, count]) => ({ scope, records: count })),
1176
+ records: pendingOutside.map((h) => ({
1177
+ id: h.record.id,
1178
+ score: h.score,
1179
+ scope: h.record.scope,
1180
+ kind: h.record.kind,
1181
+ tags: Array.isArray(h.record.tags) ? h.record.tags : [],
1182
+ updatedAt: h.record.updatedAt,
1183
+ summary: summarize(h.record.content, chars),
1184
+ })),
1185
+ }
1186
+ }
1106
1187
  if (wantedTopK !== undefined) result.records = result.records.slice(0, wantedTopK)
1107
1188
  // 上下文去重:同一条记忆同版本已经出现过 → 只回 id,摘要让 memory_get 按需取。
1108
1189
  applySummaryDedupe(opts, exec, result.records)
@@ -8,6 +8,8 @@
8
8
  * 0.20.0:范围外命中被挡住时,把**真实原因**(用户拒绝 / 审批超时 / 无法审批)
9
9
  * 写进渲染文本。
10
10
  * 0.23.0:绝对限制与「不可读」开关也会被说明(不再假装"不存在"),并提示怎么调整。
11
+ * 0.27.0:普通限制下范围外命中不再自动弹审批 —— 检索结果带 outOfScope 索引
12
+ * (命中作用域聚合 + 条目印象,不含正文),审批改为 Agent 显式发起。
11
13
  */
12
14
 
13
15
  import { scopeDisplayName } from '../provider/scope.js'
@@ -40,6 +42,8 @@ export function renderWithheldNote(withheld ) {
40
42
  if (withheld === undefined || withheld.count <= 0) return ''
41
43
  const count = withheld.count
42
44
  switch (withheld.reason) {
45
+ case 'out-of-scope':
46
+ return `另有 ${count} 条记忆在本会话的可见域外(限制等级:普通限制)。本次没有弹审批,它们的索引已列在下方 outOfScope 里;确认其中确有需要的内容后,用 memory_search 带 requestApproval=true 显式发起审批,或用 memory_scopes 申请该作用域的会话权限。`
43
47
  case 'rejected':
44
48
  return `另有 ${count} 条记忆在本会话的可见域外,用户拒绝了本次访问(限制等级:普通限制),未返回。如确实需要,请让用户调整「记忆范围」后重试。`
45
49
  case 'timeout':
@@ -59,12 +63,39 @@ export function renderWithheldNote(withheld ) {
59
63
  }
60
64
  }
61
65
 
66
+ /**
67
+ * 范围外索引的尾部说明(0.27.0)。告诉模型这块是「目录印象」不是可读正文,
68
+ * 以及想读时该走哪条路。
69
+ */
70
+ export const OUT_OF_SCOPE_INDEX_NOTE =
71
+ '以上为范围外记忆的索引(不含正文)。需要正文时:用 memory_search 带 requestApproval=true 重新发起同一次搜索(会弹审批),或用 memory_scopes(action="request") 申请该作用域的本会话权限。'
72
+
73
+ /**
74
+ * 范围外索引块:命中作用域聚合 + 条目印象。刻意与可见域内的结果分开排版,
75
+ * 模型一眼能分清「哪些已返回、哪些只是线索」。
76
+ */
77
+ function renderOutOfScopeIndex(
78
+ outOfScope ,
79
+ label ,
80
+ ) {
81
+ const scopes = outOfScope.scopes.map((item) => `${label(item.scope)}(${item.records})`).join('、')
82
+ const lines = outOfScope.records.map((entry) => {
83
+ const tags = joinList(entry.tags)
84
+ const meta = `${label(entry.scope)}/${entry.kind}${tags === '' ? '' : ` · ${tags}`}`
85
+ return `[${entry.score.toFixed(3)}] ${shortId(entry.id)} (${meta}) ${entry.summary}`
86
+ })
87
+ return [`范围外命中:${scopes}`, ...lines, '', OUT_OF_SCOPE_INDEX_NOTE].join('\n')
88
+ }
89
+
62
90
  /** 「[得分] id (作用域/类型 · 标签) 摘要」;没有任何一条命中时给明确空结果。 */
63
91
  export function renderSearchResult(value , label ) {
64
92
  const note = renderWithheldNote(value.withheld)
93
+ const index = value.outOfScope !== undefined && (value.outOfScope.records.length > 0 || value.outOfScope.scopes.length > 0)
94
+ ? renderOutOfScopeIndex(value.outOfScope, label)
95
+ : ''
65
96
  if (value.records.length === 0) {
66
- if (note === '') return '没有找到相关记忆。'
67
- return `没有找到可见范围内的相关记忆。\n${note}`
97
+ if (note === '' && index === '') return '没有找到相关记忆。'
98
+ return [`没有找到可见范围内的相关记忆。`, index, note].filter((part) => part !== '').join('\n\n')
68
99
  }
69
100
  // 已出现过的条目(上下文去重)只回 id:不带作用域/类型/标签/摘要。
70
101
  // 它们单独成块、与带摘要的条目之间空一行 —— 否则一串裸 id 看起来像上一条的
@@ -81,7 +112,7 @@ export function renderSearchResult(value , label )
81
112
  shown.push(`[${hit.score.toFixed(3)}] ${shortId(hit.id)} (${meta}) ${hit.summary}`)
82
113
  }
83
114
  const body = [shown.join('\n'), bare.join('\n')].filter((part) => part !== '').join('\n\n')
84
- const tail = [bare.length > 0 ? DEDUPE_NOTE : '', note].filter((part) => part !== '').join('\n\n')
115
+ const tail = [bare.length > 0 ? DEDUPE_NOTE : '', index, note].filter((part) => part !== '').join('\n\n')
85
116
  return tail === '' ? body : `${body}\n\n${tail}`
86
117
  }
87
118
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@restregular/dsh-memory",
3
- "version": "0.26.0",
3
+ "version": "0.27.0",
4
4
  "description": "DeepSeek Harness 记忆系统(单包单入口):JSONL 存储 + 本地向量检索(BGE-M3)+ 五个模型工具 + 自动召回注入 + 管理面板。",
5
5
  "icon": "./icon.svg",
6
6
  "type": "module",