@restregular/dsh-memory 0.23.1 → 0.24.1

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.
@@ -35,6 +35,20 @@ import {
35
35
 
36
36
  } from './session-visibility.js'
37
37
  import { WorkspaceBindingsStore } from './workspace-bindings.js'
38
+ import { SessionGrantsStore, } from './grants.js'
39
+ import { ApprovalAuditStore, } from './approval-audit.js'
40
+ import {
41
+ authorize as authorizeAccess,
42
+
43
+
44
+
45
+ } from './authorize.js'
46
+ import {
47
+ MAX_SCOPE_DESCRIPTION_CHARS,
48
+ ScopeMetaStore,
49
+
50
+
51
+ } from './scope-meta.js'
38
52
  import { mergeInjectSettings, normalizeInjectSettings, } from './inject-settings.js'
39
53
  import { buildStats, lexicalScore, recordScore, tokenize, cosine, normalizeInPlace, hasStrongHit } from './scoring.js'
40
54
  import { EmbedClient } from './embed.js'
@@ -520,6 +534,37 @@ export function resolveConfig(config = {}) {
520
534
 
521
535
 
522
536
 
537
+ /**
538
+ * 目录工具(memory_scopes list)的一行:作用域的“身份证 + 当前访问状态”。
539
+ *
540
+ * 0.24.0 起目录可见与正文可读是两件事:
541
+ * - `absolute` 下范围外作用域仍列出名字/用途(`accessStatus='restricted'`),
542
+ * 但 `readable/writable` 恒为 false,`canRequest*` 也恒为 false —— absolute
543
+ * 没有任何审批放行路径;
544
+ * - `normal` 下范围外可申请,`canRequest*` 才是 true;
545
+ * - 自定义作用域开关关闭时整个条目不出现(不是 `unavailable`)。
546
+ */
547
+
548
+
549
+
550
+
551
+
552
+                            
553
+
554
+
555
+
556
+
557
+
558
+
559
+
560
+
561
+
562
+                       
563
+                                     
564
+
565
+
566
+
567
+
523
568
  /** 范围外访问的动作(读取 / 写入 / 删除);审批浮层按它换文案。 */
524
569
 
525
570
 
@@ -534,6 +579,8 @@ export function resolveConfig(config = {}) {
534
579
 
535
580
                                    
536
581
 
582
+                      
583
+
537
584
 
538
585
 
539
586
 
@@ -546,6 +593,11 @@ export function resolveConfig(config = {}) {
546
593
 
547
594
                              
548
595
 
596
+
597
+                        
598
+                       
599
+
600
+
549
601
 
550
602
 
551
603
 
@@ -554,6 +606,32 @@ export function resolveConfig(config = {}) {
554
606
  /** 一次审批的结局:允许(可只允许其中几条) / 拒绝 / 超时。 */
555
607
 
556
608
 
609
+ /** 一条作用域权限申请的处理结果(0.24.0 / D3)。 */
610
+
611
+
612
+
613
+
614
+
615
+
616
+
617
+
618
+
619
+
620
+
621
+
622
+
623
+
624
+                
625
+
626
+
627
+
628
+
629
+
630
+
631
+                 
632
+
633
+
634
+
557
635
  /**
558
636
  * 审批结论(0.21.0)。`allowedIds` 省略 = 本次请求的所有条目都允许;
559
637
  * 用户在审批卡里逐条勾选时只带被勾选的条目 id。
@@ -597,12 +675,18 @@ export class LocalMemoryService {
597
675
  scopesReconciled = false
598
676
  /** 作用域别名(project:<路径> → 显示名),落盘 <storeDir>/scopes.json。 */
599
677
  names
678
+ /** 作用域用途等元数据;每作用域一个文件,旧作用域按需懒合成。 */
679
+ meta
600
680
  /** 注入设置(面板「设置」标签页可改;落盘在 <storeDir>/settings.json)。 */
601
681
  inject
602
682
  /** 会话级「记忆可见范围」覆盖;没有覆盖时沿用默认集合。 */
603
683
  visibility
604
684
  /** 工作区级「绑定作用域」:默认范围会额外并入这些作用域。 */
605
685
  bindings
686
+ /** 会话级授权(Agent 申请、用户批准);独立于 visibility 策略。 */
687
+ grants
688
+ /** 权限申请 / 授权生命周期审计(approvals.jsonl,不含正文)。 */
689
+ approvalAudit
606
690
  /** 可见域变更通知:下一次 pre-step 注入给 Agent 后删除(按会话)。 */
607
691
  visibilityNotices = new Map ()
608
692
  /** 普通限制下等待用户审批的范围外访问(按审批 id)。 */
@@ -626,8 +710,11 @@ export class LocalMemoryService {
626
710
  this.cfg = resolveConfig(config)
627
711
  this.inject = this.loadInjectSettings((config ).inject)
628
712
  this.names = new ScopeNames(join(this.cfg.storeDir, 'scopes.json'))
713
+ this.meta = new ScopeMetaStore({ root: this.cfg.storeDir })
629
714
  this.visibility = new SessionVisibilityStore({ root: this.cfg.storeDir })
630
715
  this.bindings = new WorkspaceBindingsStore({ root: this.cfg.storeDir })
716
+ this.grants = new SessionGrantsStore({ root: this.cfg.storeDir })
717
+ this.approvalAudit = new ApprovalAuditStore({ root: this.cfg.storeDir })
631
718
  this.rerankBudget = new DailyBudget(this.cfg.llm.dailyBudgetTokens)
632
719
  this.store = new MemoryStore(this.cfg.storeDir, { onWarn: (m) => console.warn(`[dsh-memory-local] ${m}`) })
633
720
  // Identity BEFORE the eager load (issue #1): ScopeStore skips its sidecar
@@ -1352,7 +1439,8 @@ export class LocalMemoryService {
1352
1439
  */
1353
1440
  assertCustomScopeBudget(scope ) {
1354
1441
  if (!isCustomScope(scope)) return
1355
- if (this.store.peek(scope) !== undefined) return // 已存在(内存或磁盘)→ 写入不受限
1442
+ // 已有记录或已有元数据都算“已存在”:删光记录但保留元数据的作用域不该再占一个新名额。
1443
+ if (this.store.peek(scope) !== undefined || this.meta.has(scope)) return
1356
1444
  const loaded = this.store.allScopes().filter((s) => isCustomScope(s.scope)).length
1357
1445
  if (loaded < this.cfg.customMaxScopes && this.store.customScopeCount() < this.cfg.customMaxScopes) return
1358
1446
  throw memoryError(
@@ -1469,6 +1557,52 @@ export class LocalMemoryService {
1469
1557
  }
1470
1558
  }
1471
1559
 
1560
+ /**
1561
+ * 沿 parentSession 链收集 grant(当前会话在前、父会话在后)。
1562
+ * 子 Agent 与父会话是同一个任务,应该继承父会话获批的权限。
1563
+ */
1564
+ resolveGrantChain(sessionId ) {
1565
+ const out = []
1566
+ const seen = new Set ()
1567
+ let id = sessionId
1568
+ while (id !== '' && !seen.has(id)) {
1569
+ seen.add(id)
1570
+ out.push(...this.grants.list(id))
1571
+ let parent
1572
+ try {
1573
+ const session = this.sessionLookup?.(id)
1574
+ parent = typeof session?.header?.parentSession === 'string' && session.header.parentSession !== ''
1575
+ ? session.header.parentSession
1576
+ : undefined
1577
+ } catch { parent = undefined }
1578
+ id = parent ?? ''
1579
+ }
1580
+ return out
1581
+ }
1582
+
1583
+ /**
1584
+ * 当前 agent 的有效 grant:作用域仍启用、作用域代次一致(同名重建不复用旧授权)。
1585
+ * `grants.list()` 已过滤撤销 / 过期;这里再按 provider 的 canonicalScope 统一键。
1586
+ */
1587
+ validGrants(agent ) {
1588
+ const sessionId = this.rawSessionIdOf(agent)
1589
+ if (sessionId === undefined) return []
1590
+ const out = []
1591
+ for (const grant of this.resolveGrantChain(sessionId)) {
1592
+ const scope = this.canonicalScope(grant.scope)
1593
+ if (!this.scopeEnabled(scope)) continue
1594
+ const meta = this.meta.get(scope)
1595
+ if (meta !== undefined && grant.scopeGeneration !== meta.generation) continue
1596
+ out.push({ ...grant, scope })
1597
+ }
1598
+ return out
1599
+ }
1600
+
1601
+ /** 面板/诊断:当前会话(含父链)的有效授权快照。 */
1602
+ activeGrants(agent ) {
1603
+ return this.validGrants(agent)
1604
+ }
1605
+
1472
1606
  /** 没有显式覆盖时的默认可见域范围(会话 + 项目 + global + 工作区绑定的作用域)。 */
1473
1607
  /** 默认三路(会话 + 项目 + global),**不含**工作区绑定;各自开关生效。 */
1474
1608
  baseDefaultScopes(agent ) {
@@ -1566,33 +1700,62 @@ export class LocalMemoryService {
1566
1700
  return rule.kinds !== undefined && rule.kinds.length > 0 ? [...rule.kinds] : undefined
1567
1701
  }
1568
1702
 
1569
- /** 一条记录(scope + kind)是否落在当前可见域内;等级 none 时恒为 true。 */
1570
- isRecordVisible(agent , scope , kind ) {
1703
+ /**
1704
+ * 把 agent 解析成一次性授权上下文(可见域只解析一次)。
1705
+ * 纯函数 `authorize()` 是唯一规则出口;这里只负责把配置 / 策略翻译成上下文。
1706
+ */
1707
+ accessContext(agent ) {
1571
1708
  const policy = this.visibilityPolicy(agent)
1572
- if (policy.level === 'none') return true
1573
- const key = this.canonicalScope(scope)
1574
- const rule = policy.scopes.find((item) => this.canonicalScope(item.scope) === key)
1575
- if (rule === undefined || rule.read === false) return false
1576
- if (rule.kinds === undefined || rule.kinds.length === 0) return true
1577
- return rule.kinds.includes(kind)
1709
+ return {
1710
+ level: policy.level,
1711
+ scopes: policy.scopes,
1712
+ enabled: {
1713
+ global: this.cfg.globalEnabled,
1714
+ project: this.cfg.projectEnabled,
1715
+ session: this.cfg.sessionEnabled,
1716
+ custom: this.cfg.customEnabled,
1717
+ },
1718
+ originOf: (scope) => scopeKind(scope),
1719
+ grants: this.validGrants(agent),
1720
+ }
1721
+ }
1722
+
1723
+ /**
1724
+ * 统一授权判定:discover / read / write / delete 全部走这里。
1725
+ * 工具层、检索过滤、目录与注入都应以它为准,不再各自解释 absolute / normal / none。
1726
+ */
1727
+ authorize(agent , request ) {
1728
+ return authorizeAccess(
1729
+ { ...request, scope: this.canonicalScope(request.scope) },
1730
+ this.accessContext(agent),
1731
+ )
1732
+ }
1733
+
1734
+ /**
1735
+ * 一次解析、多次判定的版本:检索会逐条判定命中,不能每条都重新解析可见域
1736
+ * (那会重复读会话文件、重复走 parentSession 链)。
1737
+ */
1738
+ accessEvaluator(agent ) {
1739
+ const context = this.accessContext(agent)
1740
+ return (request) => authorizeAccess(
1741
+ { ...request, scope: this.canonicalScope(request.scope) },
1742
+ context,
1743
+ )
1744
+ }
1745
+
1746
+ /** 一条记录(scope + kind)是否可读。 */
1747
+ isRecordVisible(agent , scope , kind ) {
1748
+ return this.authorize(agent, { scope, action: 'read', kind }).allowed
1578
1749
  }
1579
1750
 
1580
1751
  /** 某个作用域是否可读(0.23.0:read 开关);等级 none 时恒为 true。 */
1581
1752
  isScopeReadable(agent , scope ) {
1582
- const policy = this.visibilityPolicy(agent)
1583
- if (policy.level === 'none') return true
1584
- const key = this.canonicalScope(scope)
1585
- const rule = policy.scopes.find((item) => this.canonicalScope(item.scope) === key)
1586
- return rule !== undefined && rule.read !== false
1753
+ return this.authorize(agent, { scope, action: 'read' }).allowed
1587
1754
  }
1588
1755
 
1589
1756
  /** 某个作用域是否可写(0.23.0:write 开关);等级 none 时恒为 true。 */
1590
1757
  isScopeWritable(agent , scope ) {
1591
- const policy = this.visibilityPolicy(agent)
1592
- if (policy.level === 'none') return true
1593
- const key = this.canonicalScope(scope)
1594
- const rule = policy.scopes.find((item) => this.canonicalScope(item.scope) === key)
1595
- return rule !== undefined && rule.write !== false
1758
+ return this.authorize(agent, { scope, action: 'write' }).allowed
1596
1759
  }
1597
1760
 
1598
1761
  /**
@@ -1608,21 +1771,9 @@ export class LocalMemoryService {
1608
1771
  * undefined = 不限制。
1609
1772
  */
1610
1773
  visibilityFilterFor(agent ) {
1611
- const policy = this.visibilityPolicy(agent)
1612
- if (policy.level === 'none') return undefined
1613
- const byScope = new Map ()
1614
- for (const rule of policy.scopes) {
1615
- byScope.set(this.canonicalScope(rule.scope), {
1616
- kinds: rule.kinds !== undefined && rule.kinds.length > 0 ? rule.kinds : undefined,
1617
- read: rule.read !== false,
1618
- })
1619
- }
1620
- return (scope, kind) => {
1621
- const key = this.canonicalScope(scope)
1622
- const entry = byScope.get(key)
1623
- if (entry === undefined || !entry.read) return false
1624
- return entry.kinds === undefined || entry.kinds.includes(kind)
1625
- }
1774
+ if (this.visibilityPolicy(agent).level === 'none') return undefined
1775
+ const evaluate = this.accessEvaluator(agent)
1776
+ return (scope, kind) => evaluate({ scope, action: 'read', kind }).allowed
1626
1777
  }
1627
1778
 
1628
1779
  /** 面板:读取某会话自己的覆盖(null = 没有覆盖,继续用默认集合)。 */
@@ -1776,6 +1927,8 @@ export class LocalMemoryService {
1776
1927
 
1777
1928
                        
1778
1929
 
1930
+                   
1931
+
1779
1932
 
1780
1933
 
1781
1934
  ,
@@ -1787,18 +1940,37 @@ export class LocalMemoryService {
1787
1940
  const createdAt = Date.now()
1788
1941
  const expiresAt = createdAt + VISIBILITY_APPROVAL_TTL_MS
1789
1942
  const description = typeof input.description === 'string' ? input.description.replace(/\s+/g, ' ').trim().slice(0, 500) : ''
1943
+ const auditBase = {
1944
+ at: createdAt,
1945
+ event: 'requested',
1946
+ id,
1947
+ sessionId,
1948
+ tool: input.tool,
1949
+ action: input.action ?? 'read',
1950
+ mode: input.mode ?? 'records',
1951
+ scopes: [...new Set(input.items.map((item) => item.scope))],
1952
+ count: input.items.length,
1953
+ ...(description !== '' ? { description } : {}),
1954
+ }
1955
+ this.approvalAudit.append(auditBase)
1790
1956
  return new Promise((resolve) => {
1791
1957
  let timer
1792
- const onAbort = () => finish({ outcome: 'rejected' })
1793
- const finish = (answer ) => {
1958
+ const onAbort = () => finish({ outcome: 'rejected' }, 'aborted')
1959
+ const finish = (answer , why ) => {
1794
1960
  const pending = this.pendingApprovals.get(id)
1795
1961
  if (pending === undefined) return
1796
1962
  this.pendingApprovals.delete(id)
1797
1963
  if (timer !== undefined) clearTimeout(timer)
1798
1964
  try { input.signal?.removeEventListener('abort', onAbort) } catch { /* 已卸载 */ }
1965
+ this.approvalAudit.append({
1966
+ ...auditBase,
1967
+ at: Date.now(),
1968
+ event: why === 'timeout' ? 'timeout' : 'denied',
1969
+ outcome: answer.outcome,
1970
+ })
1799
1971
  pending.resolve(answer)
1800
1972
  }
1801
- timer = setTimeout(() => finish({ outcome: 'timeout' }), VISIBILITY_APPROVAL_TTL_MS)
1973
+ timer = setTimeout(() => finish({ outcome: 'timeout' }, 'timeout'), VISIBILITY_APPROVAL_TTL_MS)
1802
1974
  timer.unref?.()
1803
1975
  this.pendingApprovals.set(id, {
1804
1976
  id,
@@ -1807,6 +1979,7 @@ export class LocalMemoryService {
1807
1979
  action: input.action ?? 'read',
1808
1980
  query: input.query,
1809
1981
  ...(description !== '' ? { description } : {}),
1982
+ ...(input.mode !== undefined ? { mode: input.mode } : {}),
1810
1983
  items: input.items.slice(0, VISIBILITY_APPROVAL_MAX_ITEMS).map((item) => ({
1811
1984
  ...item,
1812
1985
  tags: [...item.tags],
@@ -1832,6 +2005,7 @@ export class LocalMemoryService {
1832
2005
  action: pending.action,
1833
2006
  query: pending.query,
1834
2007
  ...(pending.description !== undefined ? { description: pending.description } : {}),
2008
+ ...(pending.mode !== undefined ? { mode: pending.mode } : {}),
1835
2009
  // 轮询载荷保持轻量:正文截到 1200 字,悬浮需要全文时面板再按 id 取一次。
1836
2010
  items: pending.items.map((item) => ({
1837
2011
  ...item,
@@ -1866,10 +2040,172 @@ export class LocalMemoryService {
1866
2040
  } else {
1867
2041
  answer = { outcome: 'allowed-once' }
1868
2042
  }
2043
+ this.approvalAudit.append({
2044
+ at: Date.now(),
2045
+ event: answer.outcome === 'allowed-once' ? 'approved' : 'denied',
2046
+ id,
2047
+ sessionId: pending.sessionId,
2048
+ tool: pending.tool,
2049
+ action: pending.action,
2050
+ mode: pending.mode ?? 'records',
2051
+ scopes: [...new Set(pending.items.map((item) => item.scope))],
2052
+ count: pending.items.length,
2053
+ outcome: answer.outcome,
2054
+ })
1869
2055
  pending.resolve(answer)
1870
2056
  return true
1871
2057
  }
1872
2058
 
2059
+ /**
2060
+ * Agent 主动申请范围外作用域的会话权限(0.24.0 / D3)。
2061
+ *
2062
+ * 流程:先按统一授权判定逐条筛(已允许 / 已授权 / 不可申请都不弹卡),
2063
+ * 只把**可申请**的 scope + 权限合成审批卡(`mode='grant'`),用户批准后
2064
+ * 写入 `grants/<session>.json`(仅本会话,子 Agent 沿 parentSession 继承)。
2065
+ *
2066
+ * 一次性访问**不在**这里:它继续由 memory_* 的隐式审批处理;本工具只申请会话授权。
2067
+ */
2068
+ async requestScopeGrants(
2069
+ agent ,
2070
+ input
2071
+
2072
+
2073
+
2074
+
2075
+ ,
2076
+ ) {
2077
+ const sessionId = this.rawSessionIdOf(agent)
2078
+ const results = []
2079
+ const describe = (request ) =>
2080
+ [...new Set(request.permissions.filter((item) => item === 'read' || item === 'write'))]
2081
+ if (sessionId === undefined) {
2082
+ for (const request of input.requests) {
2083
+ const scope = this.canonicalScope(request.scope)
2084
+ for (const permission of describe(request)) results.push({ scope, permission, status: 'unavailable' })
2085
+ }
2086
+ return { results, outcome: 'unavailable', grants: [] }
2087
+ }
2088
+
2089
+ const pending = []
2090
+ const seen = new Set ()
2091
+ for (const request of input.requests) {
2092
+ const scope = this.canonicalScope(request.scope)
2093
+ for (const permission of describe(request)) {
2094
+ const key = `${scope}\0${permission}`
2095
+ if (seen.has(key)) continue
2096
+ seen.add(key)
2097
+ const decision = this.authorize(agent, { scope, action: permission === 'read' ? 'read' : 'write' })
2098
+ if (decision.allowed) {
2099
+ results.push({
2100
+ scope,
2101
+ permission,
2102
+ status: decision.source === 'grant' ? 'already-granted' : 'already-allowed',
2103
+ })
2104
+ continue
2105
+ }
2106
+ if (!decision.requestable) {
2107
+ results.push({ scope, permission, status: 'not-requestable', ...(decision.reason !== undefined ? { reason: decision.reason } : {}) })
2108
+ continue
2109
+ }
2110
+ pending.push({ id: `grant:${scope}:${permission}`, scope, permission })
2111
+ }
2112
+ }
2113
+ if (pending.length === 0) return { results, grants: [] }
2114
+
2115
+ const reason = typeof input.reason === 'string' ? input.reason.replace(/\s+/g, ' ').trim().slice(0, 500) : ''
2116
+ const answer = await this.requestOutOfScope(agent, {
2117
+ tool: 'memory_scopes',
2118
+ action: 'read',
2119
+ query: reason === '' ? [...new Set(pending.map((item) => item.scope))].join(' ') : reason,
2120
+ ...(input.description !== undefined ? { description: input.description } : {}),
2121
+ mode: 'grant',
2122
+ items: pending.map((item) => ({
2123
+ id: item.id,
2124
+ scope: item.scope,
2125
+ kind: 'grant',
2126
+ content: item.permission === 'read' ? '只读访问' : '写入 / 删除',
2127
+ tags: [],
2128
+ importance: 0,
2129
+ updatedAt: Date.now(),
2130
+ reason: 'scope' ,
2131
+ grantPermission: item.permission,
2132
+ })),
2133
+ ...(input.signal !== undefined ? { signal: input.signal } : {}),
2134
+ })
2135
+
2136
+ if (answer.outcome !== 'allowed-once') {
2137
+ const status = answer.outcome === 'timeout' ? 'timeout' : answer.outcome === 'unavailable' ? 'approval-unavailable' : 'denied'
2138
+ for (const item of pending) {
2139
+ results.push({ scope: item.scope, permission: item.permission, status })
2140
+ }
2141
+ return { results, outcome: answer.outcome, grants: [] }
2142
+ }
2143
+
2144
+ const approved = answer.allowedIds === undefined
2145
+ ? new Set(pending.map((item) => item.id))
2146
+ : new Set(answer.allowedIds)
2147
+ const granted = []
2148
+ for (const item of pending) {
2149
+ if (!approved.has(item.id)) {
2150
+ results.push({ scope: item.scope, permission: item.permission, status: 'denied' })
2151
+ continue
2152
+ }
2153
+ const meta = this.meta.get(item.scope)
2154
+ const grant = this.grants.add(sessionId, {
2155
+ scope: item.scope,
2156
+ permissions: [item.permission],
2157
+ grantedBy: 'user',
2158
+ ...(meta !== undefined ? { scopeGeneration: meta.generation } : {}),
2159
+ })
2160
+ granted.push(grant)
2161
+ this.approvalAudit.append({
2162
+ at: Date.now(),
2163
+ event: 'granted',
2164
+ id: grant.id,
2165
+ sessionId,
2166
+ tool: 'memory_scopes',
2167
+ action: 'grant',
2168
+ mode: 'grant',
2169
+ scopes: [item.scope],
2170
+ permissions: [item.permission],
2171
+ outcome: 'granted',
2172
+ })
2173
+ results.push({ scope: item.scope, permission: item.permission, status: 'granted' })
2174
+ }
2175
+ return { results, outcome: 'allowed-once', grants: granted }
2176
+ }
2177
+
2178
+ /** 面板 / 诊断:当前会话的有效授权(含父会话继承)。 */
2179
+ grantList(agent ) {
2180
+ return this.validGrants(agent)
2181
+ }
2182
+
2183
+ /** 面板:撤销某会话的一条授权。 */
2184
+ revokeGrant(sessionId , id ) {
2185
+ if (typeof sessionId !== 'string' || sessionId === '') return false
2186
+ const before = this.grants.list(sessionId).find((grant) => grant.id === id)
2187
+ const ok = this.grants.revoke(sessionId, id)
2188
+ if (ok) {
2189
+ this.approvalAudit.append({
2190
+ at: Date.now(),
2191
+ event: 'revoked',
2192
+ id,
2193
+ sessionId,
2194
+ tool: 'memory_scopes',
2195
+ action: 'revoke',
2196
+ mode: 'grant',
2197
+ ...(before !== undefined ? { scopes: [before.scope], permissions: before.permissions } : {}),
2198
+ outcome: 'revoked',
2199
+ })
2200
+ }
2201
+ return ok
2202
+ }
2203
+
2204
+ /** 面板 / 诊断:最近的审批与授权事件(不含记忆正文)。 */
2205
+ approvalAuditList(limit = 200) {
2206
+ return this.approvalAudit.list(limit)
2207
+ }
2208
+
1873
2209
  /**
1874
2210
  * 无显式 scope 时的**读取**合并集合:当前会话 + 当前项目 + global(各自开关生效、按 key 去重)。
1875
2211
  * 工具 / 注入都用它。会话设置了「可见范围」时以覆盖为准(不再并入默认集合)。
@@ -1892,16 +2228,19 @@ export class LocalMemoryService {
1892
2228
  * - none:不限制。
1893
2229
  */
1894
2230
  assertOperable(agent , scope ) {
1895
- if (this.isScopeWritable(agent, scope)) return
1896
- const policy = this.visibilityPolicy(agent)
1897
- const rule = policy.scopes.find((item) => this.canonicalScope(item.scope) === this.canonicalScope(scope))
1898
- if (rule !== undefined) {
1899
- throw memoryError('SCOPE_READ_ONLY', `作用域 ${scope} 在本会话记忆范围里被标记为「不可写」(可读/可写按钮),本次写入/删除没有执行。如需写入,请让用户打开该作用域的「可写」状态。`)
1900
- }
1901
- if (policy.level === 'absolute') {
1902
- throw memoryError('SCOPE_NOT_WRITABLE', `作用域 ${scope} 不在本会话可见范围内(限制等级:绝对限制),本次写入/删除没有执行。如需写入,请让用户调整「记忆范围」后重试。`)
2231
+ const decision = this.authorize(agent, { scope, action: 'write' })
2232
+ if (decision.allowed) return
2233
+ switch (decision.reason) {
2234
+ case 'WRITE_DISABLED':
2235
+ throw memoryError('SCOPE_READ_ONLY', `作用域 ${scope} 在本会话记忆范围里被标记为「不可写」(可读/可写按钮),本次写入/删除没有执行。如需写入,请让用户打开该作用域的「可写」状态。`)
2236
+ case 'SCOPE_DISABLED':
2237
+ throw memoryError('SCOPE_DISABLED', `作用域 ${scope} 已被配置关闭,本次写入/删除没有执行。`)
2238
+ case 'ABSOLUTE_ISOLATION':
2239
+ throw memoryError('SCOPE_NOT_WRITABLE', `作用域 ${scope} 不在本会话可见范围内(限制等级:绝对限制),本次写入/删除没有执行。如需写入,请让用户调整「记忆范围」后重试。`)
2240
+ default:
2241
+ // normal 且作用域不在范围内:工具层会先审批,批准后带 visibilityApproved 再来。
2242
+ throw memoryError('VISIBILITY_APPROVAL_REQUIRED', `作用域 ${scope} 不在本会话的可操作范围内,需要用户审批`)
1903
2243
  }
1904
- throw memoryError('VISIBILITY_APPROVAL_REQUIRED', `作用域 ${scope} 不在本会话的可操作范围内,需要用户审批`)
1905
2244
  }
1906
2245
 
1907
2246
  async save(input ) {
@@ -1958,10 +2297,64 @@ export class LocalMemoryService {
1958
2297
  content = redactSecrets(content)
1959
2298
  }
1960
2299
  }
1961
- const { record } = this.store.save(
1962
- { ...saveInput, scope, content },
1963
- { importance: input.source?.origin === 'auto' ? 0.4 : 0.8, source: { origin: 'explicit' } },
1964
- )
2300
+ // 0.24.0:自定义作用域的“创建”与“普通写入”分开判断。
2301
+ // - Agent 新建自定义作用域必须带 scopeDescription(面板 / 导入等无 agent 路径不受限);
2302
+ // - 元数据存在但 status='pending'(上次初始化半途失败)时继续完成初始化;
2303
+ // - 已有作用域带 scopeDescription = 更新用途,不写初始记忆。
2304
+ const initInput = input
2305
+ const description = normalizeScopeDescription(initInput.scopeDescription)
2306
+ const ruleText = typeof initInput.scopeRule === 'string' ? initInput.scopeRule.trim() : ''
2307
+ const metaBefore = this.meta.get(scope)
2308
+ const newCustom = isCustomScope(scope) && this.store.peek(scope) === undefined && metaBefore === undefined
2309
+ const pendingInit = metaBefore?.status === 'pending'
2310
+ const effectiveDescription = description !== '' ? description : (metaBefore?.description ?? '')
2311
+ const agentWrite = saveAgent !== undefined
2312
+ if ((newCustom || pendingInit) && agentWrite && effectiveDescription === '') {
2313
+ throw memoryError(
2314
+ 'SCOPE_DESCRIPTION_REQUIRED',
2315
+ `新建自定义作用域 ${scope} 必须提供 scopeDescription(一句话说明这个作用域用来做什么)。`,
2316
+ )
2317
+ }
2318
+ if (effectiveDescription.length > MAX_SCOPE_DESCRIPTION_CHARS) {
2319
+ throw memoryError('SCOPE_DESCRIPTION_TOO_LONG', `作用域用途最多 ${MAX_SCOPE_DESCRIPTION_CHARS} 字`)
2320
+ }
2321
+ if (ruleText !== '' && ruleText.length > this.cfg.maxRecordChars) {
2322
+ throw memoryError('SCOPE_RULE_TOO_LONG', `scopeRule 超过 ${this.cfg.maxRecordChars} 字`)
2323
+ }
2324
+ const createdBy = agentWrite ? (this.rawSessionIdOf(saveAgent) ?? 'agent') : 'user'
2325
+ const carryInitial = (input ).initial === true
2326
+ const initialized = (newCustom || pendingInit) && effectiveDescription !== ''
2327
+ if (initialized) {
2328
+ // 先落 pending 元数据:进程在写记录途中退出时,下一次保存能识别并重试,
2329
+ // 目录工具也能看到“这个作用域正在初始化”。
2330
+ this.meta.put(scope, { description: effectiveDescription, createdBy, status: 'pending' })
2331
+ } else if (description !== '' && (metaBefore === undefined || description !== metaBefore.description)) {
2332
+ this.meta.put(scope, { description, createdBy: metaBefore?.createdBy ?? createdBy, status: 'ready' })
2333
+ }
2334
+
2335
+ let record
2336
+ try {
2337
+ const saved = this.store.save(
2338
+ { ...saveInput, scope, content, ...(initialized || carryInitial ? { initial: true } : {}) },
2339
+ { importance: input.source?.origin === 'auto' ? 0.4 : 0.8, source: { origin: 'explicit' } },
2340
+ )
2341
+ record = saved.record
2342
+ // 初始规则:只有初始化流程(新作用域 / 半途重试)才写;普通写入带 scopeRule 不生效。
2343
+ if (initialized && ruleText !== '') {
2344
+ const ruleSaved = this.store.save(
2345
+ { ...saveInput, scope, kind: 'rule', content: ruleText, tags: ['scope-init'], initial: true },
2346
+ { importance: 0.8, source: { origin: 'explicit' } },
2347
+ )
2348
+ void this.embedRecord(ruleSaved.record).catch(() => {})
2349
+ }
2350
+ if (initialized) {
2351
+ this.meta.put(scope, { description: effectiveDescription, createdBy: metaBefore?.createdBy ?? createdBy, status: 'ready' })
2352
+ }
2353
+ } catch (error) {
2354
+ // 保留 pending 元数据(而不是删掉):下一次保存可以接着完成初始化,
2355
+ // 目录工具也能明确看到这个作用域尚未就绪。
2356
+ throw error
2357
+ }
1965
2358
  void this.embedRecord(record).catch(() => {})
1966
2359
  this.store.scheduleFlush()
1967
2360
  return record
@@ -2523,6 +2916,10 @@ export class LocalMemoryService {
2523
2916
  ? input.triggers.map(String)
2524
2917
  : (old ).triggers
2525
2918
  if (Array.isArray(triggers)) (next ).triggers = [...triggers]
2919
+ // 编辑初始记录 = 修正该作用域的“自我介绍”,来源标记要跟着走。
2920
+ if ((old ).initial === true) {
2921
+ ;(next ).initial = true
2922
+ }
2526
2923
  if (input.expiresAt === null) {
2527
2924
  // 显式清除:不设置 expiredAt。
2528
2925
  } else if (typeof input.expiresAt === 'number' && Number.isFinite(input.expiresAt)) {
@@ -2557,6 +2954,8 @@ export class LocalMemoryService {
2557
2954
 
2558
2955
                 
2559
2956
 
2957
+                           
2958
+
2560
2959
 
2561
2960
  {
2562
2961
  this.discoverScopes()
@@ -2575,6 +2974,7 @@ export class LocalMemoryService {
2575
2974
  ? { triggers: ((rec ).triggers ).map(String) }
2576
2975
  : {}),
2577
2976
  ...(rec.expiredAt !== undefined ? { expiredAt: rec.expiredAt } : {}),
2977
+ ...((rec ).initial === true ? { initial: true } : {}),
2578
2978
  })
2579
2979
  }
2580
2980
  }
@@ -2603,7 +3003,7 @@ export class LocalMemoryService {
2603
3003
  try {
2604
3004
  const rec = raw
2605
3005
 
2606
-
3006
+
2607
3007
 
2608
3008
  const content = typeof rec.content === 'string' ? rec.content : ''
2609
3009
  if (content.trim().length === 0) throw new Error('content 为空')
@@ -2623,6 +3023,7 @@ export class LocalMemoryService {
2623
3023
  ...(typeof rec.importance === 'number' ? { importance: rec.importance } : {}),
2624
3024
  ...(Array.isArray(rec.triggers) ? { triggers: rec.triggers.map(String) } : {}),
2625
3025
  ...(typeof rec.expiredAt === 'number' && Number.isFinite(rec.expiredAt) ? { expiresAt: rec.expiredAt } : {}),
3026
+ ...(rec.initial === true ? { initial: true } : {}),
2626
3027
  } )
2627
3028
  imported += 1
2628
3029
  } catch (error) {
@@ -2652,6 +3053,27 @@ export class LocalMemoryService {
2652
3053
  return this.names.nameOf(scope)
2653
3054
  }
2654
3055
 
3056
+ /** 作用域用途等元数据(没有则 undefined;调用方按“未填写用途”处理)。 */
3057
+ scopeMeta(scope ) {
3058
+ return this.meta.get(this.canonicalScope(scope))
3059
+ }
3060
+
3061
+ /**
3062
+ * 写入 / 更新作用域用途。**不会**创建记录,也不触发初始化;给面板与
3063
+ * memory_save 的 scopeDescription 补写用。
3064
+ */
3065
+ describeScope(scope , description , by ) {
3066
+ const key = this.canonicalScope(scope)
3067
+ this.assertScopeAllowed(key)
3068
+ this.assertCustomScopeBudget(key)
3069
+ const text = typeof description === 'string' ? description.replace(/\s+/g, ' ').trim() : ''
3070
+ if (text === '') throw memoryError('SCOPE_DESCRIPTION_EMPTY', '作用域用途不能为空')
3071
+ if (text.length > MAX_SCOPE_DESCRIPTION_CHARS) {
3072
+ throw memoryError('SCOPE_DESCRIPTION_TOO_LONG', `作用域用途最多 ${MAX_SCOPE_DESCRIPTION_CHARS} 字`)
3073
+ }
3074
+ return this.meta.put(key, { description: text, createdBy: by, status: 'ready' })
3075
+ }
3076
+
2655
3077
  /** 名字 → 作用域键:读路径允许直接用别名找作用域。 */
2656
3078
  scopeKeyForName(name ) {
2657
3079
  return this.names.scopeOf(name)
@@ -2695,6 +3117,106 @@ export class LocalMemoryService {
2695
3117
  .sort((a, b) => b.updatedAt - a.updatedAt || b.records - a.records || a.scope.localeCompare(b.scope))
2696
3118
  }
2697
3119
 
3120
+ /**
3121
+ * 作用域目录(memory_scopes list / 未来面板的“作用域”页)。
3122
+ *
3123
+ * 与 `scopeStats()` 的区别:这里回答的是“有哪些作用域、各自干什么、我现在能不能
3124
+ * 读/写/申请”,而不是“每个作用域有多少条”。三条语义写死:
3125
+ * - 没有记录但有元数据的作用域也会出现(删光记录不等于作用域消失);
3126
+ * - 关闭的作用域类型(含 `customEnabled=false`)整条不出现;
3127
+ * - `absolute` 下范围外条目的名字/用途仍可见,但 readable/writable/canRequest*
3128
+ * 全为 false —— 目录可见不等于正文可读,且 absolute 没有审批放行路径。
3129
+ */
3130
+ /**
3131
+ * 作用域初始化记录(`initial: true`)的目录视图。只给 normal / none 用;
3132
+ * absolute 由调用方跳过。正文截断到 800 字,每个作用域最多 3 条。
3133
+ */
3134
+ initialRecordsOf(scope ) {
3135
+ const store = this.store.peek(scope)
3136
+ if (store === undefined) return undefined
3137
+ const out = []
3138
+ for (const record of store.records.values()) {
3139
+ if ((record ).initial !== true) continue
3140
+ const content = record.content.trim()
3141
+ out.push({
3142
+ id: record.id,
3143
+ kind: record.kind,
3144
+ content: content.length > 800 ? `${content.slice(0, 800)}…` : content,
3145
+ ...(content.length > 800 ? { truncated: true } : {}),
3146
+ })
3147
+ if (out.length >= 3) break
3148
+ }
3149
+ return out.length > 0 ? out : undefined
3150
+ }
3151
+
3152
+ scopeCatalog(agent ) {
3153
+ const policy = this.visibilityPolicy(agent)
3154
+ const stats = new Map(this.scopeStats().map((item) => [this.canonicalScope(item.scope), item]))
3155
+ const metas = new Map(this.meta.list().map((item) => [this.canonicalScope(item.scope), item]))
3156
+ const keys = new Set ()
3157
+ for (const scope of this.baseDefaultScopes(agent)) keys.add(this.canonicalScope(scope))
3158
+ for (const scope of this.bindings.get(this.workspaceKeyFor(agent))) keys.add(this.canonicalScope(scope))
3159
+ for (const scope of stats.keys()) keys.add(this.canonicalScope(scope))
3160
+ for (const scope of metas.keys()) keys.add(scope)
3161
+
3162
+ const out = []
3163
+ const evaluate = this.accessEvaluator(agent)
3164
+ for (const scope of keys) {
3165
+ // 目录发现本身也是一条授权判定:作用域类型被关闭时连名字/用途都不出现。
3166
+ if (!evaluate({ scope, action: 'discover' }).allowed) continue
3167
+ const meta = metas.get(scope)
3168
+ const stat = stats.get(scope)
3169
+ const rule = policy.scopes.find((item) => this.canonicalScope(item.scope) === scope)
3170
+ const inScope = policy.level === 'none' || rule !== undefined
3171
+ // 别的会话的 session scope 默认不进目录:它们没有用途、也不该被 Agent 主动申请,
3172
+ // 全列出来只会把目录变成历史会话列表。有元数据(被人描述过)则保留。
3173
+ if (!inScope && meta === undefined && scopeKind(scope) === 'session') continue
3174
+ const readDecision = evaluate({ scope, action: 'read' })
3175
+ const writeDecision = evaluate({ scope, action: 'write' })
3176
+ const readable = readDecision.allowed
3177
+ const writable = writeDecision.allowed
3178
+ // 只有“整个作用域不在范围内”(SCOPE_NOT_IN_RANGE)才可申请;absolute 与
3179
+ // 用户显式关掉的 read/write 都不会 requestable。
3180
+ const canRequestRead = !readable && readDecision.requestable
3181
+ const canRequestWrite = !writable && writeDecision.requestable
3182
+ const accessStatus = !inScope
3183
+ // 范围外但已有会话授权:如实显示“可读 / 可写”,而不是继续标 restricted。
3184
+ ? readable && writable
3185
+ ? 'read-write'
3186
+ : readable
3187
+ ? 'read-only'
3188
+ : 'restricted'
3189
+ : policy.source === 'default'
3190
+ ? 'default'
3191
+ : readable && writable
3192
+ ? 'read-write'
3193
+ : readable
3194
+ ? 'read-only'
3195
+ : 'restricted'
3196
+ const name = meta?.name ?? this.names.nameOf(scope)
3197
+ const initialRecords = policy.level === 'absolute' ? undefined : this.initialRecordsOf(scope)
3198
+ out.push({
3199
+ scope,
3200
+ ...(name !== undefined ? { name } : {}),
3201
+ ...(meta !== undefined ? { description: meta.description } : {}),
3202
+ origin: meta?.origin ?? scopeKind(scope),
3203
+ ...(inScope ? { records: stat?.records ?? 0 } : {}),
3204
+ inScope,
3205
+ readable,
3206
+ writable,
3207
+ canRequestRead,
3208
+ canRequestWrite,
3209
+ accessStatus,
3210
+ updatedAt: stat?.updatedAt ?? meta?.updatedAt ?? 0,
3211
+ ...(initialRecords !== undefined ? { initialRecords } : {}),
3212
+ })
3213
+ }
3214
+ return out.sort((a, b) => Number(b.inScope) - Number(a.inScope)
3215
+ || (b.records ?? 0) - (a.records ?? 0)
3216
+ || b.updatedAt - a.updatedAt
3217
+ || a.scope.localeCompare(b.scope))
3218
+ }
3219
+
2698
3220
  /**
2699
3221
  * 发现磁盘上的 scope(带时间缓存)。面板每次 /status、每次 memory_list 都要一份完整
2700
3222
  * 清单,而 discovery 要读每个文件的第一条记录 —— 限流到最短 3 秒一次,既保证清单够新,
@@ -2884,6 +3406,11 @@ function memoryError(code , message ) {
2884
3406
  return err
2885
3407
  }
2886
3408
 
3409
+ /** 作用域用途统一成一行(与工具的 description 同款收敛口径)。 */
3410
+ function normalizeScopeDescription(raw ) {
3411
+ return typeof raw === 'string' ? raw.replace(/\s+/g, ' ').trim() : ''
3412
+ }
3413
+
2887
3414
  /** discoverScopes() 的最短间隔:清单要够新,但 projects/ 目录不该被读成热路径。 */
2888
3415
  const DISCOVER_TTL_MS = 3000
2889
3416