@restregular/dsh-memory 0.28.0 → 0.29.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.
@@ -201,11 +201,16 @@ export class CordisMemoryService extends Service {
201
201
  return this.impl.scopeMeta(scope)
202
202
  }
203
203
 
204
- /** 写入 / 更新作用域用途(不创建记录)。 */
204
+ /** 写入 / 更新 / 清空作用域用途(不创建记录)。 */
205
205
  describeScope(scope , description , by ) {
206
206
  return this.impl.describeScope(scope, description, by)
207
207
  }
208
208
 
209
+ /** 设置 / 移除作用域别名(只影响显示与引用,不改变作用域键)。 */
210
+ renameScope(scope , name ) {
211
+ return this.impl.renameScope(scope, name)
212
+ }
213
+
209
214
  /** 作用域目录:名字 / 用途 / 当前可读可写状态(工具 memory_scopes 与面板共用)。 */
210
215
  scopeCatalog(agent ) {
211
216
  return this.impl.scopeCatalog(agent)
@@ -3189,21 +3189,48 @@ export class LocalMemoryService {
3189
3189
  }
3190
3190
 
3191
3191
  /**
3192
- * 写入 / 更新作用域用途。**不会**创建记录,也不触发初始化;给面板与
3193
- * memory_save 的 scopeDescription 补写用。
3192
+ * 写入 / 更新 / 清空作用域用途。**不会**创建记录,也不触发初始化;给面板、
3193
+ * `memory_scopes` 的 edit 动作与 memory_save 的 scopeDescription 用。
3194
+ *
3195
+ * 0.29.0:空白描述 = **清空**(保留元数据与 generation —— 删元数据会让按
3196
+ * generation 绑定的会话授权失效,所以清空只把 description 写成空串)。
3197
+ * 清空后目录按类型补默认描述,与"从没写过"的展示一致。
3194
3198
  */
3195
3199
  describeScope(scope , description , by ) {
3196
3200
  const key = this.canonicalScope(scope)
3197
3201
  this.assertScopeAllowed(key)
3198
3202
  this.assertCustomScopeBudget(key)
3199
3203
  const text = typeof description === 'string' ? description.replace(/\s+/g, ' ').trim() : ''
3200
- if (text === '') throw memoryError('SCOPE_DESCRIPTION_EMPTY', '作用域用途不能为空')
3201
3204
  if (text.length > MAX_SCOPE_DESCRIPTION_CHARS) {
3202
3205
  throw memoryError('SCOPE_DESCRIPTION_TOO_LONG', `作用域用途最多 ${MAX_SCOPE_DESCRIPTION_CHARS} 字`)
3203
3206
  }
3204
3207
  return this.meta.put(key, { description: text, createdBy: by, status: 'ready' })
3205
3208
  }
3206
3209
 
3210
+ /**
3211
+ * 设置 / 移除作用域别名(0.29.0)。别名只影响**显示与引用**,不改变作用域键:
3212
+ * 项目作用域的身份永远是 `project:<绝对路径>`,自定义作用域永远是名字本身。
3213
+ *
3214
+ * - 非空名字 → `ScopeNames.claim`(统一校验、去重;重名报 SCOPE_NAME_TAKEN);
3215
+ * - 空串 / undefined → 移除别名,显示名回退到键本身(项目路径 / 自定义名);
3216
+ * - global 与 session 不支持别名:它们的显示名跟随类型与会话 id,改名只会让
3217
+ * 同一个域出现两种叫法,没有收益。
3218
+ */
3219
+ renameScope(scope , name ) {
3220
+ const key = this.canonicalScope(scope)
3221
+ this.assertScopeAllowed(key)
3222
+ const kind = scopeKind(key)
3223
+ if (kind === 'global' || kind === 'session') {
3224
+ throw memoryError('SCOPE_NAME_UNSUPPORTED', 'global 与 session 作用域不支持别名:它们的显示名跟随类型与会话 id(项目 / 自定义作用域可以设别名)')
3225
+ }
3226
+ const text = typeof name === 'string' ? name.replace(/\s+/g, ' ').trim() : ''
3227
+ if (text === '') {
3228
+ this.names.release(key)
3229
+ return { scope: key }
3230
+ }
3231
+ return { scope: key, name: this.names.claim(key, text) }
3232
+ }
3233
+
3207
3234
  /** 名字 → 作用域键:读路径允许直接用别名找作用域。 */
3208
3235
  scopeKeyForName(name ) {
3209
3236
  return this.names.scopeOf(name)
@@ -3332,7 +3359,9 @@ export class LocalMemoryService {
3332
3359
  const initialRecords = policy.level === 'absolute' ? undefined : this.initialRecordsOf(scope)
3333
3360
  // 0.27.0:scope-meta 没写用途时按作用域类型给默认描述,
3334
3361
  // 让目录里每一条都自带「这个域是干什么的」。
3335
- const description = meta?.description ?? defaultScopeDescription(scope)
3362
+ // 0.29.0:被显式清空(描述为空串)与从没写过同样处理,都回退到默认描述。
3363
+ const written = typeof meta?.description === 'string' ? meta.description.trim() : ''
3364
+ const description = written !== '' ? written : defaultScopeDescription(scope)
3336
3365
  out.push({
3337
3366
  scope,
3338
3367
  ...(name !== undefined ? { name } : {}),
@@ -191,6 +191,15 @@ import { canonicalWorkspacePath, defaultScopeDescription, normalizeScopeInput, r
191
191
                                
192
192
 
193
193
 
194
+                                 
195
+
196
+
197
+
198
+                               
199
+          
200
+
201
+
202
+
194
203
                    
195
204
                                
196
205
 
@@ -290,6 +299,20 @@ function agentOf(exec ) {
290
299
  return (exec )?.agent
291
300
  }
292
301
 
302
+ /**
303
+ * agent → 会话 id(只给需要"这是谁改的"的元数据写入用,如作用域用途的 createdBy)。
304
+ * 与 provider 的 rawSessionIdOf 同口径:header.id 优先,其次 session.id。
305
+ */
306
+ function sessionIdOf(agent ) {
307
+ try {
308
+ const session = (agent )?.session
309
+ const id = session?.header?.id ?? session?.id
310
+ return typeof id === 'string' && id !== '' ? id : undefined
311
+ } catch {
312
+ return undefined
313
+ }
314
+ }
315
+
293
316
  /**
294
317
  * 当前项目 key。优先级:**服务端解析的会话 cwd** → 显式配置 → process.cwd()。
295
318
  *
@@ -1485,7 +1508,7 @@ export function memoryListTool(opts )
1485
1508
  }
1486
1509
 
1487
1510
 
1488
-
1511
+
1489
1512
                     
1490
1513
 
1491
1514
 
@@ -1499,6 +1522,15 @@ export function memoryListTool(opts )
1499
1522
 
1500
1523
                  
1501
1524
 
1525
+                          
1526
+
1527
+
1528
+                              
1529
+                    
1530
+
1531
+
1532
+                     
1533
+
1502
1534
                       
1503
1535
 
1504
1536
 
@@ -1511,7 +1543,17 @@ export function memoryListTool(opts )
1511
1543
 
1512
1544
 
1513
1545
 
1514
-
1546
+ /**
1547
+ * action='edit' 的结果(0.29.0):只回「改成了什么」,不回记忆内容。
1548
+ * 字段缺省 = 这次没动它;空串 = 已清空(用途)或已移除(别名)。
1549
+ */
1550
+
1551
+
1552
+
1553
+
1554
+
1555
+
1556
+
1515
1557
 
1516
1558
  /**
1517
1559
  * 作用域目录 / 权限申请工具(0.24.0)。
@@ -1525,9 +1567,9 @@ export function memoryListTool(opts )
1525
1567
  export function memoryScopesTool(opts ) {
1526
1568
  return {
1527
1569
  name: 'memory_scopes',
1528
- description: 'List memory scopes with their purpose and access status (metadata only, no content), or request session access to out-of-scope scopes. action="request" defaults to read-only and requires a reason; absolute restriction never grants access.',
1570
+ description: 'List memory scopes with their purpose and access status (metadata only, no content), request session access to out-of-scope scopes, or edit a scope\'s purpose and alias. action="edit" updates the scope description (empty = clear, falls back to the type default) and/or alias (empty = remove); the scope must be writable in this session. action="request" defaults to read-only and requires a reason; absolute restriction never grants access.',
1529
1571
  parameters: {
1530
- action: { type: 'string', enum: ['list', 'request'], description: 'list = 目录;request = 申请范围外作用域的会话权限(默认只读)' },
1572
+ action: { type: 'string', enum: ['list', 'request', 'edit'], description: 'list = 目录;request = 申请范围外作用域的会话权限(默认只读);edit = 编辑某个作用域的描述 / 别名(需要该作用域可写)' },
1531
1573
  includeOutOfScope: { type: 'boolean', description: 'list:默认 true;false 时只列当前可见域内的作用域。' },
1532
1574
  limit: { type: 'number', description: 'list:1~200,默认 50' },
1533
1575
  scopes: {
@@ -1541,6 +1583,9 @@ export function memoryScopesTool(opts )
1541
1583
  description: 'request:申请哪些权限,省略 = 只读;写权限必须显式加 "write"',
1542
1584
  },
1543
1585
  reason: { type: 'string', description: 'request:一句话申请理由,展示在审批卡上' },
1586
+ scope: { type: 'string', description: 'edit:要编辑的作用域键(目录里显示的那个,如 handbook / project:<路径>)。当前会话范围外时先用 action="request" 申请写权限' },
1587
+ scopeDescription: { type: 'string', description: 'edit:新的用途(一句话,最多 500 字)。空串 = 清空并回退到按类型的默认描述;与本参数一起省略 scopeName 则报错。' },
1588
+ scopeName: { type: 'string', description: 'edit:新的别名(只影响显示与引用,不改作用域键;项目 / 自定义作用域支持)。空串 = 移除别名;省略 = 这次不改别名。' },
1544
1589
  description: { type: 'string', description: DESCRIPTION_PARAM_DESCRIPTION },
1545
1590
  },
1546
1591
  async execute(args , exec ) {
@@ -1548,6 +1593,66 @@ export function memoryScopesTool(opts )
1548
1593
  const agent = agentOf(exec)
1549
1594
  requireDescription(service, agent, args.description)
1550
1595
 
1596
+ // ---- action='edit':编辑作用域描述 / 别名(0.29.0)----
1597
+ // 只改**目录元数据**,不碰任何记忆记录;需要该作用域可写(范围外先用
1598
+ // action='request' 拿写权限,不走隐式审批 —— 审批卡里没有"一条记忆"可展示)。
1599
+ if (args.action === 'edit') {
1600
+ const rawScope = typeof args.scope === 'string' ? args.scope.trim() : ''
1601
+ if (rawScope === '') throw new MemoryToolError('SCOPE_REQUIRED', 'action="edit" 需要 scope(要编辑的作用域键,目录里显示的那个)')
1602
+ const wantDescription = typeof args.scopeDescription === 'string'
1603
+ const wantName = typeof args.scopeName === 'string'
1604
+ if (!wantDescription && !wantName) {
1605
+ throw new MemoryToolError('EDIT_NOTHING_TO_UPDATE', 'action="edit" 至少要给 scopeDescription 或 scopeName 之一(想清空用途传空串,想移除别名传空串)')
1606
+ }
1607
+ if (typeof service.describeScope !== 'function' && wantDescription) {
1608
+ throw new MemoryToolError('SCOPES_UNAVAILABLE', '当前 provider 不支持编辑作用域用途(请升级 @restregular/dsh-memory)')
1609
+ }
1610
+ if (typeof service.renameScope !== 'function' && wantName) {
1611
+ throw new MemoryToolError('SCOPES_UNAVAILABLE', '当前 provider 不支持编辑作用域别名(请升级 @restregular/dsh-memory)')
1612
+ }
1613
+ const resolved = resolveScope(opts, service, exec, rawScope, 'write')
1614
+ if (resolved.all === true) {
1615
+ throw new MemoryToolError('SCOPE_NOT_WRITABLE', "scope 'all' cannot be edited; name one scope")
1616
+ }
1617
+ const scope = resolved.scope ?? currentSessionScope(service, exec)
1618
+ if (scope === undefined) {
1619
+ throw new MemoryToolError('SCOPE_INVALID', `scope "${rawScope}" could not be resolved; use the concrete scope key shown by action="list"`)
1620
+ }
1621
+ // 可写护栏:与写入记忆同一把锁(write 开关 / absolute / 范围外)。
1622
+ const policy = visibilityPolicy(service, agent)
1623
+ const decide = decisionMaker(service, agent)
1624
+ const level = policy?.level ?? 'none'
1625
+ if (level !== 'none' && !scopeWritableBy(decide, service, agent, policy, scope)) {
1626
+ const decision = decide('write', scope)
1627
+ if (decision !== undefined) {
1628
+ if (!decision.requestable) throw writeDecisionError(decision, scope, 'write')
1629
+ throw new MemoryToolError(
1630
+ 'SCOPE_NOT_WRITABLE',
1631
+ `作用域 ${scope} 不在本会话的可写范围内;编辑作用域信息需要写权限,先用 memory_scopes({ action: "request", scopes: ["${scope}"], permissions: ["write"] }) 申请,批准后重试。`,
1632
+ )
1633
+ }
1634
+ if (policy?.level === 'normal') {
1635
+ // 老 provider 没有统一判定:普通限制下范围外就是"可申请",别报成绝对限制。
1636
+ throw new MemoryToolError(
1637
+ 'SCOPE_NOT_WRITABLE',
1638
+ `作用域 ${scope} 不在本会话的可写范围内;编辑作用域信息需要写权限,先用 memory_scopes({ action: "request", scopes: ["${scope}"], permissions: ["write"] }) 申请,批准后重试。`,
1639
+ )
1640
+ }
1641
+ throw scopeWriteBlockedError(policy, scope, 'write')
1642
+ }
1643
+ const description = wantDescription ? String(args.scopeDescription) : undefined
1644
+ const name = wantName ? String(args.scopeName) : undefined
1645
+ const by = sessionIdOf(agent) ?? 'agent'
1646
+ try {
1647
+ const edited = { scope }
1648
+ if (description !== undefined) edited.description = service.describeScope (scope, description, by).description
1649
+ if (name !== undefined) edited.name = service.renameScope (scope, name).name ?? ''
1650
+ return edited
1651
+ } catch (error) {
1652
+ throw toolError(error)
1653
+ }
1654
+ }
1655
+
1551
1656
  if (args.action === 'request') {
1552
1657
  if (typeof service.requestScopeGrants !== 'function') {
1553
1658
  throw new MemoryToolError('SCOPES_UNAVAILABLE', '当前 provider 不支持作用域权限申请(请升级 @restregular/dsh-memory)')
@@ -149,7 +149,8 @@ export function renderListResult(value , label ) {
149
149
 
150
150
  /**
151
151
  * memory_scopes 的渲染:list 只讲“有什么、干什么、能不能碰”;request 讲每个
152
- * scope + 权限的申请结局。两者共用同一个工具入口,但文案完全分开。
152
+ * scope + 权限的申请结局;edit(0.29.0)讲这次改了描述 / 别名的什么。
153
+ * 三者共用同一个工具入口,但文案完全分开。
153
154
  */
154
155
  export function renderScopesResult(value , label ) {
155
156
  if ('results' in value) {
@@ -181,6 +182,20 @@ export function renderScopesResult(value , label )
181
182
  ).join('\n')
182
183
  return `作用域权限申请结果:\n${body}`
183
184
  }
185
+ // edit(0.29.0):只回「改成了什么」。没动过的字段不出现,空串表示清空 / 移除。
186
+ if ('scope' in value) {
187
+ const name = value.name !== undefined && value.name !== '' ? scopeDisplayName(value.scope, value.name) : label(value.scope)
188
+ const lines = [`作用域已更新:${name}(${value.scope})`]
189
+ if (value.description !== undefined) {
190
+ lines.push(value.description === ''
191
+ ? '- 用途:已清空(回退到按类型的默认描述)'
192
+ : `- 用途:${value.description}`)
193
+ }
194
+ if (value.name !== undefined) {
195
+ lines.push(value.name === '' ? '- 别名:已移除(显示名回退到作用域键)' : `- 别名:${value.name}`)
196
+ }
197
+ return lines.join('\n')
198
+ }
184
199
  if (value.scopes.length === 0) return '当前没有可列出的作用域。'
185
200
  const body = value.scopes.map((item) => {
186
201
  // 别名(项目 / 自定义作用域)也带类型前缀:自定义作用域的键本身没有前缀,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@restregular/dsh-memory",
3
- "version": "0.28.0",
3
+ "version": "0.29.0",
4
4
  "description": "DeepSeek Harness 记忆系统(单包单入口):JSONL 存储 + 本地向量检索(BGE-M3)+ 五个模型工具 + 自动召回注入 + 管理面板。",
5
5
  "icon": "./icon.svg",
6
6
  "type": "module",