evolcore 0.0.43-test.2 → 0.0.43-test.3

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.
Files changed (110) hide show
  1. package/CHANGELOG.md +8 -1
  2. package/dist/agents/ecagent-runner.js +13 -6
  3. package/dist/aun/aid/agentmd.js +21 -1
  4. package/dist/aun/msg/p2p.js +4 -2
  5. package/dist/channels/aun.js +79 -48
  6. package/dist/channels/daemon.js +4 -0
  7. package/dist/cli/agent-create.js +3 -5
  8. package/dist/cli/aun-commands.js +17 -19
  9. package/dist/cli/directory.js +101 -56
  10. package/dist/cli/index.js +1 -1
  11. package/dist/cli/peer.js +2 -1
  12. package/dist/cli/task-context.js +3 -1
  13. package/dist/config/access-policy.js +0 -1
  14. package/dist/config/builtin-role-templates.js +2 -2
  15. package/dist/config/builtin-roles.js +2 -1
  16. package/dist/config/config-field-policy.js +5 -0
  17. package/dist/config/config-manager.js +25 -10
  18. package/dist/config/peer-role-resolver.js +23 -1
  19. package/dist/config/role-schema.js +26 -2
  20. package/dist/config/role-service.js +9 -4
  21. package/dist/config/role-store.js +30 -8
  22. package/dist/core/auth/auth-gateway.js +14 -4
  23. package/dist/core/auth/operation-authorizer.js +17 -0
  24. package/dist/core/auth/operation-catalog.js +12 -2
  25. package/dist/core/channel-runtime.js +5 -0
  26. package/dist/core/command/agent-control.js +1 -1
  27. package/dist/core/command/agentmd-menu-request.js +50 -0
  28. package/dist/core/command/agentmd-menu.js +156 -0
  29. package/dist/core/command/command-handler.js +39 -3
  30. package/dist/core/command/menu-catalog.js +13 -0
  31. package/dist/core/command/menu-handler.js +59 -9
  32. package/dist/core/command/menu-protocol.js +8 -0
  33. package/dist/core/command/role-menu.js +23 -9
  34. package/dist/core/command/slash-handler.js +48 -21
  35. package/dist/core/daemon-lifecycle.js +9 -1
  36. package/dist/core/evolagent.js +5 -4
  37. package/dist/core/lifecycle-notice.js +185 -0
  38. package/dist/core/message/aun-ipc-sender.js +30 -24
  39. package/dist/core/message/contact-admission.js +1 -19
  40. package/dist/core/message/im-renderer.js +64 -28
  41. package/dist/core/message/message-admission.js +15 -65
  42. package/dist/core/message/message-bridge.js +18 -5
  43. package/dist/core/message/message-utils.js +9 -0
  44. package/dist/core/message/peer-mode.js +16 -8
  45. package/dist/core/message/response-engine.js +56 -35
  46. package/dist/core/ownership/owner-resolver.js +72 -34
  47. package/dist/core/permission/ec-command-parser.js +24 -10
  48. package/dist/core/relation/pa-team.js +127 -0
  49. package/dist/core/role/runtime-policy.js +4 -3
  50. package/dist/core/thread/thread-service.js +6 -4
  51. package/dist/directory/owner-directory-admission.js +0 -3
  52. package/dist/directory/owner-directory-cache.js +197 -15
  53. package/dist/directory/owner-directory-markdown.js +44 -21
  54. package/dist/directory/owner-directory-policy.js +1 -1
  55. package/dist/directory/owner-directory-query-operation.js +219 -97
  56. package/dist/directory/owner-directory-request-operation.js +76 -0
  57. package/dist/directory/owner-directory-scope.js +35 -4
  58. package/dist/directory/owner-directory-search.js +76 -23
  59. package/dist/directory/owner-directory-store.js +5 -38
  60. package/dist/directory/owner-directory-text.js +60 -0
  61. package/dist/eck/kit-renderer.js +6 -3
  62. package/dist/eck/message-renderer.js +2 -5
  63. package/dist/ecweb/message-context-service.js +4 -0
  64. package/dist/index.js +11 -0
  65. package/dist/paths.js +4 -2
  66. package/dist/product.js +1 -0
  67. package/dist/response-system/engines/v1/index.js +2 -4
  68. package/dist/response-system/modes/single-session/index.js +1 -1
  69. package/dist/trigger/scheduler.js +8 -3
  70. package/dist/utils/error-utils.js +7 -5
  71. package/ecagent/README.md +18 -0
  72. package/ecagent/dist/harness/agent-harness.d.ts +2 -0
  73. package/ecagent/dist/harness/agent-harness.js +24 -8
  74. package/ecagent/dist/harness/compaction/compaction.js +3 -0
  75. package/ecagent/dist/harness/types.d.ts +1 -0
  76. package/kits/docs/channels/aun.md +1 -1
  77. package/kits/docs/context-assembly.md +1 -1
  78. package/kits/docs/evolcore/INDEX.md +4 -1
  79. package/kits/docs/evolcore/directory.md +125 -35
  80. package/kits/docs/evolcore/ecweb-lifecycle.md +26 -0
  81. package/kits/docs/evolcore/file-navigation.md +265 -0
  82. package/kits/docs/evolcore/msg.md +1 -0
  83. package/kits/docs/evolcore/peer.md +2 -1
  84. package/kits/docs/evolcore/response.md +2 -2
  85. package/kits/docs/evolcore/task.md +2 -0
  86. package/kits/docs/evolcore/tool-authorization.md +1 -1
  87. package/kits/docs/identity/ROLE_DETAIL.md +2 -0
  88. package/kits/eck_manifest.json +7 -3
  89. package/kits/eck_manifest.memory.json +26 -1
  90. package/kits/schemas/_meta.json +16 -3
  91. package/kits/schemas/agent-config.schema.20.json +925 -0
  92. package/kits/schemas/relation-config.schema.13.json +289 -0
  93. package/kits/schemas/role-config.schema.3.json +1038 -0
  94. package/kits/schemas/role-registry.schema.1.json +3 -2
  95. package/kits/templates/soul/00-GUIDE.md +20 -42
  96. package/kits/templates/system-fragments/channel.md +2 -2
  97. package/kits/templates/system-fragments/commands.md +1 -1
  98. package/kits/templates/system-fragments/directory-contacts.md +1 -1
  99. package/kits/templates/system-fragments/personal-assistant.md +2 -17
  100. package/kits/templates/system-fragments/reply.md +7 -0
  101. package/kits/templates/system-fragments/session.md +6 -2
  102. package/package.json +2 -2
  103. package/dist/eck/paactive-context.js +0 -45
  104. package/dist/response-system/engines/v1/paactive-flow.js +0 -18
  105. package/kits/eck_manifest.paactive.json +0 -528
  106. package/kits/eck_message_manifest.paactive.json +0 -233
  107. package/kits/templates/message-fragments/paactive/item.md +0 -3
  108. package/kits/templates/system-fragments/paactive/channel.md +0 -25
  109. package/kits/templates/system-fragments/paactive/reply.md +0 -25
  110. package/kits/templates/system-fragments/paactive/session.md +0 -32
@@ -0,0 +1,127 @@
1
+ import { createHash } from 'crypto';
2
+ import { agentmdGet } from '../../aun/aid/agentmd.js';
3
+ import { isValidAid } from '../../aun/aid/validation.js';
4
+ import { parseAgentMdFrontmatter } from './peer-identity.js';
5
+ export const PA_TEAM_MAX_AGE_MS = 30_000;
6
+ const PA_TEAM_TIMEOUT_MS = 8_000;
7
+ const runtimes = new Map();
8
+ const knownTeams = new Map();
9
+ let revision = 0;
10
+ export function registerPaTeamClient(selfAid, client, store) {
11
+ unregisterPaTeamClient(selfAid);
12
+ const peers = knownTeams.get(selfAid) ?? new Set();
13
+ knownTeams.set(selfAid, peers);
14
+ const runtime = { client, store, generation: 0, entries: new Map(), pending: new Map(), knownTeams: peers, subscriptions: [] };
15
+ runtimes.set(selfAid, runtime);
16
+ const invalidate = () => {
17
+ if (runtimes.get(selfAid) !== runtime)
18
+ return;
19
+ runtime.generation++;
20
+ runtime.entries.clear();
21
+ runtime.pending.clear();
22
+ revision++;
23
+ };
24
+ for (const event of ['agentmd.changed', 'storage.object_changed', 'ownership.completed', 'ownership.rejected',
25
+ 'ownership.stopped', 'ownership.error', 'disconnected']) {
26
+ runtime.subscriptions.push(client.on(event, invalidate));
27
+ }
28
+ }
29
+ export function unregisterPaTeamClient(selfAid, client) {
30
+ const runtime = runtimes.get(selfAid);
31
+ if (!runtime || (client && runtime.client !== client))
32
+ return;
33
+ runtimes.delete(selfAid);
34
+ revision++;
35
+ for (const subscription of runtime.subscriptions)
36
+ subscription.unsubscribe();
37
+ }
38
+ export function paTeamQualification(selfAid, peerAid) {
39
+ const runtime = runtimes.get(selfAid);
40
+ const entry = runtime?.entries.get(peerAid);
41
+ return runtime?.client.isReady && entry && entry.expiresAt > Date.now()
42
+ ? entry.qualification : 'unavailable';
43
+ }
44
+ export function paTeamRevision(selfAid) {
45
+ const runtime = runtimes.get(selfAid);
46
+ const entries = [...(runtime?.entries ?? [])].map(([peerAid, entry]) => [peerAid, entry.revision, entry.expiresAt > Date.now()]);
47
+ return JSON.stringify([revision, runtime?.client.isReady === true, entries]);
48
+ }
49
+ export function requiresPaTeamVerification(selfAid, peerAid) {
50
+ return knownTeams.get(selfAid)?.has(peerAid) === true;
51
+ }
52
+ export async function preparePaTeamQualification(selfAid, peerAid) {
53
+ if (!selfAid || !peerAid || selfAid === peerAid || !isValidAid(selfAid) || !isValidAid(peerAid))
54
+ return;
55
+ const runtime = runtimes.get(selfAid);
56
+ if (!runtime?.client.isReady)
57
+ return;
58
+ const cached = runtime.entries.get(peerAid);
59
+ if (cached && cached.expiresAt > Date.now())
60
+ return;
61
+ const pending = runtime.pending.get(peerAid);
62
+ if (pending)
63
+ return pending;
64
+ const generation = runtime.generation;
65
+ const startedAt = Date.now();
66
+ const query = async () => {
67
+ const cards = await Promise.all([selfAid, peerAid].map(aid => agentmdGet(aid, { store: runtime.store, withVerification: true, remoteOnly: true })));
68
+ const profiles = cards.map((card, index) => {
69
+ if (card.source !== 'remote' || card.verification.status !== 'verified')
70
+ throw new Error('Unverified PA profile');
71
+ const profile = parseAgentMdFrontmatter(card.content);
72
+ if (profile.aid !== [selfAid, peerAid][index])
73
+ throw new Error('Mismatched PA profile');
74
+ return profile;
75
+ });
76
+ if (!profiles.every(profile => profile.type === 'agent'
77
+ && typeof profile.exttype === 'string' && /^pa\.[^\s.][^\s]*$/i.test(profile.exttype.trim())))
78
+ return 'unmatched';
79
+ const consensuses = await Promise.all([selfAid, peerAid].map(aid => runtime.client.checkOwnershipConsensus(aid, true)));
80
+ for (const [index, consensus] of consensuses.entries()) {
81
+ const digest = createHash('sha256').update(cards[index].content, 'utf8').digest('hex');
82
+ if (consensus.status !== 'consensus' || consensus.sub_aid !== [selfAid, peerAid][index]
83
+ || consensus.lock !== 'locked' || !consensus.owner_aid || !isValidAid(consensus.owner_aid)
84
+ || !Number.isSafeInteger(consensus.relation_version) || consensus.relation_version < 1
85
+ || consensus.agent_md_sha256 !== digest
86
+ || profiles[index].owner !== consensus.owner_aid)
87
+ return 'unavailable';
88
+ }
89
+ return consensuses[0].owner_aid === consensuses[1].owner_aid ? 'matched' : 'unmatched';
90
+ };
91
+ const task = (async () => {
92
+ let timeout;
93
+ let qualification = 'unavailable';
94
+ try {
95
+ qualification = await Promise.race([query(), new Promise(resolve => {
96
+ timeout = setTimeout(() => resolve('unavailable'), PA_TEAM_TIMEOUT_MS);
97
+ timeout.unref?.();
98
+ })]);
99
+ }
100
+ catch {
101
+ qualification = 'unavailable';
102
+ }
103
+ finally {
104
+ if (timeout)
105
+ clearTimeout(timeout);
106
+ }
107
+ if (runtimes.get(selfAid) !== runtime || runtime.generation !== generation || !runtime.client.isReady)
108
+ return;
109
+ if (qualification === 'matched')
110
+ runtime.knownTeams.add(peerAid);
111
+ if (qualification === 'unmatched')
112
+ runtime.knownTeams.delete(peerAid);
113
+ runtime.entries.set(peerAid, {
114
+ qualification,
115
+ expiresAt: startedAt + (qualification === 'unavailable' ? 2_000 : PA_TEAM_MAX_AGE_MS),
116
+ revision: ++revision,
117
+ });
118
+ })();
119
+ runtime.pending.set(peerAid, task);
120
+ try {
121
+ await task;
122
+ }
123
+ finally {
124
+ if (runtime.pending.get(peerAid) === task)
125
+ runtime.pending.delete(peerAid);
126
+ }
127
+ }
@@ -170,7 +170,8 @@ export function sessionFullAccessStatus(session, principalId) {
170
170
  // takes precedence over any per-main-session or per-topic /fa state.
171
171
  const override = readSessionFullAccessOverride(session);
172
172
  const localEnabled = override?.enabled === true;
173
- const scope = isTopicSession(session) ? 'session' : 'relation';
173
+ const source = isTopicSession(session) ? 'session' : 'relation';
174
+ const scope = source === 'session' ? 'topic-session' : 'relation-main';
174
175
  if (agentStatus.enabled) {
175
176
  return {
176
177
  ...agentStatus, effective: agentStatus.effective && session.chatType === 'private',
@@ -180,7 +181,7 @@ export function sessionFullAccessStatus(session, principalId) {
180
181
  if (!override) {
181
182
  return {
182
183
  enabled: false, eligible: agentStatus.eligible, effective: false,
183
- inherited: false, globalEnabled: false, localEnabled: false, scope, source: scope, mutable: true,
184
+ inherited: false, globalEnabled: false, localEnabled: false, scope, source, mutable: true,
184
185
  };
185
186
  }
186
187
  const eligible = !!session.selfAID && isAgentFullAccessOwner(session.selfAID, principalId);
@@ -193,7 +194,7 @@ export function sessionFullAccessStatus(session, principalId) {
193
194
  globalEnabled: false,
194
195
  localEnabled,
195
196
  scope,
196
- source: scope,
197
+ source,
197
198
  mutable: true,
198
199
  authorizedBy: override.authorizedBy,
199
200
  };
@@ -332,15 +332,17 @@ export class ThreadService {
332
332
  if (entry.name === sanitized)
333
333
  return { changed: false, name: sanitized };
334
334
  const nameUpdatedAt = Math.max(Date.now(), Number(entry.nameUpdatedAt ?? entry.createdAt ?? 0) + 1);
335
+ const session = await this.sessionManager.getThreadSession(entryChannelType(entry), entry.peer, threadId, selfAid);
336
+ if (session) {
337
+ const renamed = await this.sessionManager.renameSession(session.id, sanitized, nameUpdatedAt);
338
+ if (!renamed)
339
+ throw new ThreadServiceError(`话题会话改名失败: ${session.id}`, 'RENAME_FAILED');
340
+ }
335
341
  entry.name = sanitized;
336
342
  entry.nameUpdatedAt = nameUpdatedAt;
337
343
  entry.lastActiveAt = nameUpdatedAt;
338
344
  this.writeThreadIndex(selfAid, index);
339
345
  this.appendThreadSnapshot(selfAid, entry);
340
- const session = await this.sessionManager.getThreadSession(entryChannelType(entry), entry.peer, threadId, selfAid);
341
- if (session) {
342
- await this.sessionManager.renameSession(session.id, sanitized, nameUpdatedAt);
343
- }
344
346
  return { changed: true, name: sanitized, nameUpdatedAt, peerKind: entry.peerKind };
345
347
  }
346
348
  /**
@@ -4,7 +4,6 @@ import { agentDir } from '../paths.js';
4
4
  import { existsAtomic } from '../utils/atomic-write.js';
5
5
  import { ownerResolver } from '../core/ownership/owner-resolver.js';
6
6
  import { logger } from '../utils/logger.js';
7
- import { readAccessPolicy } from '../config/access-policy.js';
8
7
  import { isInternalEntry, ownerRefAid } from './owner-directory-scope.js';
9
8
  import { isPersonalAssistantSnapshot, resolveAllowExternalContacts } from './owner-directory-policy.js';
10
9
  import { OwnerDirectoryCache, OWNER_DIRECTORY_INITIAL_WAIT_MS, OWNER_DIRECTORY_SCOPES, } from './owner-directory-cache.js';
@@ -157,8 +156,6 @@ export async function syncOwnerDirectoryForLookup(selfAid) {
157
156
  }
158
157
  /** Cache misses get one bounded synchronization attempt before admission, using the live channel. */
159
158
  export async function prepareOwnerDirectoryAdmission(selfAid, aid) {
160
- if (readAccessPolicy(selfAid).contactAdmission === 'app-v1')
161
- return;
162
159
  const live = liveDirectories.get(selfAid);
163
160
  if (!live)
164
161
  return;
@@ -53,6 +53,16 @@ const FAILURES_FILE = 'failures.jsonl';
53
53
  /** 失败记录保留条数与字节上限;超出从头丢,只留最近的。 */
54
54
  const FAILURE_KEEP_LINES = 20;
55
55
  const FAILURE_MAX_BYTES = 256 * 1024;
56
+ /**
57
+ * 落地记录:每次把远端内容写进共享缓存都追加一行,回答"为什么变了、变了什么"。
58
+ *
59
+ * 与 `failures.jsonl` 同样是诊断设施,写失败只 warn,不影响同步。
60
+ */
61
+ const LANDING_FILE = 'landing.jsonl';
62
+ const LANDING_KEEP_LINES = 2000;
63
+ const LANDING_MAX_BYTES = 1024 * 1024;
64
+ /** 单行里最多展开多少条条目级差异;再多只记总数。 */
65
+ const LANDING_DIFF_MAX_ENTRIES = 20;
56
66
  /** 连续失败到这个次数就把 WARN 升级成 ERROR,避免"没人看见的一行 WARN"。 */
57
67
  const FAILURE_ESCALATE_AFTER = 3;
58
68
  const MAX_DIRECTORY_ENTRIES = 100_000;
@@ -248,7 +258,7 @@ export class OwnerDirectoryCache {
248
258
  // ── handleOwnerChangedEvent ────────────────────────────────────────────────
249
259
  async handleOwnerChangedEvent(senderAid, digests) {
250
260
  if (senderAid !== this.options.ownerAid) {
251
- throw new OwnerDirectoryCacheError('UNTRUSTED_OWNER_EVENT', 'directory change sender is not the authorized Owner');
261
+ throw new OwnerDirectoryCacheError('UNTRUSTED_OWNER_EVENT', `directory change sender is not the authorized Owner: sender=${senderAid} expected=${this.options.ownerAid}`);
252
262
  }
253
263
  // 每条通知都是独立的变更事件:退避在这里归零,立即重试一次。
254
264
  // 通知本身是有来源保证的(App 对未 ACK 的通知会退避重发),不会造成风暴。
@@ -259,7 +269,10 @@ export class OwnerDirectoryCache {
259
269
  digests: digests ?? {},
260
270
  markedAtMs: this.now(),
261
271
  });
262
- logger.info(`[OwnerDirectoryCache] Pending written for ${this.options.ownerAid}`);
272
+ const hint = Object.entries(digests ?? {})
273
+ .map(([scope, digest]) => `${scope}=${String(digest).slice(0, 8)}`).join(',');
274
+ logger.info(`[OwnerDirectoryCache] Pending written for ${this.options.ownerAid}`
275
+ + ` sender=${senderAid} digests=${hint || 'none'}`);
263
276
  }
264
277
  /** 授权被明确撤销或拒绝时,清掉本地快照,避免继续拿旧数据做准入判断。 */
265
278
  revokeAuthorization(status) {
@@ -311,9 +324,9 @@ export class OwnerDirectoryCache {
311
324
  * 拆开的理由:网络拉取是所有 agent 共享的,落地是每个 agent 自己的,时机和
312
325
  * 代价都不一样——混在一起会让"来一条消息"既可能发网络请求又可能写盘。
313
326
  */
314
- async processPendingIfNeeded() {
327
+ async processPendingIfNeeded(trigger) {
315
328
  if (this.options.relationVersion === undefined)
316
- return this.processPendingOnce();
329
+ return this.processPendingOnce(trigger);
317
330
  if (this.pendingInFlight)
318
331
  return this.pendingInFlight;
319
332
  const run = (async () => {
@@ -321,7 +334,7 @@ export class OwnerDirectoryCache {
321
334
  const before = this.readPendingUpdate();
322
335
  if (!before || (this.options.isCurrent && !this.options.isCurrent()))
323
336
  return;
324
- await this.processPendingOnce();
337
+ await this.processPendingOnce(trigger);
325
338
  const after = this.readPendingUpdate();
326
339
  if (!after || (after.operationId === before.operationId && after.markedAtMs === before.markedAtMs))
327
340
  return;
@@ -336,7 +349,7 @@ export class OwnerDirectoryCache {
336
349
  this.pendingInFlight = undefined;
337
350
  }
338
351
  }
339
- async processPendingOnce() {
352
+ async processPendingOnce(trigger) {
340
353
  const pending = this.readPendingUpdate();
341
354
  if (!pending)
342
355
  return;
@@ -348,7 +361,9 @@ export class OwnerDirectoryCache {
348
361
  }
349
362
  logger.info(`[OwnerDirectoryCache] Processing pending for ${this.options.ownerAid}, op=${pending.operationId}, attempt=${this.pullFailures + 1}`);
350
363
  try {
351
- const fetched = await this.fetchToSharedCache(pending.digests);
364
+ const fetched = await this.fetchToSharedCache(pending.digests,
365
+ // 调用方知道得更准(grant 之后的首次拉取、启动补拉);否则按标记来源推断。
366
+ trigger ?? (pending.operationId.startsWith('notification-') ? 'notification' : 'startup'), pending.operationId);
352
367
  if (this.options.relationVersion !== undefined)
353
368
  await this._applyAll(fetched);
354
369
  this.clearPullFailures();
@@ -416,7 +431,7 @@ export class OwnerDirectoryCache {
416
431
  * 写盘失败只 warn 不抛(共享缓存坏了下一次会重写);返回的是本次拿到的数据,
417
432
  * 即使共享缓存写失败,调用方仍可据此落地。
418
433
  */
419
- async fetchToSharedCache(digests) {
434
+ async fetchToSharedCache(digests, trigger = 'unspecified', operationId) {
420
435
  // ① 检查共享缓存:通知 digest 与共享缓存一致时,跳过网络请求
421
436
  const sharedFresh = this.options.relationVersion === undefined && OWNER_DIRECTORY_SCOPES.every(scope => {
422
437
  const hintDigest = digests?.[scope];
@@ -436,9 +451,13 @@ export class OwnerDirectoryCache {
436
451
  const outcome = existing
437
452
  ? await existing
438
453
  : await (() => {
454
+ const startedAt = this.now();
439
455
  const fetchPromise = this._doFetch().then(result => {
440
- if (this.options.relationVersion === undefined && (!this.options.isCurrent || this.options.isCurrent()))
441
- this._writeSharedCache(result.data);
456
+ // 关系级共享缓存由「拉取方替其他 agent 写」;单 owner 目录只写自己的。
457
+ // 两条分支都要带 trigger / operationId,落地记录才回答得出"这次是谁触发的"。
458
+ if (this.options.relationVersion === undefined && (!this.options.isCurrent || this.options.isCurrent())) {
459
+ this._writeSharedCache(result.data, trigger, operationId, startedAt);
460
+ }
442
461
  return result;
443
462
  }).finally(() => {
444
463
  if (_fetchInFlight.get(flightKey) === fetchPromise) {
@@ -564,9 +583,9 @@ export class OwnerDirectoryCache {
564
583
  *
565
584
  * 需求路径(`lookupByAid`、准入)用这个:用户正等着结果,不能只拉不落。
566
585
  */
567
- async pullAndApply(digests) {
586
+ async pullAndApply(digests, trigger = 'unspecified') {
568
587
  const generation = ++this.fetchGeneration;
569
- const fetched = await this.fetchToSharedCache(digests);
588
+ const fetched = await this.fetchToSharedCache(digests, trigger);
570
589
  if (generation !== this.fetchGeneration)
571
590
  return;
572
591
  await this._applyAll(fetched);
@@ -677,7 +696,7 @@ export class OwnerDirectoryCache {
677
696
  * 和 `cmp` 都能直接对,排查时不用再区分"到底哪一份是真的"。本地需要的
678
697
  * 元数据(摘要、条数、时间)全部从字节和文档自身推导,不再另存一份。
679
698
  */
680
- _writeSharedCache(data) {
699
+ _writeSharedCache(data, trigger = 'unspecified', operationId, startedAt) {
681
700
  try {
682
701
  const dir = this._sharedCacheDir();
683
702
  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -685,6 +704,8 @@ export class OwnerDirectoryCache {
685
704
  const file = data[scope];
686
705
  if (!file)
687
706
  continue;
707
+ // 覆盖前先读出旧文件:落地记录要回答"变了什么",而旧字节马上就没了。
708
+ const prev = this._readSharedCacheDocumentSafely(scope);
688
709
  const target = this._sharedCachePath(scope);
689
710
  atomicWriteBytes(target, file.bytes);
690
711
  fs.chmodSync(target, 0o600);
@@ -698,12 +719,86 @@ export class OwnerDirectoryCache {
698
719
  logger.debug(`[OwnerDirectoryCache] utimes ${scope} failed: ${errorText(error)}`);
699
720
  }
700
721
  }
722
+ this._recordLanding(scope, file, prev, trigger, operationId, startedAt);
701
723
  }
702
724
  }
703
725
  catch (error) {
704
726
  logger.warn(`[OwnerDirectoryCache] Failed to write shared cache: ${errorText(error)}`);
705
727
  }
706
728
  }
729
+ /** 读旧共享缓存;不存在或已损坏都返回 undefined,不影响本次落地。 */
730
+ _readSharedCacheDocumentSafely(scope) {
731
+ try {
732
+ const stored = this._readSharedCacheDocument(scope);
733
+ if (!stored)
734
+ return undefined;
735
+ return {
736
+ file: this.parseDirectoryObject(stored.parsed, stored.bytes, stored.sha256, scope, {
737
+ storageUpdatedAtMs: mtimeOf(this._sharedCachePath(scope)),
738
+ }),
739
+ };
740
+ }
741
+ catch {
742
+ return undefined;
743
+ }
744
+ }
745
+ /**
746
+ * 落地后追加一行 `landing.jsonl`,并在内容变化时把摘要、差异和回退迹象一起写进去。
747
+ *
748
+ * 这条记录的唯一职责是回答事后问题:"这次写盘是谁触发的、摘要从哪变到哪、
749
+ * 具体变了哪些条目"。所以它不参与任何判定,失败也只 warn。
750
+ */
751
+ _recordLanding(scope, file, prev, trigger, operationId, startedAt) {
752
+ try {
753
+ const digest = file.contentDigest ?? '';
754
+ const prevDigest = prev?.file.contentDigest;
755
+ const changed = !!digest && digest !== prevDigest;
756
+ const record = {
757
+ at: this.now(),
758
+ scope,
759
+ trigger,
760
+ ...(operationId ? { operationId } : {}),
761
+ digest,
762
+ ...(prevDigest ? { prevDigest } : {}),
763
+ changed,
764
+ ...(typeof file.raw.source_revision === 'string' ? { sourceRevision: file.raw.source_revision } : {}),
765
+ ...(file.updatedAtMs !== undefined ? { updatedAtMs: file.updatedAtMs } : {}),
766
+ bytes: file.bytes.byteLength,
767
+ sha256: file.sha256,
768
+ ...(startedAt !== undefined ? { durationMs: Math.max(0, this.now() - startedAt) } : {}),
769
+ };
770
+ let summary = '';
771
+ if (changed && prev) {
772
+ const { diff, total, regressions } = diffLandingEntries(prev.file.entries, file.entries);
773
+ if (diff.length > 0) {
774
+ record.diff = diff.slice(0, LANDING_DIFF_MAX_ENTRIES);
775
+ record.diffTotal = total;
776
+ }
777
+ if (regressions.length > 0) {
778
+ record.warn = 'regression';
779
+ summary = ` (${regressions.slice(0, 3).join('; ')})`;
780
+ }
781
+ }
782
+ this._appendLandingLine(record);
783
+ logger.info(`[OwnerDirectoryCache] Landed ${scope}: trigger=${trigger} digest=`
784
+ + `${(prevDigest ?? 'none').slice(0, 8)}→${digest.slice(0, 8)} changed=${changed}${summary}`);
785
+ }
786
+ catch (error) {
787
+ logger.warn(`[OwnerDirectoryCache] Failed to record landing for ${scope}: ${errorText(error)}`);
788
+ }
789
+ }
790
+ /** 追加并滚动 `landing.jsonl`;与 `failures.jsonl` 同一套行数/字节双上限。 */
791
+ _appendLandingLine(record) {
792
+ const target = path.join(this._sharedCacheDir(), LANDING_FILE);
793
+ const previous = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : '';
794
+ const lines = previous.split('\n').filter(Boolean);
795
+ lines.push(JSON.stringify(record));
796
+ const kept = lines.slice(-LANDING_KEEP_LINES);
797
+ while (kept.length > 1 && Buffer.byteLength(kept.join('\n'), 'utf8') > LANDING_MAX_BYTES)
798
+ kept.shift();
799
+ atomicWriteText(target, `${kept.join('\n')}\n`);
800
+ fs.chmodSync(target, 0o600);
801
+ }
707
802
  // ── readSnapshot / lookupByAid ─────────────────────────────────────────────
708
803
  readSnapshot(scope) {
709
804
  if (!isOwnerDirectoryScope(scope))
@@ -722,7 +817,7 @@ export class OwnerDirectoryCache {
722
817
  // 需求路径必须"拉 + 落"一次做完:调用方在等这个结果,
723
818
  // 只更新共享缓存的话本地快照还是旧的,刚加的人照样查不到。
724
819
  const pending = this.readPendingUpdate();
725
- await this.pullAndApply(pending?.digests);
820
+ await this.pullAndApply(pending?.digests, 'lookup');
726
821
  // 这次拉取已经覆盖了 pending 的内容,标记可以清了;否则下一条消息
727
822
  // 会拿同一批 digest 再走一遍拉取路径。失败时不清,交给退避重试。
728
823
  if (pending)
@@ -1069,6 +1164,9 @@ export class OwnerDirectoryCache {
1069
1164
  snapshotId: snapshot.snapshotId,
1070
1165
  status: 'ready',
1071
1166
  error: undefined,
1167
+ // 成功即清零:否则 `status: ready` 与 `failureCount: 3` 并存,
1168
+ // 事后把这个状态文件当证据的人会被误导。
1169
+ failureCount: 0,
1072
1170
  });
1073
1171
  this.refreshMarkdown();
1074
1172
  try {
@@ -1569,7 +1667,91 @@ export function extraFingerprint(value) {
1569
1667
  return '';
1570
1668
  return JSON.stringify(keys.map(key => [key, value[key] ?? null]));
1571
1669
  }
1572
- /** 按码位截断,避免把代理对劈成半个字符。 */
1670
+ /**
1671
+ * 落地记录里的条目级差异。
1672
+ *
1673
+ * 不能复用 store 的 `diffSnapshots`:store 依赖本模块,反向引用会形成运行时循环,
1674
+ * 而这条路径在每次落地时都会走到。比较口径由 `changedEntryFields` 决定,
1675
+ * 与 `entry_changed` 的行生成是同一份定义。
1676
+ *
1677
+ * 旧条目可能来自更早的版本或已经损坏,`normalizeEntry` 抛错时整条跳过——落地
1678
+ * 记录是诊断设施,不能因为它读不懂旧文件就让写盘失败。
1679
+ *
1680
+ * `regressions` 单独列出"同一个 aid 的 `agent_md_signed_at` 变小"这种反常形态。
1681
+ * 上游两个源交替发布时 `updated_at_ms` 照常前进、内容却退回去,这是唯一能看出来的地方。
1682
+ */
1683
+ function diffLandingEntries(prevEntries, nextEntries) {
1684
+ const normalize = (list) => {
1685
+ const out = new Map();
1686
+ for (const raw of list) {
1687
+ try {
1688
+ const entry = normalizeEntry(raw);
1689
+ out.set(entry.aid, entry);
1690
+ }
1691
+ catch { /* 旧条目读不懂就跳过 */ }
1692
+ }
1693
+ return out;
1694
+ };
1695
+ const prev = normalize(prevEntries);
1696
+ const next = normalize(nextEntries);
1697
+ const diff = [];
1698
+ const regressions = [];
1699
+ for (const [aid, entry] of next) {
1700
+ const before = prev.get(aid);
1701
+ if (!before) {
1702
+ diff.push({ aid, kind: 'added' });
1703
+ continue;
1704
+ }
1705
+ const a = before.agent_md_signed_at, b = entry.agent_md_signed_at;
1706
+ if (a !== undefined && b !== undefined && b < a) {
1707
+ regressions.push(`${aid}: agent_md_signed_at ${a}→${b}`);
1708
+ }
1709
+ const fields = changedEntryFields(before, entry);
1710
+ if (fields.length > 0)
1711
+ diff.push({ aid, kind: 'changed', fields });
1712
+ }
1713
+ for (const aid of prev.keys()) {
1714
+ if (!next.has(aid))
1715
+ diff.push({ aid, kind: 'removed' });
1716
+ }
1717
+ return { diff, total: diff.length, regressions };
1718
+ }
1719
+ /**
1720
+ * 条目内容的可变字段。这是"什么算变了"的唯一定义:`entry_changed` 的判定、
1721
+ * 变更行里的 `fields` 都从这里出,不另写一份。
1722
+ *
1723
+ * `ownership_checked_at_ms` 不在其中——它是探测时间而不是内容。
1724
+ * `ownerAid` 也不在:上游对它的有无本身在抖,纳进来只会制造噪音;内外归属变化
1725
+ * 会体现在 `ownership_status` 上。
1726
+ */
1727
+ export const DIRECTORY_CONTENT_FIELDS = [
1728
+ 'name', 'remark', 'description', 'type', 'exttype', 'baseagent', 'ownership_status',
1729
+ ];
1730
+ /**
1731
+ * 条目内容相对旧值的差异字段。空数组 = 没有实际变化。
1732
+ *
1733
+ * 缺失与空串视为等价:normalizeEntry 已经把恒存在的字符串字段收敛成恒 `''`,
1734
+ * 但本地快照可能来自更早的版本(字段缺失),这里再兜一层。这同时是运行期自检——
1735
+ * 无论上游把可选字段写成 `""`、`null` 还是不写,只要业务值相同就不会进日志。
1736
+ */
1737
+ export function changedEntryFields(a, b) {
1738
+ const changed = [];
1739
+ for (const key of DIRECTORY_CONTENT_FIELDS) {
1740
+ if (text(a[key]) !== text(b[key]))
1741
+ changed.push(key);
1742
+ }
1743
+ if (a.agent_md_signed_at !== b.agent_md_signed_at)
1744
+ changed.push('agent_md_signed_at');
1745
+ // 未知字段(`extra`)单独比:它是 key→值 的映射,按规范化指纹比较,
1746
+ // 字段顺序不同不算变化。远端新增一个字段却没有任何 `DIRECTORY_CONTENT_FIELDS` 变化时,
1747
+ // 变更日志里只会有这一条线索,不能漏。
1748
+ if (extraFingerprint(a.extra) !== extraFingerprint(b.extra))
1749
+ changed.push('extra');
1750
+ return changed;
1751
+ }
1752
+ function text(value) {
1753
+ return value ?? '';
1754
+ }
1573
1755
  function truncateCodePoints(text, max) {
1574
1756
  if (text.length <= max)
1575
1757
  return text;