@restregular/dsh-memory 0.19.1 → 0.20.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,34 @@
2
2
 
3
3
  本项目的版本记录。安装 id 与 npm 版本一一对应。
4
4
 
5
+ ## 0.20.0 — 写入护栏、真实失败原因、默认记忆范围、按钮边框表达限制等级
6
+
7
+ - **默认记忆范围(新会话)**:以前没有显式覆盖 = 完全不限制;现在没有显式覆盖时按默认设置生效:**当前会话 + 当前项目 + global** 三个作用域 + **普通限制**。`visibilityPolicy()` 因此永远返回一份策略,并带 `source: 'explicit' | 'inherited' | 'default'`。
8
+ - 默认策略下普通检索只搜这三个作用域,不会每次都弹审批;显式 `scope:'all'` 或 `memory_get` 命中范围外记录时才发起审批。
9
+ - `visibleScopes()` 语义不变(只代表**显式**覆盖),注入半边的 `inject.extraScopes` / fork 父会话召回不受默认策略影响。
10
+ - **写入护栏(可见范围 = 可操作范围)**:`memory_save` / `memory_forget` 与读取共用同一份可见域。
11
+ - `absolute`:范围外写入报「作用域 … 不存在或不可写」,范围外 id 删除按「不存在」处理,范围外按 query 删除静默无匹配 —— 都不暴露可见域配置。
12
+ - `normal`:范围外写入 / 删除先向用户发一次审批(浮层区分读 / 写 / 删);拒绝、超时、无法审批各自返回真实原因(`VISIBILITY_REJECTED` / `VISIBILITY_TIMEOUT` / `VISIBILITY_UNAVAILABLE`)。
13
+ - `none`:不限制。没有会话上下文的调用(老宿主 / 无 `exec`)不启用护栏。
14
+ - provider 层同样守一道:有 `agent` 且未审批时 `save` 直接拒绝(`SCOPE_NOT_WRITABLE` / `VISIBILITY_APPROVAL_REQUIRED`);面板写入不带 agent,仍是用户本人的操作。
15
+ - **失败信息讲真实原因**:工具结果里的 `withheld` 改为 `{ count, reason: 'rejected' | 'timeout' | 'unavailable' }`,渲染层把原因写进模型可见文本(「用户拒绝了本次访问」「审批在 5 分钟内没有得到答复」「当前环境无法发起审批」)。
16
+ - `absolute` 不再产生 `withheld`,也不再把显式询问范围外 scope 变成 `SCOPE_NOT_VISIBLE` 报错 —— 一律视为不存在。
17
+ - 审批超时与用户主动拒绝已区分:provider 的超时返回 `'timeout'`(以前和拒绝一样)。
18
+ - **记忆范围按钮**:数字 = 生效作用域数量;边框样式 = 限制等级:**绝对限制 = 橙黄(`state-warn-primary`)实线**、**普通限制 = 蓝色(`state-business-primary`)实线**、**无限制 = 灰色虚线**;`title` 里写明「已设置 / 使用默认 / 继承父会话 + 数量 + 等级」。
19
+ - **审批浮层**:区分读取 / 写入 / 删除三种动作(标题、说明文案),写入审批直接展示将被写入的内容。
20
+ - **可见域通知**:恢复默认的注入文案改成「默认 = 会话 + 项目 + global + 普通限制」,并说明写入 / 删除也受同一份可见域约束。
21
+ - 测试:默认策略与默认检索不弹审批、显式 all 的审批 / 拒绝 / 超时、写入与删除护栏(三档 × 工具层与 provider 层)、`withheld` 渲染文案、按钮三档边框与数字。
22
+
23
+ ## 0.19.2 — 深色模式下勾选框 / 保存按钮配色修正,浮窗再收紧
24
+
25
+ - **根因**:宿主深色主题里 `--dsw-alias-brand-primary` 是近白色;0.19.1 把它当填充色,导致选中的勾选框变成白块(勾不可见)、保存按钮变成白底白字。
26
+ - **修正**:勾选框选中态、保存按钮、限制等级选中态改用 `--dsw-alias-state-business-primary`(亮色 #4176e6 / 暗色 #7aaaff);勾/按钮文字用可翻转的 `--dsw-alias-label-primary-foreground`(亮色白、暗色深),两种主题下都有足够对比度。
27
+ - 未选中勾选框:底色用 `label-primary` 5% 的轻填充,边框用 `label-secondary` 52% 混 `border-l1`,深色下不再是几乎看不见的空框。
28
+ - 选中行 / 等级卡的边框与底色也统一成 business-primary 的淡色,避免深色主题里出现白色描边。
29
+ - **高度收紧**:滚动列表 `max-height` 从 `min(300px,40vh)` 降到 `min(220px,32vh)`;浮窗整体从 `min(600px,80vh)` 降到 `min(520px,72vh)`,padding 14→12。
30
+ - 测试:CSS 断言锁定 business-primary + primary-foreground 的组合与新的高度上限;用 headless Chrome 在深色 token 下渲染确认勾选框、保存按钮、等级卡的对比度。
31
+ - 重新构建并发布;0.19.1 的结构与行为不变。
32
+
5
33
  ## 0.19.1 — 记忆范围按钮常驻数字、默认范围预选、取消类型限制、深色模式与阴影收敛
6
34
 
7
35
  - **按钮只显示数字**:去掉「记忆可见域」文字,保存/继承后只显示当前生效的作用域数量;有显式覆盖时仍然高亮,完整说明放在 `title` 里。
package/README.md CHANGED
@@ -84,22 +84,22 @@ JSONL 落盘 · 本机向量检索 · 五个模型工具 · 自动召回 · 硬
84
84
 
85
85
  ### 输入框的记忆范围
86
86
 
87
- 输入框工具行右侧有「记忆范围」按钮。**打开会话时就会读取这个会话的设置**,按钮只显示当前生效的作用域数量(不再显示「记忆可见域」文字);有显式覆盖时高亮。点开的浮窗使用毛玻璃背景,按当前会话列出可选作用域(当前会话 / 当前项目 / global / 已有自定义作用域):
87
+ 输入框工具行右侧有「记忆范围」按钮。**打开会话时就会读取这个会话的设置**,按钮上的数字是当前生效的作用域数量,边框样式表示限制等级(绝对限制 = 橙黄实线 / 普通限制 = 蓝色实线 / 无限制 = 灰色虚线;`title` 里写明「已设置 / 使用默认 / 继承父会话 + 数量 + 等级」)。点开的浮窗使用毛玻璃背景,按当前会话列出可选作用域(当前会话 / 当前项目 / global / 已有自定义作用域):
88
88
 
89
- - **默认范围**:还没有显式设置时,按「会话 + 项目 + global」预选,不会出现空面板。
89
+ - **默认范围**:没有显式设置时(新会话)按默认设置生效 —— **当前会话 + 当前项目 + global** 三个作用域 + **普通限制**;面板按同一份默认范围预选,不会出现空面板。
90
90
  - **搜索与批量**:顶部可搜索作用域,支持「全选 / 取消全选」;列表最大高度受限,作用域多时在浮窗内滚动。
91
91
  - **限制等级**:
92
- - **绝对限制**:可见域外的记忆一律查不到;即使工具内部命中,也不返回结果。
93
- - **普通限制**(默认):可见域内正常返回;命中范围外记忆时,工具会暂停并向用户发起一次审批,展示 Agent 的查询关键词与范围外记忆摘要。
94
- - **无限制**:不启用范围白名单,可以读取任意作用域(选择仍会保存,供下次切换)。
92
+ - **绝对限制**:可见域外的记忆一律查不到(`memory_get` 按 id 取也取不到,`memory_search` / `memory_list` 不返回、也不告诉模型"被挡住");范围外也写不进去,删除范围外记录按"不存在"处理。
93
+ - **普通限制**(默认):可见域内正常返回;命中范围外记忆时,工具会暂停并向用户发起一次审批,展示 Agent 的查询关键词与范围外记忆摘要。用户拒绝 / 5 分钟未回答时,工具结果里会明确写出真实原因(「用户拒绝了本次访问」/「审批超时」),模型不会误以为记忆不存在。范围外写入 / 删除同样走审批。
94
+ - **无限制**:不启用范围白名单,可以读写任意作用域(选择仍会保存,供下次切换)。
95
95
  - **不再按记忆类型收窄**:0.19.1 起只按作用域限制;旧配置里的 `kinds` 会被忽略,同一作用域下的事实 / 规则 / 流程等都可读。
96
- - **审批浮窗**:普通限制下的待审批会出现在界面底部。记忆 ID 悬浮 350ms 后显示完整内容 / 类型 / 作用域 / 重要度 / 标签浮窗(与审计详情同一套行为与样式);点击记忆 ID 跳到「记录」页并展开对应卡片。提供「拒绝」与「允许一次」:允许一次只对本次工具调用生效;拒绝或 5 分钟未回答则工具拿不到这些内容。
96
+ - **审批浮窗**:普通限制下的待审批会出现在界面底部,按动作分为「记忆读取审批 / 记忆写入审批 / 记忆删除审批」。记忆 ID 悬浮 350ms 后显示完整内容 / 类型 / 作用域 / 重要度 / 标签浮窗(与审计详情同一套行为与样式);点击记忆 ID 跳到「记录」页并展开对应卡片。提供「拒绝」与「允许一次」:允许一次只对本次工具调用生效;拒绝、超时或无法发起审批都会把原因告诉模型。
97
97
  - 子 Agent 自动继承父会话 / 根会话的设置;在子 Agent 自己的会话里再设置,只影响那一个会话。
98
98
  - 保存后,下一次 Agent 步骤会通过注入的上下文消息收到「可见域已更新」通知(包含可见范围与限制等级),不需要重启会话。
99
- - 「恢复默认」清除覆盖,回到「会话 + 项目 + global」的默认读取集合。
99
+ - 「恢复默认」清除覆盖,回到默认设置(会话 + 项目 + global + 普通限制)。
100
100
  - 覆盖按会话落盘在 `<storeDir>/visibility/<session>.json`,浏览器刷新 / 插件重载后仍在;0.18 的旧文件按「绝对限制」兼容读取。
101
- - 浮窗与审批卡的半透明背景、边框、文字颜色全部走宿主主题 token,深色模式自动适配;阴影已收敛为小范围投影,不再有大面积明显阴影。
102
- - 只影响**读取**:`memory_save` 的落点仍由 `scope` 参数与默认写口径决定;面板管理页不受可见域限制。
101
+ - 浮窗与审批卡的半透明背景、边框、文字颜色全部走宿主主题 token;勾选框选中态、保存按钮、限制等级选中态使用 `--dsw-alias-state-business-primary` + `--dsw-alias-label-primary-foreground`,深色模式下不会出现白底白勾 / 白底白字;按钮三档边框用 `state-warn-primary`(橙黄)/ `state-business-primary`(蓝)/ 虚线灰;阴影已收敛为小范围投影,滚动列表高度收紧到 `min(220px, 32vh)`。
102
+ - **可见范围 = 可操作范围(0.20.0 起)**:`memory_search` / `memory_list` / `memory_get` 与 `memory_save` / `memory_forget` 共用同一份可见域;面板管理页仍是用户本人的操作,不受会话语义限制。
103
103
 
104
104
  ### 向量服务
105
105
 
package/lib/client.js CHANGED
@@ -488,10 +488,15 @@ window.__ModuleLoader__.load({
488
488
  '.mem-scope-wrap{display:inline-flex;min-width:0}',
489
489
  '.mem-scope-btn{display:inline-flex;align-items:center;gap:5px;height:28px;padding:0 9px;border:1px solid var(--dsw-alias-border-l1);border-radius:9px;background:color-mix(in srgb,var(--dsw-alias-bg-layer-1) 55%,transparent);color:var(--dsw-alias-label-secondary);font-size:12px;line-height:1;cursor:pointer;flex:none;transition:border-color .12s ease,color .12s ease,background .12s ease}',
490
490
  '.mem-scope-btn:hover{background:var(--dsw-alias-interactive-bg-hover);color:var(--dsw-alias-label-primary)}',
491
- '.mem-scope-btn.on{color:var(--dsw-alias-brand-primary);border-color:color-mix(in srgb,var(--dsw-alias-brand-primary) 45%,var(--dsw-alias-border-l1));background:color-mix(in srgb,var(--dsw-alias-brand-primary) 9%,transparent)}',
491
+ // 0.20.0:数字 = 当前生效的作用域数量;边框样式 = 限制等级
492
+ // 绝对限制 = 橙黄实线 · 普通限制 = 蓝色实线 · 无限制 = 灰色虚线
493
+ '.mem-scope-btn.is-absolute{border-color:var(--dsw-alias-state-warn-primary,#d9a23b);color:var(--dsw-alias-state-warn-primary,#d9a23b);background:color-mix(in srgb,var(--dsw-alias-state-warn-primary,#d9a23b) 10%,transparent)}',
494
+ '.mem-scope-btn.is-normal{border-color:var(--dsw-alias-state-business-primary,#4176e6);color:var(--dsw-alias-state-business-primary,#4176e6);background:color-mix(in srgb,var(--dsw-alias-state-business-primary,#4176e6) 10%,transparent)}',
495
+ '.mem-scope-btn.is-none{border:1px dashed color-mix(in srgb,var(--dsw-alias-label-secondary) 55%,var(--dsw-alias-border-l1));color:var(--dsw-alias-label-secondary);background:color-mix(in srgb,var(--dsw-alias-bg-layer-1) 55%,transparent)}',
496
+ '.mem-scope-btn.is-absolute:hover,.mem-scope-btn.is-normal:hover,.mem-scope-btn.is-none:hover{background:var(--dsw-alias-interactive-bg-hover)}',
492
497
  '.mem-scope-btn svg{flex:none}',
493
498
  // 毛玻璃浮窗:半透明 + backdrop blur;不支持 backdrop-filter 时退回实心底。
494
- '.mem-scope-pop{position:fixed;z-index:80;width:340px;max-height:min(600px,80vh);display:flex;flex-direction:column;gap:9px;padding:14px;border:1px solid color-mix(in srgb,var(--dsw-alias-border-l2,var(--dsw-alias-border-l1)) 60%,transparent);border-radius:14px;background:color-mix(in srgb,var(--dsw-alias-bg-layer-1) 78%,transparent);-webkit-backdrop-filter:blur(20px) saturate(1.35);backdrop-filter:blur(20px) saturate(1.35);box-shadow:0 10px 28px rgba(0,0,0,.18);color:var(--dsw-alias-label-primary);font-size:13px;overflow:hidden}',
499
+ '.mem-scope-pop{position:fixed;z-index:80;width:340px;max-height:min(520px,72vh);display:flex;flex-direction:column;gap:8px;padding:12px;border:1px solid color-mix(in srgb,var(--dsw-alias-border-l2,var(--dsw-alias-border-l1)) 60%,transparent);border-radius:14px;background:color-mix(in srgb,var(--dsw-alias-bg-layer-1) 78%,transparent);-webkit-backdrop-filter:blur(20px) saturate(1.35);backdrop-filter:blur(20px) saturate(1.35);box-shadow:0 10px 28px rgba(0,0,0,.18);color:var(--dsw-alias-label-primary);font-size:13px;overflow:hidden}',
495
500
  '@supports not ((backdrop-filter:blur(1px)) or (-webkit-backdrop-filter:blur(1px))){.mem-scope-pop{background:var(--dsw-specific-menu,var(--dsw-alias-bg-layer-1))}}',
496
501
  '.mem-scope-head{display:flex;align-items:center;gap:8px}',
497
502
  '.mem-scope-head h4{margin:0;font-size:13px;font-weight:600;line-height:1.4}',
@@ -503,24 +508,24 @@ window.__ModuleLoader__.load({
503
508
  '.mem-scope-level-btn b{font-size:12px;font-weight:600;color:var(--dsw-alias-label-primary)}',
504
509
  '.mem-scope-level-btn span{font-size:9.5px;line-height:1.4;color:var(--dsw-alias-label-secondary)}',
505
510
  '.mem-scope-level-btn:hover{border-color:color-mix(in srgb,var(--dsw-alias-brand-primary) 40%,var(--dsw-alias-border-l1))}',
506
- '.mem-scope-level-btn.on{border-color:color-mix(in srgb,var(--dsw-alias-brand-primary) 55%,var(--dsw-alias-border-l1));background:color-mix(in srgb,var(--dsw-alias-brand-primary) 11%,transparent)}',
507
- '.mem-scope-level-btn.on b,.mem-scope-level-btn.on span{color:var(--dsw-alias-brand-primary)}',
511
+ '.mem-scope-level-btn.on{border-color:color-mix(in srgb,var(--dsw-alias-state-business-primary) 60%,var(--dsw-alias-border-l1));background:color-mix(in srgb,var(--dsw-alias-state-business-primary) 14%,transparent)}',
512
+ '.mem-scope-level-btn.on b,.mem-scope-level-btn.on span{color:var(--dsw-alias-state-business-primary)}',
508
513
  '.mem-scope-note{padding:5px 8px;border-radius:8px;background:color-mix(in srgb,var(--dsw-alias-state-warn-primary,#d9a23b) 10%,transparent);color:var(--dsw-alias-label-secondary);font-size:11px;line-height:1.5}',
509
514
  '.mem-scope-search{display:flex;align-items:center;gap:6px}',
510
515
  '.mem-scope-search input[type=search]{flex:1;min-width:0;padding:5px 9px;font-size:12px;border:1px solid var(--dsw-alias-border-l1);border-radius:8px;background:color-mix(in srgb,var(--dsw-alias-bg-layer-1) 78%,transparent);color:var(--dsw-alias-label-primary);outline:none}',
511
516
  '.mem-scope-search input[type=search]:focus{border-color:var(--dsw-alias-brand-primary)}',
512
517
  '.mem-scope-search .linkbtn{white-space:nowrap;padding:2px 3px;border:none;background:none;color:var(--dsw-alias-label-secondary);font-size:11px;cursor:pointer}',
513
518
  '.mem-scope-search .linkbtn:hover{color:var(--dsw-alias-brand-primary);border:none}',
514
- '.mem-scope-list{display:flex;flex-direction:column;gap:3px;overflow:auto;min-height:0;max-height:min(300px,40vh);padding:2px 2px 2px 0;scrollbar-width:thin}',
519
+ '.mem-scope-list{display:flex;flex-direction:column;gap:3px;overflow:auto;min-height:0;max-height:min(220px,32vh);padding:2px 2px 2px 0;scrollbar-width:thin}',
515
520
  '.mem-scope-list::-webkit-scrollbar{width:8px}',
516
521
  '.mem-scope-list::-webkit-scrollbar-thumb{background:color-mix(in srgb,var(--dsw-alias-label-secondary) 35%,transparent);border-radius:999px;border:2px solid transparent;background-clip:padding-box}',
517
522
  '.mem-scope-item{display:flex;flex-direction:column;gap:4px;padding:5px 6px;border:1px solid transparent;border-radius:10px}',
518
523
  '.mem-scope-item:hover{background:var(--dsw-alias-interactive-bg-hover)}',
519
- '.mem-scope-item.on{border-color:color-mix(in srgb,var(--dsw-alias-brand-primary) 24%,var(--dsw-alias-border-l1));background:color-mix(in srgb,var(--dsw-alias-brand-primary) 7%,transparent)}',
524
+ '.mem-scope-item.on{border-color:color-mix(in srgb,var(--dsw-alias-state-business-primary) 38%,var(--dsw-alias-border-l1));background:color-mix(in srgb,var(--dsw-alias-state-business-primary) 8%,transparent)}',
520
525
  '.mem-scope-row{display:flex;align-items:center;gap:8px}',
521
526
  '.mem-scope-check{display:inline-flex;align-items:center;justify-content:center;width:18px;height:18px;padding:0;border:none;background:transparent;flex:none;cursor:pointer}',
522
- '.mem-scope-check .box{display:flex;align-items:center;justify-content:center;width:16px;height:16px;border:1.5px solid var(--dsw-alias-border-l2,var(--dsw-alias-border-l1));border-radius:5px;background:transparent;color:var(--dsw-alias-label-on-brand,#fff);transition:background .12s ease,border-color .12s ease}',
523
- '.mem-scope-check.on .box{background:var(--dsw-alias-brand-primary);border-color:var(--dsw-alias-brand-primary)}',
527
+ '.mem-scope-check .box{display:flex;align-items:center;justify-content:center;width:16px;height:16px;border:1.5px solid color-mix(in srgb,var(--dsw-alias-label-secondary) 52%,var(--dsw-alias-border-l1));border-radius:5px;background:color-mix(in srgb,var(--dsw-alias-label-primary) 5%,transparent);color:var(--dsw-alias-label-primary-foreground);transition:background .12s ease,border-color .12s ease}',
528
+ '.mem-scope-check.on .box{background:var(--dsw-alias-state-business-primary);border-color:var(--dsw-alias-state-business-primary);color:var(--dsw-alias-label-primary-foreground)}',
524
529
  '.mem-scope-check:focus-visible{outline:1px solid var(--dsw-focus-ring-color,var(--dsw-alias-state-business-primary));outline-offset:1px}',
525
530
  '.mem-scope-label{flex:1;min-width:0;padding:0;border:none;background:transparent;color:var(--dsw-alias-label-primary);font-size:12.5px;text-align:left;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;cursor:pointer}',
526
531
  '.mem-scope-label:hover{color:var(--dsw-alias-brand-primary);border:none}',
@@ -529,9 +534,10 @@ window.__ModuleLoader__.load({
529
534
  '.mem-scope-foot .spacer{flex:1}',
530
535
  '.mem-scope-reset{padding:6px 13px;border:1px solid var(--dsw-alias-border-l1);border-radius:9px;background:transparent;color:var(--dsw-alias-label-secondary);font-size:12px;cursor:pointer;transition:border-color .12s ease,color .12s ease}',
531
536
  '.mem-scope-reset:hover:not(:disabled){border-color:color-mix(in srgb,var(--dsw-alias-brand-primary) 55%,var(--dsw-alias-border-l1));color:var(--dsw-alias-brand-primary)}',
532
- '.mem-scope-save{padding:6px 16px;border:1px solid var(--dsw-alias-brand-primary);border-radius:9px;background:var(--dsw-alias-brand-primary);color:var(--dsw-alias-label-on-brand,#fff);font-size:12px;font-weight:600;cursor:pointer;box-shadow:0 2px 8px color-mix(in srgb,var(--dsw-alias-brand-primary) 24%,transparent);transition:filter .12s ease}',
533
- '.mem-scope-save:hover:not(:disabled){filter:brightness(1.06)}',
537
+ '.mem-scope-save{padding:6px 16px;border:1px solid var(--dsw-alias-state-business-primary);border-radius:9px;background:var(--dsw-alias-state-business-primary);color:var(--dsw-alias-label-primary-foreground);font-size:12px;font-weight:600;cursor:pointer;box-shadow:0 2px 8px color-mix(in srgb,var(--dsw-alias-state-business-primary) 26%,transparent);transition:filter .12s ease}',
538
+ '.mem-scope-save:hover:not(:disabled){filter:brightness(1.06);color:var(--dsw-alias-label-primary-foreground);border-color:var(--dsw-alias-state-business-primary)}',
534
539
  '.mem-scope-reset:disabled,.mem-scope-save:disabled{opacity:.5;cursor:default;filter:none}',
540
+ '.mem-scope-save:disabled{color:var(--dsw-alias-label-primary-foreground)}',
535
541
  '.mem-scope-err{padding:5px 8px;border-radius:8px;background:color-mix(in srgb,var(--dsw-alias-state-error-primary,#d33) 10%,transparent);color:var(--dsw-alias-state-error-primary,#d33);font-size:12px;line-height:1.5}',
536
542
  // 范围外访问审批浮层(全局 fixed;根节点带 .memp 以复用审计 hover 浮窗样式)
537
543
  '.mem-approval{position:fixed;left:50%;bottom:18px;transform:translateX(-50%);z-index:90;width:min(520px,calc(100vw - 24px));max-height:min(70vh,620px);display:flex;flex-direction:column;pointer-events:none;padding:0;font-size:13px;color:var(--dsw-alias-label-primary)}',
@@ -4654,17 +4660,24 @@ window.__ModuleLoader__.load({
4654
4660
  const levelMeta = [
4655
4661
  { value: 'absolute', label: '绝对限制', hint: '范围外查不到' },
4656
4662
  { value: 'normal', label: '普通限制', hint: '范围外需审批' },
4657
- { value: 'none', label: '无限制', hint: '不限制读取' },
4663
+ { value: 'none', label: '无限制', hint: '不限制读写' },
4658
4664
  ]
4665
+ // 按钮上的边框样式来自**生效中**的限制等级:没有显式覆盖时是默认的普通限制。
4666
+ const buttonLevel = effectiveConfig && (effectiveConfig.level === 'absolute' || effectiveConfig.level === 'none')
4667
+ ? effectiveConfig.level
4668
+ : 'normal'
4669
+ const buttonLevelLabel = (levelMeta.find((item) => item.value === buttonLevel) ?? levelMeta[1]).label
4670
+ const sourceText = data && data.source === 'inherited'
4671
+ ? '继承自父会话'
4672
+ : hasOverride ? '本会话已设置' : '本会话使用默认'
4673
+ const scopeCountText = `${effectiveCount} 个作用域`
4659
4674
 
4660
4675
  return h('span', { className: 'mem-scope-wrap', ref: wrapRef },
4661
4676
  h('button', {
4662
4677
  type: 'button',
4663
- className: `mem-scope-btn${hasOverride ? ' on' : ''}`,
4664
- title: hasOverride
4665
- ? `本会话已设置记忆范围:${effectiveCount} 个作用域`
4666
- : `本会话使用默认记忆范围:${effectiveCount} 个作用域`,
4667
- 'aria-label': `记忆范围 ${effectiveCount}`,
4678
+ className: `mem-scope-btn is-${buttonLevel}`,
4679
+ title: `${sourceText}记忆范围:${scopeCountText} · ${buttonLevelLabel}`,
4680
+ 'aria-label': `${sourceText}记忆范围,${scopeCountText},${buttonLevelLabel}`,
4668
4681
  'aria-expanded': open,
4669
4682
  onMouseDown: (event) => { try { event.preventDefault() } catch { /* keepFocus */ } },
4670
4683
  onClick: toggle,
@@ -4679,7 +4692,7 @@ window.__ModuleLoader__.load({
4679
4692
  h('span', { className: 'mem-scope-count' }, `已选 ${selectedCount}`),
4680
4693
  ),
4681
4694
  h('div', { className: 'hint' },
4682
- 'Agent 默认只能检索和读取勾选的作用域;限制等级决定范围外怎么处理。'),
4695
+ 'Agent 只能检索、读取、写入和删除勾选的作用域;限制等级决定范围外怎么处理。'),
4683
4696
  data && data.inherited
4684
4697
  ? h('div', { className: 'hint' }, '当前继承自父会话;保存后在本会话独立生效。')
4685
4698
  : null,
@@ -4876,17 +4889,26 @@ window.__ModuleLoader__.load({
4876
4889
 
4877
4890
  if (pending === null) return null
4878
4891
 
4892
+ // 0.20.0:写/删也会触发审批,文案按 action 走。
4893
+ const action = pending.action === 'write' || pending.action === 'delete' ? pending.action : 'read'
4894
+ const actionLabel = action === 'write' ? '写入' : action === 'delete' ? '删除' : '读取'
4895
+ const actionHint = action === 'write'
4896
+ ? 'Agent 想把一条记忆写入可见域外的作用域。允许一次只对本次调用生效;拒绝则不写入。'
4897
+ : action === 'delete'
4898
+ ? 'Agent 想删除可见域外的记忆。允许一次只对本次调用生效;拒绝则不删除。'
4899
+ : '以下记忆不在本会话的可见域内。允许一次只对本次调用生效;拒绝则工具拿不到这些内容。'
4900
+
4879
4901
  return h('div', { className: 'memp mem-approval' },
4880
4902
  h('div', { className: 'mem-approval-card', role: 'dialog', 'aria-label': '记忆访问审批' },
4881
4903
  h('div', { className: 'mem-approval-head' },
4882
4904
  h('span', { className: 'mem-approval-dot' }),
4883
- h('b', null, '记忆访问审批'),
4905
+ h('b', null, `记忆${actionLabel}审批`),
4884
4906
  h('span', { className: 'muted' }, pending.tool || 'memory'),
4885
4907
  h('span', { className: 'spacer' }),
4886
4908
  approvals.length > 1 ? h('span', { className: 'muted' }, `还有 ${approvals.length - 1} 个待审批`) : null,
4887
4909
  ),
4888
4910
  h('div', { className: 'mem-approval-query' }, `Agent 查询:${pending.query || '(未提供)'}`),
4889
- h('div', { className: 'hint' }, '以下记忆不在本会话的可见域内。允许一次只对本次调用生效,拒绝则工具拿不到这些内容。'),
4911
+ h('div', { className: 'hint' }, actionHint),
4890
4912
  h('div', { className: 'mem-approval-list' },
4891
4913
  pending.items.map((item) => h('div', { className: 'mem-approval-item', key: item.id },
4892
4914
  h('div', { className: 'mem-approval-row' },
@@ -123,9 +123,9 @@ const NUDGE_TEXT =
123
123
 
124
124
 
125
125
  const VISIBILITY_LEVEL_TEXT = {
126
- absolute: '绝对限制:可见域外的记忆一律查不到,即使工具内部命中也不会返回。',
127
- normal: '普通限制:可见域外的记忆命中时会向用户发起一次审批;用户拒绝或超时则不返回。',
128
- none: '无限制:可以读取所有作用域与类型(当前选择仅作为下次切换的偏好保留)。',
126
+ absolute: '绝对限制:可见域外的记忆一律查不到,即使工具内部命中也不会返回;范围外也写不进去。',
127
+ normal: '普通限制:可见域外的记忆命中时会向用户发起一次审批;用户拒绝或超时则不返回。写入 / 删除范围外同样需要审批。',
128
+ none: '无限制:可以读写所有作用域(当前选择仅作为下次切换的偏好保留)。',
129
129
  }
130
130
 
131
131
  /**
@@ -134,7 +134,9 @@ const VISIBILITY_LEVEL_TEXT = {
134
134
  */
135
135
  export function renderVisibilityNotice(config ) {
136
136
  if (config === null) {
137
- return '【记忆可见范围已恢复默认】本会话不再有显式可见域;memory_search / memory_get / memory_list 回到"会话 + 项目 + global"的默认读取集合。'
137
+ return '【记忆可见范围已恢复默认】'
138
+ + '本会话不再有显式可见域,改回默认设置:当前会话 + 当前项目 + global 三个作用域,限制等级 = 普通限制'
139
+ + '(范围外命中会先向用户审批;写入 / 删除范围外同样需要审批)。'
138
140
  }
139
141
  const scopes = config.scopes.length > 0
140
142
  ? config.scopes.map((rule) => (rule.kinds !== undefined && rule.kinds.length > 0
package/lib/panel.js CHANGED
@@ -487,12 +487,18 @@ function visibilityPayload(ctx, memory, sessionId) {
487
487
  const own = typeof memory.sessionVisibility === 'function' ? memory.sessionVisibility(sessionId) : null
488
488
  let effective = null
489
489
  let inherited = false
490
+ // 0.20.0 起 provider 永远给一份生效策略(没有显式覆盖时是默认策略)。
491
+ // source 告诉面板这份策略是"自己的 / 继承的 / 默认的"。
492
+ let source = own === null ? 'default' : 'explicit'
490
493
  try {
491
494
  if (typeof memory.visibilityPolicy === 'function') {
492
495
  const policy = memory.visibilityPolicy(agentLike)
493
496
  if (policy !== undefined && policy !== null) {
494
497
  effective = policy
495
- inherited = own === null
498
+ source = policy.source === 'explicit' || policy.source === 'inherited' || policy.source === 'default'
499
+ ? policy.source
500
+ : (own === null ? 'default' : 'explicit')
501
+ inherited = source === 'inherited'
496
502
  }
497
503
  }
498
504
  } catch { /* 可见域是增强;拿不到就只返回自己的覆盖 */ }
@@ -533,6 +539,7 @@ function visibilityPayload(ctx, memory, sessionId) {
533
539
  override: own,
534
540
  effective,
535
541
  inherited,
542
+ source,
536
543
  defaults,
537
544
  scopes,
538
545
  }
@@ -243,11 +243,16 @@ export class CordisMemoryService extends Service {
243
243
  return this.impl.visibleScopes(agent)
244
244
  }
245
245
 
246
- /** 完整可见域(等级 + 每个 scope 的类型白名单)。 */
246
+ /** 完整可见域(等级 + 每个 scope 的类型白名单 + 来源)。0.20 起永远有值。 */
247
247
  visibilityPolicy(agent ) {
248
248
  return this.impl.visibilityPolicy(agent)
249
249
  }
250
250
 
251
+ /** 可见范围 = 可操作范围:写入/删除前用它判断一个 scope 是否可操作。 */
252
+ isScopeOperable(agent , scope ) {
253
+ return this.impl.isScopeOperable(agent, scope)
254
+ }
255
+
251
256
  /** 某个 scope 下允许的记忆类型(undefined = 不限制)。 */
252
257
  visibleKinds(agent , scope ) {
253
258
  return this.impl.visibleKinds(agent, scope)
@@ -502,12 +502,26 @@ export function resolveConfig(config = {}) {
502
502
 
503
503
 
504
504
 
505
- /** 生效中的可见域(已剔除被 scope 开关禁用的项)。 */
505
+ /**
506
+ * 生效中的可见域(已剔除被 scope 开关禁用的项)。
507
+ *
508
+ * 0.20.0 起**永远有值**:没有显式覆盖时返回默认策略 ——
509
+ * 「当前会话 + 当前项目 + global」+ 普通限制。`source` 说明这份策略从哪来:
510
+ * - `explicit` = 本会话自己保存过可见范围;
511
+ * - `inherited` = 沿 parentSession 链继承来的显式范围;
512
+ * - `default` = 没有显式覆盖,用的默认策略。
513
+ * 工具层用 `source === 'default'` 区分"默认普通限制"(普通检索不主动把范围外
514
+ * 也搜一遍)与"用户显式设的普通限制"。
515
+ */
506
516
 
507
517
 
508
518
 
519
+
509
520
 
510
521
 
522
+ /** 范围外访问的动作(读取 / 写入 / 删除);审批浮层按它换文案。 */
523
+
524
+
511
525
  /** 一条"范围外"命中:给审批浮层展示的完整快照(不落盘,进程内存)。 */
512
526
 
513
527
 
@@ -525,6 +539,8 @@ export function resolveConfig(config = {}) {
525
539
 
526
540
 
527
541
 
542
+                         
543
+
528
544
                     
529
545
 
530
546
 
@@ -533,7 +549,7 @@ export function resolveConfig(config = {}) {
533
549
 
534
550
 
535
551
 
536
-
552
+
537
553
 
538
554
 
539
555
 
@@ -542,6 +558,12 @@ const VISIBILITY_APPROVAL_TTL_MS = 5 * 60_000
542
558
  /** 审批浮层一次最多展示多少条范围外命中(工具侧仍会返回全部允许的命中)。 */
543
559
  const VISIBILITY_APPROVAL_MAX_ITEMS = 20
544
560
 
561
+ /**
562
+ * 没有显式覆盖时的默认限制等级(0.20.0 起)。
563
+ * 默认范围 = 当前会话 + 当前项目 + global;范围外命中走一次审批。
564
+ */
565
+ export const DEFAULT_VISIBILITY_LEVEL = 'normal'
566
+
545
567
  export class LocalMemoryService {
546
568
  cfg
547
569
  store
@@ -1389,14 +1411,18 @@ export class LocalMemoryService {
1389
1411
  *
1390
1412
  * 起点用**当前会话自己的 id**(不是 resolveCurrentScopes 映射后的父会话):
1391
1413
  * 子 Agent 自己也可以有一份覆盖;没有时才沿链继承父会话 / 根会话。
1414
+ * `inherited` = 找到的那份覆盖不属于当前会话自己。
1392
1415
  */
1393
- visibilityForSession(sessionId ) {
1394
- let id = sessionId ?? ''
1416
+ resolveVisibility(
1417
+ sessionId ,
1418
+ ) {
1419
+ const own = sessionId ?? ''
1420
+ let id = own
1395
1421
  const seen = new Set ()
1396
1422
  while (id !== '' && !seen.has(id)) {
1397
1423
  seen.add(id)
1398
1424
  const found = this.visibility.get(id)
1399
- if (found !== undefined) return found
1425
+ if (found !== undefined) return { config: found, inherited: id !== own }
1400
1426
  let parent
1401
1427
  try {
1402
1428
  const session = this.sessionLookup?.(id)
@@ -1420,42 +1446,66 @@ export class LocalMemoryService {
1420
1446
  }
1421
1447
  }
1422
1448
 
1449
+ /** 没有显式覆盖时的默认可见域范围(当前会话 + 当前项目 + global,各自开关生效)。 */
1450
+ defaultReadScopes(agent ) {
1451
+ const refs = this.scopeRefs(agent)
1452
+ const out = []
1453
+ const push = (scope , enabled ) => {
1454
+ if (scope === undefined || !enabled || out.includes(scope)) return
1455
+ out.push(scope)
1456
+ }
1457
+ push(refs.session, this.cfg.sessionEnabled)
1458
+ push(refs.project, this.cfg.projectEnabled)
1459
+ push('global', this.cfg.globalEnabled)
1460
+ return out
1461
+ }
1462
+
1423
1463
  /**
1424
- * 显式「记忆可见域」的完整策略(含等级与每个 scope 的类型白名单)。
1425
- * undefined = 没有覆盖;level='none' 时 scopes 仍保留(供面板/下次切换),
1426
- * 但**不参与**读取限制。
1464
+ * 生效的「记忆可见域」。**永远有值**(0.20.0 起):没有显式覆盖时返回默认策略。
1465
+ * level='none' 时 scopes 仍保留(供面板/下次切换),但**不参与**读写限制。
1427
1466
  */
1428
- visibilityPolicy(agent ) {
1429
- const explicit = this.visibilityForSession(this.rawSessionIdOf(agent))
1430
- if (explicit === undefined) return undefined
1431
- return { level: explicit.level, scopes: this.filterEnabledRules(explicit.scopes) }
1467
+ visibilityPolicy(agent ) {
1468
+ const resolved = this.resolveVisibility(this.rawSessionIdOf(agent))
1469
+ if (resolved === undefined) {
1470
+ return {
1471
+ level: DEFAULT_VISIBILITY_LEVEL,
1472
+ scopes: this.defaultReadScopes(agent).map((scope) => ({ scope })),
1473
+ source: 'default',
1474
+ }
1475
+ }
1476
+ return {
1477
+ level: resolved.config.level,
1478
+ scopes: this.filterEnabledRules(resolved.config.scopes),
1479
+ source: resolved.inherited ? 'inherited' : 'explicit',
1480
+ }
1432
1481
  }
1433
1482
 
1434
1483
  /**
1435
- * 显式「记忆可见范围」的 scope 键列表。
1436
- * undefined = 不限制(没有覆盖,或等级为 none);
1484
+ * **显式**「可见范围」的 scope 键列表(不含默认策略,注入半边用它判断是否被
1485
+ * 显式白名单收窄,并决定要不要把 inject.extraScopes 关掉)。
1486
+ * undefined = 本会话没有显式覆盖(或等级为 none);
1437
1487
  * [] = 显式设置了范围但全部被 scope 开关禁用,调用方必须按空处理。
1438
1488
  */
1439
1489
  visibleScopes(agent ) {
1440
- const policy = this.visibilityPolicy(agent)
1441
- if (policy === undefined || policy.level === 'none') return undefined
1442
- return policy.scopes.map((rule) => this.canonicalScope(rule.scope))
1490
+ const resolved = this.resolveVisibility(this.rawSessionIdOf(agent))
1491
+ if (resolved === undefined || resolved.config.level === 'none') return undefined
1492
+ return this.filterEnabledRules(resolved.config.scopes).map((rule) => this.canonicalScope(rule.scope))
1443
1493
  }
1444
1494
 
1445
1495
  /** 某个 scope 下允许的记忆类型;undefined = 不限制(可见且没有类型白名单)。 */
1446
1496
  visibleKinds(agent , scope ) {
1447
1497
  const policy = this.visibilityPolicy(agent)
1448
- if (policy === undefined || policy.level === 'none') return undefined
1498
+ if (policy.level === 'none') return undefined
1449
1499
  const key = this.canonicalScope(scope)
1450
1500
  const rule = policy.scopes.find((item) => this.canonicalScope(item.scope) === key)
1451
1501
  if (rule === undefined) return []
1452
1502
  return rule.kinds !== undefined && rule.kinds.length > 0 ? [...rule.kinds] : undefined
1453
1503
  }
1454
1504
 
1455
- /** 一条记录(scope + kind)是否落在当前可见域内;等级 none / 无覆盖时恒为 true。 */
1505
+ /** 一条记录(scope + kind)是否落在当前可见域内;等级 none 时恒为 true。 */
1456
1506
  isRecordVisible(agent , scope , kind ) {
1457
1507
  const policy = this.visibilityPolicy(agent)
1458
- if (policy === undefined || policy.level === 'none') return true
1508
+ if (policy.level === 'none') return true
1459
1509
  const key = this.canonicalScope(scope)
1460
1510
  const rule = policy.scopes.find((item) => this.canonicalScope(item.scope) === key)
1461
1511
  if (rule === undefined) return false
@@ -1463,13 +1513,24 @@ export class LocalMemoryService {
1463
1513
  return rule.kinds.includes(kind)
1464
1514
  }
1465
1515
 
1516
+ /**
1517
+ * 一个作用域是否可读**且可写**(0.20.0 起「可见范围 = 可操作范围」,
1518
+ * save / forget 与读取共用这一份口径)。等级 none 时恒为 true。
1519
+ */
1520
+ isScopeOperable(agent , scope ) {
1521
+ const policy = this.visibilityPolicy(agent)
1522
+ if (policy.level === 'none') return true
1523
+ const key = this.canonicalScope(scope)
1524
+ return policy.scopes.some((item) => this.canonicalScope(item.scope) === key)
1525
+ }
1526
+
1466
1527
  /**
1467
1528
  * 批量过滤用的可见域判定(策略只解析一次,避免每条记录都走一遍 parentSession 链)。
1468
1529
  * undefined = 不限制。
1469
1530
  */
1470
1531
  visibilityFilterFor(agent ) {
1471
1532
  const policy = this.visibilityPolicy(agent)
1472
- if (policy === undefined || policy.level === 'none') return undefined
1533
+ if (policy.level === 'none') return undefined
1473
1534
  const byScope = new Map ()
1474
1535
  for (const rule of policy.scopes) {
1475
1536
  byScope.set(this.canonicalScope(rule.scope), rule.kinds !== undefined && rule.kinds.length > 0 ? rule.kinds : undefined)
@@ -1570,11 +1631,22 @@ export class LocalMemoryService {
1570
1631
  return out
1571
1632
  }
1572
1633
 
1573
- /** 普通限制:范围外命中时创建一条待审批,等待面板回答(超时按拒绝)。 */
1634
+ /**
1635
+ * 普通限制:范围外命中时创建一条待审批,等待面板回答。
1636
+ * 超时返回 `'timeout'`(和用户主动拒绝区分开,工具层要把真实原因告诉模型);
1637
+ * 调用被中止按拒绝处理。
1638
+ */
1574
1639
  requestOutOfScope(
1575
1640
  agent ,
1576
- input ,
1577
- ) {
1641
+ input
1642
+
1643
+                     
1644
+
1645
+
1646
+
1647
+
1648
+ ,
1649
+ ) {
1578
1650
  if (input.items.length === 0) return Promise.resolve('allowed-once')
1579
1651
  if (input.signal?.aborted) return Promise.resolve('rejected')
1580
1652
  const sessionId = this.rawSessionIdOf(agent) ?? ''
@@ -1584,7 +1656,7 @@ export class LocalMemoryService {
1584
1656
  return new Promise((resolve) => {
1585
1657
  let timer
1586
1658
  const onAbort = () => finish('rejected')
1587
- const finish = (outcome ) => {
1659
+ const finish = (outcome ) => {
1588
1660
  const pending = this.pendingApprovals.get(id)
1589
1661
  if (pending === undefined) return
1590
1662
  this.pendingApprovals.delete(id)
@@ -1592,12 +1664,13 @@ export class LocalMemoryService {
1592
1664
  try { input.signal?.removeEventListener('abort', onAbort) } catch { /* 已卸载 */ }
1593
1665
  pending.resolve(outcome)
1594
1666
  }
1595
- timer = setTimeout(() => finish('rejected'), VISIBILITY_APPROVAL_TTL_MS)
1667
+ timer = setTimeout(() => finish('timeout'), VISIBILITY_APPROVAL_TTL_MS)
1596
1668
  timer.unref?.()
1597
1669
  this.pendingApprovals.set(id, {
1598
1670
  id,
1599
1671
  sessionId,
1600
1672
  tool: input.tool,
1673
+ action: input.action ?? 'read',
1601
1674
  query: input.query,
1602
1675
  items: input.items.slice(0, VISIBILITY_APPROVAL_MAX_ITEMS).map((item) => ({
1603
1676
  ...item,
@@ -1621,6 +1694,7 @@ export class LocalMemoryService {
1621
1694
  id: pending.id,
1622
1695
  sessionId: pending.sessionId,
1623
1696
  tool: pending.tool,
1697
+ action: pending.action,
1624
1698
  query: pending.query,
1625
1699
  // 轮询载荷保持轻量:正文截到 1200 字,悬浮需要全文时面板再按 id 取一次。
1626
1700
  items: pending.items.map((item) => ({
@@ -1648,29 +1722,45 @@ export class LocalMemoryService {
1648
1722
  /**
1649
1723
  * 无显式 scope 时的**读取**合并集合:当前会话 + 当前项目 + global(各自开关生效、按 key 去重)。
1650
1724
  * 工具 / 注入都用它。会话设置了「可见范围」时以覆盖为准(不再并入默认集合)。
1725
+ * 没有显式覆盖时返回默认三路集合 —— 与默认可见域(`visibilityPolicy().source==='default'`)
1726
+ * 完全相同,所以"默认并没有限制"这句话在 0.20 之后不再成立。
1651
1727
  */
1652
1728
  resolveReadScopes(agent ) {
1653
1729
  const explicit = this.visibleScopes(agent)
1654
1730
  // level='none' 时 visibleScopes 返回 undefined:不限制读取,继续用默认三路集合。
1655
1731
  if (explicit !== undefined) return explicit
1656
- const refs = this.scopeRefs(agent)
1657
- const out = []
1658
- const push = (scope , enabled ) => {
1659
- if (scope === undefined || !enabled || out.includes(scope)) return
1660
- out.push(scope)
1732
+ return this.defaultReadScopes(agent)
1733
+ }
1734
+
1735
+ /**
1736
+ * 写入/删除护栏(0.20.0):可见范围 = 可操作范围。
1737
+ *
1738
+ * - absolute:范围外一律拒绝,而且**不暴露**这是可见域限制(视为不存在);
1739
+ * - normal:没经过审批就拒绝(工具层会用 `requestOutOfScope` 先问一次,
1740
+ * 批准后带 `visibilityApproved` 再调进来);
1741
+ * - none:不限制。
1742
+ */
1743
+ assertOperable(agent , scope ) {
1744
+ if (this.isScopeOperable(agent, scope)) return
1745
+ const level = this.visibilityPolicy(agent).level
1746
+ if (level === 'absolute') {
1747
+ throw memoryError('SCOPE_NOT_WRITABLE', `作用域 ${scope} 不存在或不可写`)
1661
1748
  }
1662
- push(refs.session, this.cfg.sessionEnabled)
1663
- push(refs.project, this.cfg.projectEnabled)
1664
- push('global', this.cfg.globalEnabled)
1665
- return out
1749
+ throw memoryError('VISIBILITY_APPROVAL_REQUIRED', `作用域 ${scope} 不在本会话的可操作范围内,需要用户审批`)
1666
1750
  }
1667
1751
 
1668
1752
  async save(input ) {
1669
1753
  // 省略 scope 时按当前会话落点 —— 会话上下文必须**从调用方带进来**
1670
1754
  // (工具 handler 拿得到 exec.agent,provider 自己看不到)。
1671
- const requestedScope = input.scope ?? this.resolveWriteScope((input ).agent)
1755
+ const saveAgent = (input ).agent
1756
+ const requestedScope = input.scope ?? this.resolveWriteScope(saveAgent)
1672
1757
  const scope = this.canonicalScope(requestedScope)
1673
1758
  this.assertScopeAllowed(scope)
1759
+ // 写入护栏:可见范围 = 可操作范围。工具层在普通限制下会先审批,批准后带
1760
+ // `visibilityApproved` 再来;面板写入不带 agent,不受会话可见域约束(用户本人操作)。
1761
+ if (saveAgent !== undefined && (input ).visibilityApproved !== true) {
1762
+ this.assertOperable(saveAgent, scope)
1763
+ }
1674
1764
  // 0.7.0:项目作用域可以带一个显示名(别名)。同一路径同名幂等,不同路径同名拒绝。
1675
1765
  const requestedName = (input ).name
1676
1766
  if (requestedName !== undefined && requestedName !== null && String(requestedName).trim() !== '') {
@@ -2072,11 +2162,28 @@ export class LocalMemoryService {
2072
2162
  return undefined
2073
2163
  }
2074
2164
 
2075
- async forget(input ) {
2165
+ /**
2166
+ * 删除记录。`agent` + 未审批时按可见域护栏处理(0.20.0):
2167
+ * 范围外一律**当作不存在** —— id 找不到、query 没有匹配,不泄露"被限制";
2168
+ * 普通限制下工具层会先审批,批准后带 `visibilityApproved` 再调进来。
2169
+ */
2170
+ async forget(input
2171
+
2172
+
2173
+
2174
+
2175
+
2176
+
2177
+ ) {
2178
+ const guardAgent = input.agent
2179
+ const approved = input.visibilityApproved === true
2180
+ const operable = (scope ) =>
2181
+ guardAgent === undefined || approved || this.isScopeOperable(guardAgent, scope)
2076
2182
  const ids = []
2077
2183
  if (input.id) {
2078
2184
  // 按 id 删除天然跨 scope:调用方给的是精确 id,不存在误删别的 scope 的风险。
2079
2185
  for (const s of this.store.allScopes()) {
2186
+ if (!operable(s.scope)) continue
2080
2187
  if (s.remove(input.id)) ids.push(input.id)
2081
2188
  }
2082
2189
  if (ids.length === 0) throw memoryError('RECORD_NOT_FOUND', `id ${input.id} not found`)
@@ -2092,6 +2199,7 @@ export class LocalMemoryService {
2092
2199
  for (const scope of targets) {
2093
2200
  if (seen.has(scope)) continue
2094
2201
  seen.add(scope)
2202
+ if (!operable(scope)) continue
2095
2203
  const store = this.store.peek(scope) // 读/删路径不创建
2096
2204
  if (!store) continue
2097
2205
  const hit = this.store.findIdsByQuery(scope, input.query)
@@ -19,7 +19,7 @@ import {
19
19
 
20
20
 
21
21
  } from './index.js'
22
- import { renderGetResult, renderSearchResult } from './render.js'
22
+ import { renderGetResult, renderSearchResult, renderWithheldNote } from './render.js'
23
23
  import { resolveCurrentScopes, scopeKind, } from '../provider/scope.js'
24
24
 
25
25
  export const name = 'dsh-tool-memory'
@@ -116,7 +116,8 @@ export function apply(ctx , config = {}) {
116
116
  ? '该作用域还没有记忆。'
117
117
  : value.records.map((r) => `(${renderScope(r.scope, agent)}/${r.kind}) ${r.content}`).join('\n')
118
118
  const summary = scopeSummary(value, agent)
119
- return summary ? `${body}\n${summary}` : body
119
+ const note = renderWithheldNote(value.withheld)
120
+ return [body, summary, note].filter((part) => part !== '').join('\n')
120
121
  })
121
122
 
122
123
  register(tools.memory_get, (value, _args, exec) => {
@@ -40,16 +40,28 @@ import { canonicalWorkspacePath, normalizeScopeInput, resolveScopeRef } from '..
40
40
  /** 范围外访问的处理方式(与 provider 的会话可见域一致)。 */
41
41
 
42
42
 
43
+ /** 一次范围外审批的结局:允许一次 / 用户拒绝 / 超时未答 / 当前版本不支持审批。 */
44
+
45
+
46
+ /** 被可见域挡住、没有返回给模型的原因(absolute 模式不会出现:一律视为不存在)。 */
47
+
48
+
43
49
 
44
50
 
45
51
                  
46
52
 
47
53
 
48
54
 
49
- /** provider 解析出的生效可见域;undefined = 没有覆盖(不限制)。 */
55
+ /**
56
+ * provider 解析出的生效可见域。0.20.0 起 provider 永远返回一份策略:
57
+ * 没有显式覆盖时是「会话 + 项目 + global」+ 普通限制,`source === 'default'`。
58
+ * 老 provider 仍可能返回 undefined(视为不限制)。
59
+ */
50
60
 
51
61
 
52
62
 
63
+                         
64
+
53
65
 
54
66
 
55
67
  /** 一条范围外命中,交给审批浮层展示。 */
@@ -81,10 +93,18 @@ import { canonicalWorkspacePath, normalizeScopeInput, resolveScopeRef } from '..
81
93
           
82
94
 
83
95
 
84
-                         
96
+                            
85
97
 
86
-                             
87
-
98
+
99
+                               
100
+                
101
+
102
+
103
+
104
+                             
105
+                                 
106
+
107
+
88
108
                            
89
109
 
90
110
                 
@@ -150,7 +170,8 @@ function projectKey(opts , service , agent
150
170
  }
151
171
 
152
172
  /**
153
- * 显式「可见范围」白名单;undefined = 没有覆盖(保持旧行为,不限制显式 scope)。
173
+ * 显式「可见范围」白名单;undefined = 本会话没有显式覆盖(注入半边用它判断
174
+ * 要不要关掉 extraScopes,工具层不用它做读限制 —— 那是 visibilityPolicy 的事)。
154
175
  * provider 方法抛错时按"没有覆盖"处理:可见范围是防越界,不应该让一个 provider
155
176
  * 内部错误把所有读取都锁死。
156
177
  */
@@ -162,18 +183,34 @@ function visibleScopeList(service , agent )
162
183
  return undefined
163
184
  }
164
185
 
165
- /** 完整可见域;老 provider / 解析失败时退化为 undefined(不限制)。 */
186
+ /**
187
+ * 完整可见域;老 provider / 解析失败时退化为 undefined(不限制)。
188
+ * 0.20 的 provider 永远返回策略:没有显式覆盖时是默认策略(source='default'),
189
+ * 默认范围 = 会话 + 项目 + global,等级 = normal。
190
+ */
166
191
  function visibilityPolicy(service , agent ) {
167
192
  try {
168
193
  const policy = service.visibilityPolicy?.(agent)
169
194
  if (policy !== undefined && policy !== null) {
170
195
  const level = policy.level === 'absolute' || policy.level === 'none' ? policy.level : 'normal'
171
- return { level, scopes: Array.isArray(policy.scopes) ? policy.scopes : [] }
196
+ const source = policy.source === 'explicit' || policy.source === 'inherited' || policy.source === 'default'
197
+ ? policy.source
198
+ : undefined
199
+ return {
200
+ level,
201
+ scopes: Array.isArray(policy.scopes) ? policy.scopes : [],
202
+ ...(source !== undefined ? { source } : {}),
203
+ }
172
204
  }
173
205
  } catch { /* 降级为不限制 */ }
174
206
  return undefined
175
207
  }
176
208
 
209
+ /** 是否"用户显式设过的策略"(默认策略不算):决定普通限制下要不要把范围外也搜一遍。 */
210
+ function explicitPolicy(policy ) {
211
+ return policy !== undefined && policy.source !== 'default'
212
+ }
213
+
177
214
  function scopeInPolicy(policy , scope ) {
178
215
  if (policy === undefined || policy.level === 'none') return true
179
216
  return policy.scopes.some((rule) => rule.scope === scope)
@@ -209,8 +246,10 @@ function recordsToApprovalItems(
209
246
  }
210
247
 
211
248
  /**
212
- * 普通限制:把范围外命中交给用户审批一次。
213
- * provider 不支持审批(旧版本)时按拒绝处理 —— 不能静默把范围外记忆放出去。
249
+ * 普通限制:把范围外访问交给用户审批一次。
250
+ * 结局必须可区分:允许一次 / 用户拒绝 / 超时 / 旧 provider 不支持审批。
251
+ * `agent` 省略 = 不审批(工具层在拿不到会话时退回 provider 的护栏)。
252
+ * 允许写/删时要带 `approvedItems` 之类的合成条目,浮层才显示得出来。
214
253
  */
215
254
  async function askOutOfScope(
216
255
  service ,
@@ -219,35 +258,58 @@ async function askOutOfScope(
219
258
  tool ,
220
259
  query ,
221
260
  records ,
261
+ action ,
222
262
  signal ,
223
- ) {
224
- if (records.length === 0) return true
225
- if (typeof service.requestOutOfScope !== 'function') return false
226
- if (signal?.aborted) return false
263
+ ) {
264
+ if (records.length === 0) return 'allowed-once'
265
+ if (typeof service.requestOutOfScope !== 'function') return 'unavailable'
266
+ if (signal?.aborted) return 'rejected'
227
267
  try {
228
268
  const outcome = await service.requestOutOfScope(agent, {
229
269
  tool,
270
+ action,
230
271
  query,
231
272
  items: recordsToApprovalItems(policy, records),
232
273
  ...(signal !== undefined ? { signal } : {}),
233
274
  })
234
- return outcome === 'allowed-once'
275
+ if (outcome === 'allowed-once' || outcome === 'timeout' || outcome === 'unavailable') return outcome
276
+ return 'rejected'
235
277
  } catch {
236
- return false
278
+ return 'unavailable'
237
279
  }
238
280
  }
239
281
 
240
- /** 显式询问一个不在可见范围内的 scope 时给出明确错误,而不是返回空结果。 */
241
- function assertScopeVisible(service , agent , scope ) {
242
- const policy = visibilityPolicy(service, agent)
243
- if (policy === undefined || policy.level === 'none' || scopeInPolicy(policy, scope)) return
244
- const visible = policy.scopes.map((rule) => rule.scope)
245
- throw new MemoryToolError(
246
- 'SCOPE_NOT_VISIBLE',
247
- `当前会话的「记忆可见域」不包含 ${scope};只能读取: ${visible.length > 0 ? visible.join(', ') : '(无)'}`,
282
+ /** 审批没通过时给模型的真实原因(写/删路径直接抛这个错误)。 */
283
+ function visibilityError(outcome , action , scope ) {
284
+ const verb = action === 'write' ? '写入' : '删除'
285
+ if (outcome === 'rejected') {
286
+ return new MemoryToolError(
287
+ 'VISIBILITY_REJECTED',
288
+ `用户拒绝了本次${verb}请求(作用域 ${scope},当前限制等级:普通限制),没有执行。如需${verb},请让用户调整「记忆范围」后重试。`,
289
+ )
290
+ }
291
+ if (outcome === 'timeout') {
292
+ return new MemoryToolError(
293
+ 'VISIBILITY_TIMEOUT',
294
+ `等待用户审批超时(5 分钟没有答复),本次${verb}没有执行(作用域 ${scope},当前限制等级:普通限制)。`,
295
+ )
296
+ }
297
+ return new MemoryToolError(
298
+ 'VISIBILITY_UNAVAILABLE',
299
+ `当前环境无法就范围外访问发起审批,本次${verb}没有执行(作用域 ${scope})。`,
248
300
  )
249
301
  }
250
302
 
303
+ /** 写入/删除前判断一个 scope 是否可操作(可见范围 = 可操作范围)。 */
304
+ function scopeOperable(service , agent , policy , scope ) {
305
+ if (policy === undefined || policy.level === 'none') return true
306
+ try {
307
+ const verdict = service.isScopeOperable?.(agent, scope)
308
+ if (typeof verdict === 'boolean') return verdict
309
+ } catch { /* 退回本地判断 */ }
310
+ return scopeInPolicy(policy, scope)
311
+ }
312
+
251
313
  /** 规范里所有已知 scope(用来在普通限制下把范围外也搜一遍,看看有没有可审批的命中)。 */
252
314
  function allKnownScopes(service ) {
253
315
  try {
@@ -367,6 +429,7 @@ export function memorySaveTool(opts )
367
429
  if (args.importance !== undefined && (args.importance < 0 || args.importance > 1)) {
368
430
  throw new MemoryToolError('IMPORTANCE_RANGE', 'importance must be between 0 and 1')
369
431
  }
432
+ const content = args.content.trim()
370
433
  // 写路径:省略 scope → provider 按 tools.defaultScope(缺省 session,拿不到会话回退
371
434
  // project)。默认值的最终权威是 provider 的 `save` —— 省略时干脆不带 scope 字段,
372
435
  // 但要把会话上下文(exec.agent)带过去,否则它没法知道"当前会话"是谁。
@@ -395,13 +458,50 @@ export function memorySaveTool(opts )
395
458
  explicit = resolved
396
459
  }
397
460
 
461
+ // 写入护栏(0.20.0):可见范围 = 可操作范围。范围外写入:
462
+ // - absolute → 按"作用域不存在/不可写"处理,不暴露可见域配置;
463
+ // - normal → 先向用户审批一次,拒绝/超时把真实原因抛给模型;
464
+ // - none → 不限制。
465
+ // 拿不到会话(老宿主 / 无 exec)时不判断:没有会话就没有"本会话的可见域"。
466
+ const policy = agent === undefined ? undefined : visibilityPolicy(service, agent)
467
+ const level = policy?.level ?? 'none'
468
+ const target = explicit ?? (typeof service.resolveWriteScope === 'function' ? service.resolveWriteScope(agent) : undefined)
469
+ let approved = false
470
+ if (level !== 'none' && target !== undefined && !scopeOperable(service, agent, policy, target)) {
471
+ if (level === 'absolute') {
472
+ throw new MemoryToolError('SCOPE_NOT_WRITABLE', `作用域 ${target} 不存在或不可写`)
473
+ }
474
+ const draft = {
475
+ id: 'new-record',
476
+ scope: target,
477
+ kind: args.kind ?? 'note',
478
+ content: content,
479
+ tags: Array.isArray(args.tags) ? args.tags : [],
480
+ importance: typeof args.importance === 'number' ? args.importance : 0,
481
+ updatedAt: Date.now(),
482
+ }
483
+ const outcome = await askOutOfScope(
484
+ service,
485
+ agent,
486
+ policy,
487
+ 'memory_save',
488
+ summarize(content, 80),
489
+ [draft],
490
+ 'write',
491
+ (exec )?.signal,
492
+ )
493
+ if (outcome !== 'allowed-once') throw visibilityError(outcome, 'write', target)
494
+ approved = true
495
+ }
496
+
398
497
  try {
399
498
  const record = await service.save({
400
499
  ...(explicit !== undefined ? { scope: explicit } : {}),
401
500
  ...(alias !== undefined ? { name: alias } : {}),
402
501
  ...(agent !== undefined ? { agent } : {}),
502
+ ...(approved ? { visibilityApproved: true } : {}),
403
503
  kind: args.kind ?? 'note',
404
- content: args.content.trim(),
504
+ content: content,
405
505
  ...(args.tags ? { tags: args.tags } : {}),
406
506
  ...(args.importance !== undefined ? { importance: args.importance } : {}),
407
507
  ...(args.supersedes ? { supersedes: args.supersedes } : {}),
@@ -457,8 +557,11 @@ export function summarize(content , chars = DEFAULT_SUMMARY_CHARS
457
557
 
458
558
 
459
559
 
460
-                            
461
-
560
+
561
+                                   
562
+                         
563
+
564
+
462
565
 
463
566
 
464
567
  export function memorySearchTool(opts ) {
@@ -480,10 +583,12 @@ export function memorySearchTool(opts )
480
583
  const resolved = resolveScope(opts, service, exec, args.scope, 'read')
481
584
  const agent = agentOf(exec)
482
585
  const policy = visibilityPolicy(service, agent)
483
- const level = policy?.level
484
- const visible = policy !== undefined && level !== 'none'
485
- ? policy.scopes.map((rule) => rule.scope)
486
- : visibleScopeList(service, agent)
586
+ const level = policy?.level ?? 'none'
587
+ // level=none 时策略里的 scopes 只是偏好,不参与限制(等价于没有可见域)。
588
+ const visible = policy !== undefined && policy.level !== 'none' ? policy.scopes.map((rule) => rule.scope) : undefined
589
+ // 只有"用户显式设过"的普通限制才把磁盘上其它 scope 也搜一遍(才有范围外命中
590
+ // 可以审批)。默认策略下普通检索就只搜默认的三路集合,避免每次都弹审批。
591
+ const expand = level === 'normal' && explicitPolicy(policy)
487
592
  let scopes
488
593
  if (resolved.all) {
489
594
  if (visible !== undefined) {
@@ -496,9 +601,7 @@ export function memorySearchTool(opts )
496
601
  } else if (resolved.scope === undefined) {
497
602
  // 省略 scope:三路合并(会话 + 项目 + global),或显式可见范围。
498
603
  const merged = readScopes(opts, service, agent)
499
- scopes = level === 'normal' ? [...new Set([...merged, ...allKnownScopes(service)])] : merged
500
- } else if (level === 'absolute') {
501
- assertScopeVisible(service, agent, resolved.scope)
604
+ scopes = expand ? [...new Set([...merged, ...allKnownScopes(service)])] : merged
502
605
  }
503
606
  const chars = resolveSummaryChars(args.summaryChars)
504
607
  try {
@@ -513,19 +616,22 @@ export function memorySearchTool(opts )
513
616
  })
514
617
  const inside = hits.filter((hit) => recordAllowed(policy, hit.record.scope, hit.record.kind))
515
618
  const outside = hits.filter((hit) => !recordAllowed(policy, hit.record.scope, hit.record.kind))
516
- let granted = false
619
+ // undefined = 没有范围外命中 / 绝对限制(不审批);只有普通限制会真的问一次。
620
+ let outcome
517
621
  if (outside.length > 0 && level === 'normal') {
518
- granted = await askOutOfScope(
622
+ outcome = await askOutOfScope(
519
623
  service,
520
624
  agent,
521
625
  policy,
522
626
  'memory_search',
523
627
  args.query,
524
628
  outside.map((hit) => hit.record),
629
+ 'read',
525
630
  (exec )?.signal,
526
631
  )
527
632
  }
528
- const selected = granted ? hits : inside
633
+ const allowed = outside.length === 0 || outcome === 'allowed-once'
634
+ const selected = allowed ? hits : inside
529
635
  const result = {
530
636
  records: selected.map((h) => ({
531
637
  id: h.record.id,
@@ -537,8 +643,9 @@ export function memorySearchTool(opts )
537
643
  summary: summarize(h.record.content, chars),
538
644
  })),
539
645
  }
540
- if (!granted && outside.length > 0) {
541
- result.withheld = { count: outside.length, reason: level === 'normal' ? 'rejected' : 'absolute' }
646
+ // absolute:范围外视为不存在,连"被挡住"都不告诉模型。
647
+ if (!allowed && outcome !== undefined) {
648
+ result.withheld = { count: outside.length, reason: outcome }
542
649
  }
543
650
  if (wantedTopK !== undefined) result.records = result.records.slice(0, wantedTopK)
544
651
  return result
@@ -573,21 +680,86 @@ export function memoryForgetTool(opts )
573
680
  const service = svc(opts)
574
681
  if (!args.id && !args.query) throw new MemoryToolError('TARGET_REQUIRED', 'provide id or query')
575
682
  if (args.id && args.query) throw new MemoryToolError('TARGET_AMBIGUOUS', 'provide id or query, not both')
576
- // id 路径本来就跨 scope(精确 id 不会误删),不解析 scope。
683
+ const agent = agentOf(exec)
684
+ // 没有会话就不判断可见域:护栏只对"本会话的 Agent"生效(与 provider 一致)。
685
+ const policy = agent === undefined ? undefined : visibilityPolicy(service, agent)
686
+ const level = policy?.level ?? 'none'
687
+ const signal = (exec )?.signal
688
+ // ---- 按 id 删除:先查出这条记录在哪个 scope,再按可操作范围判断 ----
577
689
  if (args.id) {
690
+ const matches = (service.getByIds?.([args.id]) ?? []).filter((record) => record.id === args.id)
691
+ const blocked = matches.filter((record) => !recordAllowed(policy, record.scope, record.kind))
692
+ let approved = false
693
+ if (blocked.length > 0) {
694
+ if (level === 'absolute') {
695
+ // 绝对限制:范围外的记录"视为不存在",与真的没有这条 id 完全一样。
696
+ throw new MemoryToolError('RECORD_NOT_FOUND', `id ${args.id} not found`)
697
+ }
698
+ if (level === 'normal') {
699
+ const outcome = await askOutOfScope(
700
+ service,
701
+ agent,
702
+ policy,
703
+ 'memory_forget',
704
+ args.id,
705
+ blocked,
706
+ 'delete',
707
+ signal,
708
+ )
709
+ if (outcome !== 'allowed-once') throw visibilityError(outcome, 'delete', blocked[0] .scope)
710
+ approved = true
711
+ }
712
+ }
578
713
  try {
579
- return await service.forget({ id: args.id })
714
+ return await service.forget({
715
+ id: args.id,
716
+ ...(agent !== undefined ? { agent } : {}),
717
+ ...(approved ? { visibilityApproved: true } : {}),
718
+ })
580
719
  } catch (error) {
581
720
  throw toolError(error)
582
721
  }
583
722
  }
723
+ // ---- 按 query 删除:目标 scope 必须在可操作范围内 ----
584
724
  const resolved = resolveScope(opts, service, exec, args.scope, 'read')
585
725
  if (resolved.all) {
586
726
  throw new MemoryToolError('SCOPE_NOT_WRITABLE', "scope 'all' cannot be combined with query; name the scope you mean")
587
727
  }
588
- const scope = resolved.scope ?? readScopes(opts, service, agentOf(exec))[0]
728
+ const scope = resolved.scope ?? readScopes(opts, service, agent)[0]
729
+ let approved = false
730
+ if (level !== 'none' && scope !== undefined && !scopeOperable(service, agent, policy, scope)) {
731
+ if (level === 'absolute') {
732
+ // 绝对限制:这个作用域"不存在",按一条都没匹配处理(不删、也不泄露原因)。
733
+ return { removed: 0, ids: [] }
734
+ }
735
+ const outcome = await askOutOfScope(
736
+ service,
737
+ agent,
738
+ policy,
739
+ 'memory_forget',
740
+ `删除 ${scope} 中匹配「${args.query}」的记忆`,
741
+ [{
742
+ id: `query:${scope}`,
743
+ scope,
744
+ kind: 'note',
745
+ content: `按关键词「${args.query}」删除该作用域中匹配的记忆`,
746
+ tags: [],
747
+ importance: 0,
748
+ updatedAt: Date.now(),
749
+ }],
750
+ 'delete',
751
+ signal,
752
+ )
753
+ if (outcome !== 'allowed-once') throw visibilityError(outcome, 'delete', scope)
754
+ approved = true
755
+ }
589
756
  try {
590
- return await service.forget({ query: args.query, ...(scope !== undefined ? { scope } : {}) })
757
+ return await service.forget({
758
+ query: args.query,
759
+ ...(scope !== undefined ? { scope } : {}),
760
+ ...(agent !== undefined ? { agent } : {}),
761
+ ...(approved ? { visibilityApproved: true } : {}),
762
+ })
591
763
  } catch (error) {
592
764
  throw toolError(error)
593
765
  }
@@ -605,8 +777,11 @@ export function memoryForgetTool(opts )
605
777
 
606
778
                                 
607
779
 
608
-                            
609
-
780
+
781
+                              
782
+                   
783
+
784
+
610
785
 
611
786
 
612
787
  export function memoryListTool(opts ) {
@@ -623,10 +798,9 @@ export function memoryListTool(opts )
623
798
  const resolved = resolveScope(opts, service, exec, args.scope, 'read')
624
799
  const agent = agentOf(exec)
625
800
  const policy = visibilityPolicy(service, agent)
626
- const level = policy?.level
627
- const visible = policy !== undefined && level !== 'none'
628
- ? policy.scopes.map((rule) => rule.scope)
629
- : visibleScopeList(service, agent)
801
+ const level = policy?.level ?? 'none'
802
+ // level=none 时策略里的 scopes 只是偏好,不参与限制(等价于没有可见域)。
803
+ const visible = policy !== undefined && policy.level !== 'none' ? policy.scopes.map((rule) => rule.scope) : undefined
630
804
  let scopes
631
805
  if (resolved.all) {
632
806
  if (visible !== undefined) {
@@ -638,8 +812,6 @@ export function memoryListTool(opts )
638
812
  // 省略 scope:默认**只列当前会话**(按需求;读全部请显式 'all')。
639
813
  // 这是有意为之的窄口径,不因为"普通限制"就去列范围外的东西。
640
814
  scopes = readScopes(opts, service, agent).slice(0, 1)
641
- } else if (level === 'absolute') {
642
- assertScopeVisible(service, agent, resolved.scope)
643
815
  }
644
816
  let records
645
817
  let withheld
@@ -654,19 +826,22 @@ export function memoryListTool(opts )
654
826
  })
655
827
  const inside = raw.filter((record) => recordAllowed(policy, record.scope, record.kind))
656
828
  const outside = raw.filter((record) => !recordAllowed(policy, record.scope, record.kind))
657
- let granted = false
829
+ // undefined = 没有范围外命中 / 绝对限制(不审批);只有普通限制会真的问一次。
830
+ let outcome
658
831
  if (outside.length > 0 && level === 'normal') {
659
- granted = await askOutOfScope(
832
+ outcome = await askOutOfScope(
660
833
  service,
661
834
  agent,
662
835
  policy,
663
836
  'memory_list',
664
837
  resolved.scope ?? args.scope ?? 'all',
665
838
  outside,
839
+ 'read',
666
840
  (exec )?.signal,
667
841
  )
668
842
  }
669
- const selected = (granted ? raw : inside).slice(0, limit)
843
+ const allowed = outside.length === 0 || outcome === 'allowed-once'
844
+ const selected = (allowed ? raw : inside).slice(0, limit)
670
845
  records = selected.map((r) => ({
671
846
  id: r.id,
672
847
  scope: r.scope,
@@ -674,8 +849,8 @@ export function memoryListTool(opts )
674
849
  updatedAt: r.updatedAt,
675
850
  content: r.content,
676
851
  }))
677
- if (!granted && outside.length > 0) {
678
- withheld = { count: outside.length, reason: level === 'normal' ? 'rejected' : 'absolute' }
852
+ if (!allowed && outcome !== undefined) {
853
+ withheld = { count: outside.length, reason: outcome }
679
854
  }
680
855
  } catch (error) {
681
856
  throw toolError(error)
@@ -728,8 +903,11 @@ export const DEFAULT_GET_FIELDS = ['content', 'scope', 'kind', 'tags
728
903
                            
729
904
 
730
905
 
731
-                              
732
-
906
+
907
+                                
908
+                   
909
+
910
+
733
911
 
734
912
 
735
913
  const FIELD_BY_LOWER = new Map (GET_FIELDS.map((field) => [field.toLowerCase(), field]))
@@ -815,28 +993,31 @@ export function memoryGetTool(opts )
815
993
  // 可见域是白名单:即使知道 id,也不能直接读别的范围/别的类型的正文。
816
994
  const agent = agentOf(exec)
817
995
  const policy = visibilityPolicy(service, agent)
818
- const level = policy?.level
996
+ const level = policy?.level ?? 'none'
819
997
  const inside = all.filter((record) => recordAllowed(policy, record.scope, record.kind))
820
998
  const outside = all.filter((record) => !recordAllowed(policy, record.scope, record.kind))
821
- let granted = false
999
+ // undefined = 没有范围外命中 / 绝对限制(不审批);只有普通限制会真的问一次。
1000
+ let outcome
822
1001
  if (outside.length > 0 && level === 'normal') {
823
- granted = await askOutOfScope(
1002
+ outcome = await askOutOfScope(
824
1003
  service,
825
1004
  agent,
826
1005
  policy,
827
1006
  'memory_get',
828
1007
  ids.join(' '),
829
1008
  outside,
1009
+ 'read',
830
1010
  (exec )?.signal,
831
1011
  )
832
1012
  }
833
- const found = granted ? all : inside
1013
+ const allowed = outside.length === 0 || outcome === 'allowed-once'
1014
+ const found = allowed ? all : inside
834
1015
  return {
835
1016
  records: found.map((r) => pickGetFields(r, fields, chars)),
836
1017
  fields,
837
1018
  missing: ids.filter((token) => !found.some((r) => r.id === token || r.id.startsWith(token))),
838
- ...(!granted && outside.length > 0
839
- ? { withheld: { count: outside.length, reason: level === 'normal' ? 'rejected' : 'absolute' } }
1019
+ ...(!allowed && outcome !== undefined
1020
+ ? { withheld: { count: outside.length, reason: outcome } }
840
1021
  : {}),
841
1022
  }
842
1023
  } catch (error) {
@@ -4,12 +4,19 @@
4
4
  *
5
5
  * 0.16.0 起 memory_search 只给“印象”(id / 作用域 / 类型 / 标签 / 短摘要),
6
6
  * 正文走 memory_get;memory_get 的 fields 决定渲染哪些元数据。
7
+ *
8
+ * 0.20.0:范围外命中被挡住时,把**真实原因**(用户拒绝 / 审批超时 / 无法审批)
9
+ * 写进渲染文本。绝对限制下工具根本不会带 withheld(视为不存在),所以这里
10
+ * 不需要也不应该提"被挡住"。
7
11
  */
8
-
12
+
9
13
 
10
14
  /** 把 scope 键渲染成展示文案(宿主能查到会话标题时用它,否则用短 id)。 */
11
15
 
12
16
 
17
+ /** 有内容没返回时的原因(absolute 模式不会走到这里)。 */
18
+
19
+
13
20
  const shortId = (id ) => id.slice(0, 8)
14
21
 
15
22
  const day = (value ) =>
@@ -18,14 +25,38 @@ const day = (value ) =>
18
25
  const joinList = (value ) =>
19
26
  Array.isArray(value) ? value.map(String).filter((v) => v !== '').join(', ') : ''
20
27
 
28
+ /**
29
+ * 范围外内容为什么没返回——给模型看的真实原因。
30
+ * 空字符串 = 没有需要说明的(没有 withheld,或 absolute 模式下不告知)。
31
+ */
32
+ export function renderWithheldNote(withheld ) {
33
+ if (withheld === undefined || withheld.count <= 0) return ''
34
+ const count = withheld.count
35
+ switch (withheld.reason) {
36
+ case 'rejected':
37
+ return `另有 ${count} 条记忆在本会话的可见域外,用户拒绝了本次访问(限制等级:普通限制),未返回。如确实需要,请让用户调整「记忆范围」后重试。`
38
+ case 'timeout':
39
+ return `另有 ${count} 条记忆在本会话的可见域外,审批在 5 分钟内没有得到答复,已按拒绝处理,未返回。如确实需要,请让用户调整「记忆范围」后重试。`
40
+ case 'unavailable':
41
+ return `另有 ${count} 条记忆在本会话的可见域外,当前环境无法发起审批,未返回。`
42
+ default:
43
+ return ''
44
+ }
45
+ }
46
+
21
47
  /** 「[得分] id (作用域/类型 · 标签) 摘要」;没有任何一条命中时给明确空结果。 */
22
48
  export function renderSearchResult(value , label ) {
23
- if (value.records.length === 0) return '没有找到相关记忆。'
24
- return value.records.map((hit) => {
49
+ const note = renderWithheldNote(value.withheld)
50
+ if (value.records.length === 0) {
51
+ if (note === '') return '没有找到相关记忆。'
52
+ return `没有找到可见范围内的相关记忆。\n${note}`
53
+ }
54
+ const body = value.records.map((hit) => {
25
55
  const tags = joinList(hit.tags)
26
56
  const meta = `${label(hit.scope)}/${hit.kind}${tags === '' ? '' : ` · ${tags}`}`
27
57
  return `[${hit.score.toFixed(3)}] ${shortId(hit.id)} (${meta}) ${hit.summary}`
28
58
  }).join('\n')
59
+ return note === '' ? body : `${body}\n\n${note}`
29
60
  }
30
61
 
31
62
  /**
@@ -74,8 +105,12 @@ export function renderGetResult(value , label ) {
74
105
  return text === '' ? head : `${head}\n${text}`
75
106
  }).join('\n\n')
76
107
  const missing = value.missing.length > 0 ? `未找到:${value.missing.join(', ')}` : ''
77
- if (body === '') return missing || '没有找到记忆。'
78
- return missing === '' ? body : `${body}\n\n${missing}`
108
+ // 被可见域挡住的那几条:absolute 模式下 provider 不会给 withheld(视为不存在),
109
+ // 其余情况把真实原因(拒绝 / 超时 / 无法审批)告诉模型。
110
+ const note = renderWithheldNote(value.withheld)
111
+ const tail = [missing, note].filter((part) => part !== '').join('\n\n')
112
+ if (body === '') return tail === '' ? '没有找到记忆。' : tail
113
+ return tail === '' ? body : `${body}\n\n${tail}`
79
114
  }
80
115
 
81
116
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@restregular/dsh-memory",
3
- "version": "0.19.1",
3
+ "version": "0.20.0",
4
4
  "description": "DeepSeek Harness 记忆系统(单包单入口):JSONL 存储 + 本地向量检索(BGE-M3)+ 五个模型工具 + 自动召回注入 + 管理面板。",
5
5
  "icon": "./icon.svg",
6
6
  "type": "module",