@restregular/dsh-memory 0.25.14 → 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,23 @@
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
+
14
+ ## 0.26.0 — 作用域参数接受 `custom:` 展示前缀:自动归一,不再写「幽灵授权」
15
+
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`)。
17
+ - **输入层归一**:`normalizeScopeInput` 新增 `custom:` 分支 —— 剥一层前缀后仍按自定义名严格校验(`custom:` / `custom:foo:bar` / `custom:global` 仍 `SCOPE_INVALID`,错误文案提示 `pass the bare scope name`)。`memory_scopes request` 现在和其他工具一样走 `resolveScope`:`custom:handbook` 与 `handbook` 合并成一条申请,`all` 与非法名在弹审批前就明确报错。
18
+ - **兜住旧数据**:`canonicalScope` 与 grants 解析用 `normalizeScopeKey` 把 `custom:` 折回裸键,0.25.x 写下的幽灵授权读取时自动生效,不用手工清理;`SessionGrantsStore.add` 落盘前用 `isWellFormedScopeKey` 卡形态;`scopeDefaultName` 对已带前缀的键幂等,不再渲染成 `custom:custom:...`。
19
+ - **讲清楚**:注入的「记忆系统」常驻段新增作用域写法说明;`scope` / `memory_scopes.scopes` 的参数说明补「自定义作用域传裸名,展示名会自动归一」;`scope name must not contain ':'` 的错误补可操作提示。README 第 4 节补同口径说明。
20
+ - 测试:新增 scope 归一 / 展示幂等 / grants 形态守卫 / 旧数据折回 / 工具端到端归一 / 非法名与 `all` 拒绝等 8 个用例;全套 518 tests / 517 pass / 1 skipped(`multiprocess.test.ts` 需真起子进程)。
21
+
5
22
  ## 0.25.14 — 侧边栏给等待记忆审批的会话显示黄点 /「待审批」
6
23
 
7
24
  - **问题**:范围外记忆审批以前只是插件自己画在 `conversation.input.dock` 的卡片;宿主的侧边栏会话列表并不认识它,所以工具在等审批时,那一行没有系统审批 / ask 工具那样的黄点,也不会被「待审批」水线自动顶出来。宿主这两类阻塞都来自 `ctx.uiSession` 的 pending-interaction 注册表(`dsh-client-ui-approval` 发 `kind:'approval'`,`dsh-client-ui-user-questions` 发 `kind:'question'`)。
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` 只读目录:给作用域名字 / 用途 / 当前可读可写状态,不返回任何正文 |
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` 取全文 |
@@ -93,6 +93,7 @@ JSONL 落盘 · 本机向量检索 · 五个模型工具 · 自动召回 · 硬
93
93
  - **默认范围**:没有显式设置时(新会话)按默认设置生效 —— **当前会话 + 当前项目 + global + 已绑定的作用域** + **普通限制**;面板按同一份默认范围预选,不会出现空面板。
94
94
  - **本会话那一行的名字**(0.25.8):本会话 `session:<id>` 那一行固定显示「**当前会话**」(0.25.10 起叫 `session:当前会话`,原始 scope 键仍在 `title` 里),别的会话的 scope 仍按标题 / 短 id 显示;搜索也按显示名匹配,输入「当前会话」即可筛到这一行。
95
95
  - **作用域名字带类型前缀**(0.25.10):所有展示名都以 `global:` / `project:` / `session:` / `custom:` 开头 —— `global:全局`、`project:D:\repositories\dsh-memory`、`session:session-1a2b3c4d`、`custom:handbook`。**global 与自定义作用域最容易被漏掉**:它们的 scope 键本身没有前缀(`global` 是个关键字、自定义就是裸名字),前缀必须按类型补。项目 / 自定义作用域有别名时是 `project:<别名>` / `custom:<别名>`,会话有标题时是 `session:<标题>(session-1a2b3c4d)`。
96
+ - **参数仍传裸名**(0.26.0):展示名只用于显示。Agent 把 `custom:handbook` 直接粘进作用域参数时会被**自动归一**成 `handbook`(不再是另一条永远匹配不到记录的授权);`custom:` 后面仍必须是合法自定义名,`custom:` / `custom:foo:bar` / `custom:global` 都会被 `SCOPE_INVALID` 拒绝。旧 grants 文件里遗留的 `custom:` 键在读取时也会折回裸键。
96
97
  - **会话作用域的短 id**(0.25.9):会话 id 取**前 16 位**(`session-` + 8 位 uuid)。以前取前 8 位,而真机会话 id 恰好以 `session-` 开头(正好 8 个字符),结果所有会话作用域都显示成同一个名字——等于没给 id。
97
98
  - **浮窗里能直接看到真实键**(0.25.11):显示名与真实键不一致时(项目别名 → 完整路径、会话短 id → 完整 uuid、自定义名 → 裸键),每行名称下面多一行等宽的完整键;**不做手工截断**,放不下就按容器宽度用 CSS 省略号收尾,窗口宽就多显示几个字符。键行是等宽小字、和勾选框左对齐。记录卡 / 记忆树 / 审批卡的作用域徽标都在 `title` 里给出「显示名 → 真实键」。
98
99
  - **搜索与批量**:顶部可搜索作用域,支持「全选 / 取消全选」;列表最大高度受限,作用域多时在浮窗内滚动。**整张作用域卡片都能点**(0.25.7 起)——点名称、记录数或行内留白等同点勾选框,只有行内的按钮(勾选框 / 绑定 / 可读 / 可写)各管各的,点它们不会再多切换一次。
@@ -100,7 +101,7 @@ JSONL 落盘 · 本机向量检索 · 五个模型工具 · 自动召回 · 硬
100
101
  - **状态按钮(0.23.0 / 0.23.1,绑定即存 0.25.13)**:作用域列表每行有【绑定】、【可读】|【可写】。**默认范围自带的会话 + 项目 + global 显示为已绑定且不可取消**;**绑定**按钮用于把其它作用域额外并入当前工作区的默认范围(没有显式覆盖的新会话可见)——**点一下立即保存**(`POST /memory/api/bindings`),不用再点「保存」,写入失败会回滚按钮状态并在浮窗里报错;**可读 / 可写**是会话级,独立控制该作用域的读取与写入(关掉可读 → 搜索 / 读取跳过并说明原因;关掉可写 → 保存 / 删除被拒绝并说明原因),这两项仍是草稿,点「保存」才生效。绑定是工作区级设置(只影响本工作区**新会话**的默认范围),当前会话读什么并没有变,所以**绑定变化不注入上下文提示**。
101
102
  - **限制等级**:
102
103
  - **绝对限制**:可见域外的读取 / 写入 / 删除一律不执行;命中被挡住时会明确告诉 Agent 是「绝对限制」以及怎么调整(不再假装记忆不存在)。
103
- - **普通限制**(默认):可见域内正常返回;命中范围外记忆时,工具会暂停并在**该会话**的输入框上方显示审批卡,展示 Agent 的查询关键词与范围外记忆摘要;读审批可以逐条勾选,只允许其中一条或多条。用户拒绝 / 5 分钟未回答时,工具结果里会明确写出真实原因(「用户拒绝了本次访问」/「审批超时」),模型不会误以为记忆不存在。范围外写入 / 删除同样走审批。
104
+ - **普通限制**(默认):可见域内正常返回;命中范围外记忆时**默认不弹审批**——结果里给一份范围外索引(命中了哪些作用域、各几条,加每条的 id / 类型 / 标签 / 短摘要印象,不含正文),Agent 确认索引里确有需要的内容后,带 `requestApproval=true` 重发查询或用 `memory_scopes request` 申请作用域权限,**这时**才在该会话的输入框上方显示审批卡,展示 Agent 的查询关键词与范围外记忆摘要;读审批可以逐条勾选,只允许其中一条或多条。用户拒绝 / 5 分钟未回答时,工具结果里会明确写出真实原因(「用户拒绝了本次访问」/「审批超时」),模型不会误以为记忆不存在。范围外写入 / 删除照旧直接走审批。
104
105
  - **无限制**:不启用范围白名单,可以读写任意作用域(选择仍会保存,供下次切换)。
105
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·待撤销」标记一律丢弃,重开只显示服务端真值(没保存就还原,不记住草稿)。
106
107
  - **不再按记忆类型收窄**:0.19.1 起只按作用域限制;旧配置里的 `kinds` 会被忽略,同一作用域下的事实 / 规则 / 流程等都可读。
@@ -243,6 +244,13 @@ memory_forget({ "id": "3f2a9c1d", "description": "删除过期的临时结论" }
243
244
  | `session:<id>` / `project:<path>` | 显式钉住某个会话 / 工作区 |
244
245
  | `all` / `*` | **只在读取时可用**:跨所有已发现作用域 |
245
246
 
247
+ **参数写法与展示名(0.26.0)**:自定义作用域传**裸名**(`handbook`)。工具输出 / 注入摘要 / 面板里看到的
248
+ `custom:handbook` 是展示名——直接粘进参数也会被自动归一(剥一层 `custom:`),不会再写成一条匹配不到记录的
249
+ 「幽灵授权」;归一后剩下的部分仍按自定义名严格校验(`custom:foo:bar`、`custom:` 都是 `SCOPE_INVALID`,
250
+ `custom:global` 这种包保留名的写法同样拒绝)。`project:` / `session:` 本来就既是展示名也是参数键。
251
+ `memory_scopes` 目录行形如 `custom:handbook(handbook)`,括号里就是该传的键;旧 grants 文件里遗留的
252
+ `custom:` 键在读取时也会自动折回裸键,不需要手工清理。
253
+
246
254
  项目作用域的身份永远是 `project:<绝对路径>`,别名只影响显示与引用,不迁移数据。
247
255
  同一路径重复用同一个名字是幂等的;换名字会覆盖原别名;另一个路径抢同一个名字会被拒绝
248
256
  (`SCOPE_NAME_TAKEN`)。
@@ -261,7 +269,9 @@ memory_save({
261
269
  })
262
270
  ```
263
271
 
264
- 用途会出现在 `memory_scopes` 的目录里:
272
+ 用途会出现在 `memory_scopes` 的目录里;没写过用途的作用域会按类型给一句**默认描述**
273
+ (0.27.0 起:global = 跨项目共享、project = 绑定当前工作区、session = 仅本会话可见、
274
+ custom = 按名字聚合,建议创建时写明用途),手写过的 `scopeDescription` 永远优先:
265
275
 
266
276
  ```js
267
277
  memory_scopes({ action: "list", description: "看看有哪些作用域、各自干什么" })
@@ -270,6 +280,12 @@ memory_scopes({ action: "list", description: "看看有哪些作用域、各自
270
280
  绝对限制下**目录可见但正文不可读**:范围外作用域仍显示名字与用途(方便判断要不要让用户
271
281
  调整范围),但记录数、正文、申请入口都不会返回。
272
282
 
283
+ **范围外命中先看索引(0.27.0)**:普通限制下 `memory_search` 撞到范围外记忆**默认不弹审批**,
284
+ 结果里的 `outOfScope` 字段给出索引——命中了哪些作用域、各几条,加每条的
285
+ id / score / 类型 / 标签 / 短摘要(不含正文)。确认索引里确有需要的内容后,再显式发起:
286
+ 带 `requestApproval: true` 重发同一次查询(立即弹审批),或用 `memory_get` 拿 id 读正文 /
287
+ `memory_scopes request` 申请作用域权限。不要凭索引里的摘要就直接引用范围外内容。
288
+
273
289
  **申请本会话权限(0.24.0 / D3)**:普通限制下,Agent 可以对**范围外**作用域发申请;
274
290
  默认只申请只读,写权限必须显式列出:
275
291
 
@@ -456,6 +472,8 @@ retrieval:
456
472
  scope 键有三种形态:`global`、`project:<cwd>`、`session:<会话 id>`,其余是自定义名
457
473
  (小写折叠、内部空白折成一个空格、最长 64 字符,禁止 `:`、路径分隔符、控制字符、`..`
458
474
  与保留名 `global/project/session/all`)。**没有任何数据迁移**:旧的 `project:<cwd>` 文件继续原样读写。
475
+ 展示用的 `custom:<名字>` 不是键:0.26.0 起参数里粘进来会被自动剥掉一层前缀(`custom:` 后面仍是
476
+ 合法自定义名才行),旧的 grants / 可见范围里遗留的 `custom:` 键读取时也折回裸键。
459
477
 
460
478
  `installRoot` 默认 `~/.dsh/memory-vector`;显式配了 `storeDir` 时取它的父目录。
461
479
 
@@ -593,6 +611,7 @@ npm run verify # 构建到 .verify/,不落 packages/
593
611
 
594
612
  ## 更新日志
595
613
 
614
+ - **0.27.0** —— 范围外命中「先索引后审批」:普通限制下 `memory_search` 不再自动弹审批,结果新增 `outOfScope` 索引(作用域聚合 + 条目印象,不含正文),`requestApproval: true` 显式发起审批;`withheld` 新增 `out-of-scope` 原因;`memory_scopes` 目录给没写用途的作用域按类型补默认描述。
596
615
  - **0.22.3** —— 审批卡高度与宿主审批卡同口径(去掉额外的 `46vh` 上限),矮窗口下详情行固定后条目列表仍有滚动空间。
597
616
  - **0.22.2** —— 修复审批卡条目不显示 Agent 查询 / 说明:两行原来带 `overflow:auto`,在 flex 列里会被长列表压成 0 高;现在锁 `flex:none`,只让列表滚动。
598
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,10 +8,14 @@ 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。
14
16
 
17
+ 作用域参数怎么写:自定义作用域用**裸名**(dsh-plugin-dev)。工具输出、注入摘要与面板里看到的是展示名——custom:dsh-plugin-dev / project:<路径> / session:<id>;其中 project: 与 session: 可以直接当参数,custom: 前缀也会被自动归一成裸名,不必自己加,更不要叠成 custom:custom:...。memory_scopes 目录行形如 custom:handbook(handbook),括号里就是该传的参数。传 all 只能读,不能用于申请权限。
18
+
15
19
  新建自定义作用域时,memory_save 必须带 scopeDescription(一句话用途);可选带 scopeRule 写一条初始规则。已有作用域带上 scopeDescription 表示更新用途,不会写初始记忆。
16
20
 
17
21
  同一会话里已经出现过的记忆,memory_search / memory_list 只回 ID 并注明“摘要因上下文去重被省略”;那不是没找到,需要正文时直接用 memory_get 取。
@@ -19,6 +19,7 @@
19
19
  import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
20
20
  import { createHash, randomUUID } from 'node:crypto'
21
21
  import { join } from 'node:path'
22
+ import { isWellFormedScopeKey, normalizeScopeKey } from './scope.js'
22
23
 
23
24
  export const GRANTS_VERSION = 1
24
25
 
@@ -70,9 +71,12 @@ function cleanPermissions(raw ) {
70
71
  function parseGrant(raw , sessionId ) {
71
72
  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return undefined
72
73
  const value = raw
73
- const scope = asString(value.scope)
74
+ const rawScope = asString(value.scope)
74
75
  const id = asString(value.id)
75
- if (scope === undefined || id === undefined) return undefined
76
+ if (rawScope === undefined || id === undefined) return undefined
77
+ // 0.26.0:旧数据里可能有展示形式 `custom:<名字>`(0.25.x 的 request 未规范化),
78
+ // 读的时候折回真实键,否则这条授权永远匹配不到记录。
79
+ const scope = normalizeScopeKey(rawScope)
76
80
  const permissions = cleanPermissions(value.permissions)
77
81
  if (permissions.length === 0) return undefined
78
82
  return {
@@ -167,9 +171,15 @@ export class SessionGrantsStore {
167
171
  add(sessionId , input ) {
168
172
  const permissions = cleanPermissions(input.permissions)
169
173
  if (permissions.length === 0) throw new Error('grant requires at least one permission')
174
+ // 0.26.0:落盘前把形态卡死。这一层是最后的护栏 —— 带展示前缀 / 带非法字符的
175
+ // 键写进 grants 只会变成"看起来授权成功、检索时又弹审批"的幽灵授权。
176
+ const scope = normalizeScopeKey(input.scope)
177
+ if (!isWellFormedScopeKey(scope)) {
178
+ throw new Error(`grant scope key is malformed: ${JSON.stringify(input.scope)}`)
179
+ }
170
180
  const all = this.readAll(sessionId)
171
181
  const now = Date.now()
172
- const existing = all.grants.find((grant) => grant.scope === input.scope
182
+ const existing = all.grants.find((grant) => grant.scope === scope
173
183
  && grant.revokedAt === undefined
174
184
  && (grant.expiresAt === undefined || grant.expiresAt > now)
175
185
  && (grant.scopeGeneration === input.scopeGeneration))
@@ -183,13 +193,13 @@ export class SessionGrantsStore {
183
193
  }
184
194
  // 同作用域但代次不同:旧代次的 grant 明确作废,避免“同名重建复活旧授权”。
185
195
  for (const grant of all.grants) {
186
- if (grant.scope === input.scope && grant.revokedAt === undefined && grant.scopeGeneration !== input.scopeGeneration) {
196
+ if (grant.scope === scope && grant.revokedAt === undefined && grant.scopeGeneration !== input.scopeGeneration) {
187
197
  grant.revokedAt = now
188
198
  }
189
199
  }
190
200
  const grant = {
191
201
  id: randomUUID(),
192
- scope: input.scope,
202
+ scope,
193
203
  permissions,
194
204
  duration: 'session',
195
205
  sessionId,
@@ -17,8 +17,10 @@
17
17
  import { MemoryStore, newId, scopeFileName, } from './store.js'
18
18
  import {
19
19
  canonicalWorkspacePath,
20
+ defaultScopeDescription,
20
21
  isCustomScope,
21
22
  normalizeScopeInput,
23
+ normalizeScopeKey,
22
24
  projectScopeIdentity,
23
25
  resolveCurrentScopes,
24
26
  scopeKind,
@@ -3208,7 +3210,8 @@ export class LocalMemoryService {
3208
3210
  }
3209
3211
 
3210
3212
  /**
3211
- * 作用域键归一:自定义名可能是别名 → 转回真实键;`project:<路径>` 统一路径写法。
3213
+ * 作用域键归一:自定义名可能是别名 → 转回真实键;`project:<路径>` 统一路径写法;
3214
+ * 展示前缀 `custom:` 剥掉(0.26.0)。
3212
3215
  *
3213
3216
  * 项目键必须过 `canonicalWorkspacePath`:工具层的 `path`、模型显式给的
3214
3217
  * `project:D:/x`、面板 HTTP 写入都从这里落盘,同一个目录不能因为 `/` 与 `\` 的差别
@@ -3222,6 +3225,10 @@ export class LocalMemoryService {
3222
3225
  const canonical = canonicalWorkspacePath(path)
3223
3226
  return (canonical === path ? scope : `project:${canonical}`)
3224
3227
  }
3228
+ // 0.26.0:展示形式 `custom:<名字>` 与裸名是同一个作用域。旧数据(grants / visibility /
3229
+ // bindings)里若留下过带前缀的键,读的时候自动折回真实键,不再出现"幽灵授权"。
3230
+ const bare = normalizeScopeKey(scope)
3231
+ if (bare !== scope) return (this.names.scopeOf(bare) ) ?? (bare )
3225
3232
  return (this.names.scopeOf(scope) ) ?? scope
3226
3233
  }
3227
3234
 
@@ -3323,10 +3330,13 @@ export class LocalMemoryService {
3323
3330
  : 'restricted'
3324
3331
  const name = meta?.name ?? this.names.nameOf(scope)
3325
3332
  const initialRecords = policy.level === 'absolute' ? undefined : this.initialRecordsOf(scope)
3333
+ // 0.27.0:scope-meta 没写用途时按作用域类型给默认描述,
3334
+ // 让目录里每一条都自带「这个域是干什么的」。
3335
+ const description = meta?.description ?? defaultScopeDescription(scope)
3326
3336
  out.push({
3327
3337
  scope,
3328
3338
  ...(name !== undefined ? { name } : {}),
3329
- ...(meta !== undefined ? { description: meta.description } : {}),
3339
+ ...(description !== '' ? { description } : {}),
3330
3340
  origin: meta?.origin ?? scopeKind(scope),
3331
3341
  ...(inScope ? { records: stat?.records ?? 0 } : {}),
3332
3342
  inScope,
@@ -16,7 +16,9 @@
16
16
  * session:<id> 一个会话(同一个 projects/<sha1>.jsonl 体系)
17
17
  * <自定义名> 自由命名,内部键仍是自定义名本身
18
18
  * 三者都由 `scopeFileName()` 映射到文件名,因此**自定义名里出现 ':' 一律拒绝**,否则
19
- * `foo:bar` 会与保留前缀撞成同一个键空间,用户也能靠它伪造 `project:` 键。
19
+ * `foo:bar` 会与保留前缀撞成同一个键空间,用户也能靠它伪造 `project:` 键。唯一的例外
20
+ * 是**展示前缀** `custom:`(0.26.0 起在 normalizeScopeInput 里剥掉一层再校验)——
21
+ * 它只会出现在工具输出 / 摘要 / 面板里,不属于键空间。
20
22
  */
21
23
  import { createHash } from 'node:crypto'
22
24
  import { posix, win32 } from 'node:path'
@@ -87,7 +89,9 @@ function normalizeCustomName(raw )
87
89
  if (name === '..' || name === '.') return { ok: false, message: "scope name must not be '.' or '..'" }
88
90
  if (/^[. ]+$/u.test(name)) return { ok: false, message: 'scope name must contain more than dots and spaces' }
89
91
  if (name.includes('..')) return { ok: false, message: "scope name must not contain '..'" }
90
- if (name.includes(':')) return { ok: false, message: "scope name must not contain ':'" }
92
+ if (name.includes(':')) {
93
+ return { ok: false, message: "scope name must not contain ':'; pass the bare scope name (e.g. 'dsh-plugin-dev')" }
94
+ }
91
95
  if (name.includes('/') || name.includes('\\')) {
92
96
  return { ok: false, message: 'scope name must not contain path separators' }
93
97
  }
@@ -128,6 +132,7 @@ export function normalizeScopeName(raw )
128
132
  * - 'global' | 'project' | 'session' → 各自的**种类**,不在这里解析 cwd/会话(纯函数拿不到);
129
133
  * - 'all' | '*' → 跨所有作用域(仅读路径合法,写路径由 assertWritableScope 拒绝);
130
134
  * - 'project:*' | 'session:*' → 原样放行(显式 pin 某个项目 / 某个会话);
135
+ * - 'custom:*' → 归一成裸名(0.26.0:展示层就是这么渲染自定义作用域的);
131
136
  * - 其余 → 自定义名,严格校验。
132
137
  *
133
138
  * 不合法**不再静默回退**,一律返回 SCOPE_INVALID。
@@ -154,12 +159,63 @@ export function normalizeScopeInput(raw )
154
159
  ? { ok: true, kind: 'session', scope: prefixed.key }
155
160
  : { ok: false, code: 'SCOPE_INVALID', message: prefixed.message }
156
161
  }
162
+ // 展示形式 `custom:<名字>` 归一到裸名(0.26.0)。0.25.10 起工具输出、注入摘要、面板
163
+ // 全部用 `custom:<名字>` 渲染,而自定义作用域的**键本身没有前缀**;模型照抄回来时
164
+ // 不该落到另一个(永远匹配不到记录的)键上。这里只剥一层,剩下的部分仍按自定义名规则
165
+ // 严格校验 —— 所以 `custom:foo:bar` / `custom:` 依然是 SCOPE_INVALID。
166
+ if (lower.startsWith('custom:')) {
167
+ const bare = value.slice('custom:'.length).trim()
168
+ if (bare.length === 0) {
169
+ return { ok: false, code: 'SCOPE_INVALID', message: "custom: must be followed by a scope name (e.g. 'dsh-plugin-dev')" }
170
+ }
171
+ if (RESERVED_SCOPE_NAMES.has(bare.toLowerCase())) {
172
+ return { ok: false, code: 'SCOPE_INVALID', message: `custom: cannot wrap the reserved name "${bare.toLowerCase()}"; use the bare scope name instead` }
173
+ }
174
+ const custom = normalizeCustomName(bare)
175
+ return custom.ok
176
+ ? { ok: true, kind: 'custom', scope: custom.name }
177
+ : { ok: false, code: 'SCOPE_INVALID', message: custom.message }
178
+ }
157
179
  const custom = normalizeCustomName(value)
158
180
  return custom.ok
159
181
  ? { ok: true, kind: 'custom', scope: custom.name }
160
182
  : { ok: false, code: 'SCOPE_INVALID', message: custom.message }
161
183
  }
162
184
 
185
+ /**
186
+ * 把"可能是展示形式"的作用域字符串归一到真实键(0.26.0)。
187
+ *
188
+ * 只剥**一层** `custom:`:自定义作用域的键本身没有前缀,`custom:` 是 `scopeDisplayName`
189
+ * 按类型补的展示前缀。用于读既有数据(grants / visibility / 面板旧键)与渲染兜底;
190
+ * 不做存在性检查,也不改 `project:` / `session:` 键。
191
+ */
192
+ export function normalizeScopeKey(value ) {
193
+ const trimmed = value.trim()
194
+ if (!trimmed.toLowerCase().startsWith('custom:')) return trimmed
195
+ const bare = trimmed.slice('custom:'.length).trim()
196
+ return bare === '' ? trimmed : bare
197
+ }
198
+
199
+ /**
200
+ * 形态是否是一个合法的作用域键(不做存在性检查,0.26.0)。
201
+ *
202
+ * 用途:grant 落盘前拒绝"永远匹配不到任何记录"的幽灵键 —— 0.25.x 里
203
+ * `memory_scopes request` 接受过 `custom:dsh-plugin-dev` 并把它原样写进 grants,
204
+ * 结果授权看起来成功、检索时却重新弹审批。`custom:` 展示前缀不算合法键。
205
+ */
206
+ export function isWellFormedScopeKey(value ) {
207
+ if (value === 'global') return true
208
+ if (value.startsWith('project:')) {
209
+ const path = value.slice('project:'.length).trim()
210
+ return path !== '' && !hasControlChar(value) && codePointLength(value) <= MAX_PREFIXED_SCOPE_CHARS
211
+ }
212
+ if (value.startsWith('session:')) {
213
+ const id = value.slice('session:'.length).trim()
214
+ return id !== '' && !hasControlChar(value) && codePointLength(value) <= MAX_PREFIXED_SCOPE_CHARS
215
+ }
216
+ return normalizeCustomName(value).ok
217
+ }
218
+
163
219
  /** scope 的种类(用于命名空间 / 阈值 / 排序);未知形态按自定义处理。 */
164
220
  export function scopeKind(scope ) {
165
221
  if (scope === 'global') return 'global'
@@ -218,7 +274,9 @@ export function scopeDefaultName(scope ) {
218
274
  if (scope === 'global') return '全局'
219
275
  if (scope.startsWith('project:')) return scope.slice('project:'.length)
220
276
  if (scope.startsWith('session:')) return sessionShortId(scope.slice('session:'.length))
221
- return String(scope)
277
+ // 兜底:输入侧已把 `custom:<名字>` 归一,但旧数据 / 外部调用仍可能带着它进来,
278
+ // 展示时绝不能叠成 `custom:custom:<名字>`。
279
+ return normalizeScopeKey(String(scope)) || String(scope)
222
280
  }
223
281
 
224
282
  /**
@@ -234,6 +292,20 @@ export function scopeDisplayName(scope , humanName ) {
234
292
  return `${scopeTypePrefix(scope)}${name}`
235
293
  }
236
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
+
237
309
  /** 写路径遇到只读 scope 时的错误码('all' 不能写)。 */
238
310
  export const SCOPE_NOT_WRITABLE = 'SCOPE_NOT_WRITABLE'
239
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
 
@@ -258,6 +259,8 @@ import { canonicalWorkspacePath, normalizeScopeInput, resolveScopeRef } from '..
258
259
  const SCOPE_DESCRIPTION =
259
260
  "省略=当前会话;'global'=所有项目共享;'project'=当前工作区;其他任意名称=自定义作用域"
260
261
  + "(memory_save 时不存在则自动创建;由 Agent 创建时必须同时提供 scopeDescription 说明用途)。"
262
+ + "自定义作用域按裸名传(如 'dsh-plugin-dev');工具输出 / 摘要里看到的展示名 "
263
+ + "'custom:<名字>' 会被自动归一成裸名,不用自己加前缀。"
261
264
  + "读取时可用 'all' 跨所有作用域。"
262
265
 
263
266
  export class MemoryToolError extends Error {
@@ -459,6 +462,27 @@ function withheldReasonFor(
459
462
  return 'read-disabled'
460
463
  }
461
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
+
462
486
  /**
463
487
  * memory_save 的 supersedes 参数说明(模型可见)。
464
488
  * 检索 / 列表 / 摘要 / 规则索引里给的 id 都是 8 位短 id,而 supersedes 在 provider
@@ -696,6 +720,15 @@ function readScopes(opts , service , agent
696
720
  return [...new Set([fallback, 'global'])]
697
721
  }
698
722
 
723
+ /**
724
+ * 当前会话的 scope 键(拿不到会话就 undefined)。给显式写成裸 `session` 的
725
+ * 请求兜底 —— `resolveScope` 在读路径上会把它解析成"合并集合",申请权限时必须
726
+ * 落到一个具体键。
727
+ */
728
+ function currentSessionScope(service , exec ) {
729
+ return service.resolveReadScopes?.(agentOf(exec))?.find((scope) => scope.startsWith('session:'))
730
+ }
731
+
699
732
  /** 写路径默认口径;provider 不支持时退回 project。 */
700
733
  function writeDefault(opts ) {
701
734
  return opts.defaultScope ?? 'session'
@@ -962,6 +995,12 @@ function applySummaryDedupe(opts , exec , records
962
995
 
963
996
                              
964
997
 
998
+
999
+                         
1000
+                               
1001
+                      
1002
+
1003
+
965
1004
 
966
1005
 
967
1006
 
@@ -980,6 +1019,22 @@ function applySummaryDedupe(opts , exec , records
980
1019
 
981
1020
 
982
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
+
983
1038
 
984
1039
 
985
1040
 
@@ -987,12 +1042,17 @@ function applySummaryDedupe(opts , exec , records
987
1042
                                
988
1043
 
989
1044
 
1045
+
1046
+                        
1047
+                                
1048
+
1049
+
990
1050
 
991
1051
 
992
1052
  export function memorySearchTool(opts ) {
993
1053
  return {
994
1054
  name: 'memory_search',
995
- 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.',
996
1056
  parameters: {
997
1057
  query: { type: 'string', required: true },
998
1058
  scope: { type: 'string', description: SCOPE_DESCRIPTION },
@@ -1000,6 +1060,7 @@ export function memorySearchTool(opts )
1000
1060
  includeSuperseded: { type: 'boolean', description: '默认 false;true 时把已被 supersede 的旧版本也返回(历史核对)' },
1001
1061
  summaryChars: { type: 'number', description: `每条摘要的字数上限(默认 ${DEFAULT_SUMMARY_CHARS},20~2000)` },
1002
1062
  description: { type: 'string', description: DESCRIPTION_PARAM_DESCRIPTION },
1063
+ requestApproval: { type: 'boolean', description: '默认 false:范围外命中只返回索引(outOfScope 字段),不自动弹审批;true = 立即向用户发起审批,允许的条目并入 records。确认索引里有值得读的内容后再传 true。' },
1003
1064
  },
1004
1065
  async execute(args , exec ) {
1005
1066
  const service = svc(opts)
@@ -1048,8 +1109,12 @@ export function memorySearchTool(opts )
1048
1109
  const outside = hits.filter((hit) => !recordAllowed(decide, policy, hit.record.scope, hit.record.kind))
1049
1110
  // 只有“作用域不在范围里”才可能审批;absolute 与 read:false 都不 requestable。
1050
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
1051
1116
  let verdict
1052
- if (needsApproval.length > 0 && level === 'normal') {
1117
+ if (needsApproval.length > 0 && level === 'normal' && wantsApproval) {
1053
1118
  verdict = await askOutOfScope(
1054
1119
  service,
1055
1120
  agent,
@@ -1089,9 +1154,36 @@ export function memorySearchTool(opts )
1089
1154
  if (denied > 0) {
1090
1155
  const approvedIds = new Set(approvedOutside.map((hit) => hit.record.id))
1091
1156
  const deniedRecords = outside.filter((hit) => !approvedIds.has(hit.record.id))
1092
- 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 })))
1093
1163
  if (reason !== undefined) result.withheld = { count: denied, reason }
1094
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
+ }
1095
1187
  if (wantedTopK !== undefined) result.records = result.records.slice(0, wantedTopK)
1096
1188
  // 上下文去重:同一条记忆同版本已经出现过 → 只回 id,摘要让 memory_get 按需取。
1097
1189
  applySummaryDedupe(opts, exec, result.records)
@@ -1420,7 +1512,7 @@ export function memoryScopesTool(opts )
1420
1512
  scopes: {
1421
1513
  type: 'array',
1422
1514
  items: { type: 'string' },
1423
- description: 'request:要申请的作用域键,最多 5 个(一次申请多个时共用同一组 permissions)',
1515
+ description: 'request:要申请的作用域,最多 5 个(一次申请多个时共用同一组 permissions);自定义作用域传裸名,如 "dsh-plugin-dev"("custom:dsh-plugin-dev" 会自动归一)',
1424
1516
  },
1425
1517
  permissions: {
1426
1518
  type: 'array',
@@ -1439,15 +1531,31 @@ export function memoryScopesTool(opts )
1439
1531
  if (typeof service.requestScopeGrants !== 'function') {
1440
1532
  throw new MemoryToolError('SCOPES_UNAVAILABLE', '当前 provider 不支持作用域权限申请(请升级 @restregular/dsh-memory)')
1441
1533
  }
1442
- const scopes = Array.isArray(args.scopes)
1443
- ? [...new Set(args.scopes.map((scope) => String(scope).trim()).filter((scope) => scope !== ''))]
1534
+ const rawScopes = Array.isArray(args.scopes)
1535
+ ? args.scopes.map((scope) => String(scope).trim()).filter((scope) => scope !== '')
1444
1536
  : []
1445
- if (scopes.length === 0) {
1537
+ if (rawScopes.length === 0) {
1446
1538
  throw new MemoryToolError('REQUESTS_REQUIRED', 'action="request" 需要 scopes 数组(要申请的作用域键)')
1447
1539
  }
1448
- if (scopes.length > 5) {
1540
+ // 0.26.0:作用域参数先过与其他 memory_* 相同的规范层。展示形式 `custom:<名字>`
1541
+ // 归一成裸名;非法名 / 'all' 在这里明确报错,而不是把 "custom:dsh-plugin-dev"
1542
+ // 这类键原样写进 grants —— 那种授权永远匹配不到记录,却会显示"已授予"。
1543
+ const normalizedScopes = []
1544
+ for (const raw of rawScopes) {
1545
+ const resolved = resolveScope(opts, service, exec, raw, 'read')
1546
+ if (resolved.all === true) {
1547
+ throw new MemoryToolError('SCOPE_NOT_WRITABLE', "scope 'all' cannot be requested; name one scope")
1548
+ }
1549
+ const scope = resolved.scope ?? currentSessionScope(service, exec)
1550
+ if (scope === undefined) {
1551
+ throw new MemoryToolError('SCOPE_INVALID', `scope "${raw}" could not be resolved; use a concrete scope name (e.g. 'dsh-plugin-dev')`)
1552
+ }
1553
+ if (!normalizedScopes.includes(scope)) normalizedScopes.push(scope)
1554
+ }
1555
+ if (normalizedScopes.length > 5) {
1449
1556
  throw new MemoryToolError('REQUESTS_TOO_MANY', '一次最多申请 5 个作用域;请分批申请')
1450
1557
  }
1558
+ const scopes = normalizedScopes
1451
1559
  const permissions = Array.isArray(args.permissions)
1452
1560
  ? [...new Set(args.permissions.filter((permission) => permission === 'read' || permission === 'write'))]
1453
1561
  : ['read' ]
@@ -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.25.14",
3
+ "version": "0.27.0",
4
4
  "description": "DeepSeek Harness 记忆系统(单包单入口):JSONL 存储 + 本地向量检索(BGE-M3)+ 五个模型工具 + 自动召回注入 + 管理面板。",
5
5
  "icon": "./icon.svg",
6
6
  "type": "module",