evolcore 0.0.43-test.1 → 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 (200) hide show
  1. package/CHANGELOG.md +31 -1
  2. package/README.md +22 -0
  3. package/dist/agents/claude-runner.js +26 -2
  4. package/dist/agents/codex/app-server-client.js +12 -0
  5. package/dist/agents/codex-runner.js +49 -8
  6. package/dist/agents/ecagent-runner.js +39 -15
  7. package/dist/agents/gemini-runner.js +15 -12
  8. package/dist/agents/tool-time-context.js +55 -0
  9. package/dist/aun/aid/agentmd.js +21 -1
  10. package/dist/aun/menu/client.js +1 -1
  11. package/dist/aun/model-headers.js +17 -0
  12. package/dist/aun/msg/p2p.js +7 -2
  13. package/dist/channels/aun.js +522 -50
  14. package/dist/channels/builtin-plugins.js +16 -11
  15. package/dist/channels/daemon.js +4 -0
  16. package/dist/channels/dingtalk.js +83 -31
  17. package/dist/channels/feishu.js +29 -13
  18. package/dist/channels/qqbot.js +32 -11
  19. package/dist/channels/wechat.js +13 -3
  20. package/dist/channels/wecom.js +67 -27
  21. package/dist/cli/agent-command.js +3 -86
  22. package/dist/cli/agent-create.js +20 -6
  23. package/dist/cli/agent.js +1 -79
  24. package/dist/cli/aun-commands.js +18 -19
  25. package/dist/cli/config.js +1 -1
  26. package/dist/cli/daemon-commands.js +47 -2
  27. package/dist/cli/data-command.js +9 -1
  28. package/dist/cli/debug-mode.js +1 -1
  29. package/dist/cli/diag.js +1 -1
  30. package/dist/cli/directory.js +149 -91
  31. package/dist/cli/getmeta-command.js +1 -1
  32. package/dist/cli/index.js +79 -22
  33. package/dist/cli/init.js +1 -23
  34. package/dist/cli/link-rules.js +1 -1
  35. package/dist/cli/managed-command-guard.js +0 -1
  36. package/dist/cli/pa-workspace-command.js +36 -2
  37. package/dist/cli/peer.js +3 -2
  38. package/dist/cli/restart-monitor.js +17 -3
  39. package/dist/cli/role.js +1 -1
  40. package/dist/cli/session-command.js +1 -1
  41. package/dist/cli/stats.js +2 -2
  42. package/dist/cli/task-context.js +3 -1
  43. package/dist/cli/thread-command.js +1 -1
  44. package/dist/cli/watch-msg.js +1 -1
  45. package/dist/config/builtin-role-templates.js +2 -2
  46. package/dist/config/builtin-roles.js +2 -1
  47. package/dist/config/config-field-policy.js +7 -2
  48. package/dist/config/config-manager.js +32 -10
  49. package/dist/config/peer-role-resolver.js +23 -1
  50. package/dist/config/role-schema.js +29 -4
  51. package/dist/config/role-service.js +12 -7
  52. package/dist/config/role-store.js +30 -8
  53. package/dist/config-store.js +75 -4
  54. package/dist/core/agent-ipc-registration.js +16 -59
  55. package/dist/core/auth/auth-gateway.js +14 -4
  56. package/dist/core/auth/authorization-audit.js +52 -14
  57. package/dist/core/auth/operation-authorizer.js +17 -11
  58. package/dist/core/auth/operation-catalog.js +5 -13
  59. package/dist/core/channel-loader.js +152 -16
  60. package/dist/core/channel-runtime.js +5 -0
  61. package/dist/core/command/agent-control.js +2 -1
  62. package/dist/core/command/agentmd-menu-request.js +50 -0
  63. package/dist/core/command/agentmd-menu.js +156 -0
  64. package/dist/core/command/cli-intent-parser.js +0 -8
  65. package/dist/core/command/command-handler.js +47 -40
  66. package/dist/core/command/connect-menu.js +7 -3
  67. package/dist/core/command/menu-catalog.js +16 -2
  68. package/dist/core/command/menu-handler.js +107 -14
  69. package/dist/core/command/menu-protocol.js +28 -0
  70. package/dist/core/command/role-menu.js +23 -9
  71. package/dist/core/command/slash-handler.js +139 -51
  72. package/dist/core/daemon-file-cache.js +3 -3
  73. package/dist/core/daemon-lifecycle.js +9 -1
  74. package/dist/core/evolagent-registry.js +5 -4
  75. package/dist/core/evolagent.js +10 -12
  76. package/dist/core/handoff/argv-parse.js +115 -0
  77. package/dist/core/handoff/ipc-registration.js +1 -1
  78. package/dist/core/ipc-registration.js +19 -2
  79. package/dist/core/lifecycle-notice.js +185 -0
  80. package/dist/core/memory/consolidation.js +8 -1
  81. package/dist/core/memory/relation-sweep.js +20 -8
  82. package/dist/core/message/aun-ipc-sender.js +35 -2
  83. package/dist/core/message/contact-admission.js +530 -0
  84. package/dist/core/message/im-renderer.js +111 -16
  85. package/dist/core/message/message-admission.js +29 -54
  86. package/dist/core/message/message-bridge.js +62 -8
  87. package/dist/core/message/message-utils.js +9 -5
  88. package/dist/core/message/peer-mode.js +55 -13
  89. package/dist/core/message/response-engine.js +298 -78
  90. package/dist/core/message/retry-scheduler.js +4 -0
  91. package/dist/core/ownership/owner-resolver.js +72 -34
  92. package/dist/core/permission/ec-command-parser.js +25 -38
  93. package/dist/core/permission/readonly-shell-query.js +34 -8
  94. package/dist/core/permission/tool-policy.js +50 -5
  95. package/dist/core/relation/pa-team.js +127 -0
  96. package/dist/core/role/runtime-policy.js +18 -5
  97. package/dist/core/session/session-manager.js +9 -1
  98. package/dist/core/soul.js +66 -0
  99. package/dist/core/system-session/memory.js +2 -2
  100. package/dist/core/thread/thread-service.js +6 -4
  101. package/dist/directory/contact-admission-paths.js +9 -0
  102. package/dist/directory/owner-directory-admission.js +125 -29
  103. package/dist/directory/owner-directory-cache.js +554 -58
  104. package/dist/directory/owner-directory-identity.js +60 -0
  105. package/dist/directory/owner-directory-markdown.js +154 -58
  106. package/dist/directory/owner-directory-policy.js +108 -0
  107. package/dist/directory/owner-directory-query-operation.js +399 -90
  108. package/dist/directory/owner-directory-remarks.js +29 -2
  109. package/dist/directory/owner-directory-request-operation.js +76 -0
  110. package/dist/directory/owner-directory-scope.js +35 -4
  111. package/dist/directory/owner-directory-search.js +118 -33
  112. package/dist/directory/owner-directory-store.js +117 -30
  113. package/dist/directory/owner-directory-text.js +60 -0
  114. package/dist/eck/kit-renderer.js +18 -8
  115. package/dist/eck/manifest-engine.js +55 -6
  116. package/dist/ecweb/basic-settings-service.js +2 -2
  117. package/dist/ecweb/message-context-service.js +28 -16
  118. package/dist/index.js +20 -5
  119. package/dist/ipc.js +1 -1
  120. package/dist/paths.js +29 -1
  121. package/dist/product.js +1 -0
  122. package/dist/response-system/config-resolver.js +1 -1
  123. package/dist/response-system/engines/v1/index.js +2 -1
  124. package/dist/response-system/modes/single-session/index.js +7 -2
  125. package/dist/trigger/scheduler.js +7 -4
  126. package/dist/trigger/validation.js +4 -0
  127. package/dist/utils/error-utils.js +12 -7
  128. package/dist/utils/logger.js +13 -4
  129. package/dist/utils/npm-ops.js +2 -2
  130. package/dist/utils/windows-autostart.js +1 -1
  131. package/ecagent/README.md +18 -0
  132. package/ecagent/dist/agent-loop.js +43 -1
  133. package/ecagent/dist/harness/agent-harness.d.ts +2 -0
  134. package/ecagent/dist/harness/agent-harness.js +24 -8
  135. package/ecagent/dist/harness/compaction/compaction.js +3 -0
  136. package/ecagent/dist/harness/types.d.ts +1 -0
  137. package/kits/docs/INDEX.md +1 -0
  138. package/kits/docs/channels/aun.md +1 -1
  139. package/kits/docs/context-assembly.md +21 -6
  140. package/kits/docs/eck_templates/INDEX.template.md +1 -2
  141. package/kits/docs/evolcore/INDEX.md +4 -1
  142. package/kits/docs/evolcore/agent-create.md +5 -5
  143. package/kits/docs/evolcore/agent.md +4 -9
  144. package/kits/docs/evolcore/directory.md +227 -0
  145. package/kits/docs/evolcore/ecweb-lifecycle.md +26 -0
  146. package/kits/docs/evolcore/file-navigation.md +265 -0
  147. package/kits/docs/evolcore/menu-protocol.md +55 -0
  148. package/kits/docs/evolcore/msg.md +1 -0
  149. package/kits/docs/evolcore/peer.md +2 -1
  150. package/kits/docs/evolcore/response.md +7 -1
  151. package/kits/docs/evolcore/task.md +2 -0
  152. package/kits/docs/evolcore/tool-authorization.md +1 -1
  153. package/kits/docs/evolcore/trigger.md +4 -0
  154. package/kits/docs/identity/ROLE_DETAIL.md +2 -0
  155. package/kits/docs/prompt-loading-architecture.md +6 -2
  156. package/kits/eck_manifest.auxiliary.json +1 -0
  157. package/kits/eck_manifest.json +64 -7
  158. package/kits/eck_manifest.memory.json +93 -4
  159. package/kits/rules/01-overview.md +2 -2
  160. package/kits/rules/03-identity.md +10 -9
  161. package/kits/rules/05-venue.md +2 -4
  162. package/kits/rules/06-channel.md +1 -1
  163. package/kits/schemas/_meta.json +44 -3
  164. package/kits/schemas/agent-config.schema.18.json +5 -0
  165. package/kits/schemas/agent-config.schema.19.json +924 -0
  166. package/kits/schemas/agent-config.schema.20.json +925 -0
  167. package/kits/schemas/relation-config.schema.12.json +289 -0
  168. package/kits/schemas/relation-config.schema.13.json +289 -0
  169. package/kits/schemas/role-config.schema.2.json +215 -0
  170. package/kits/schemas/role-config.schema.3.json +1038 -0
  171. package/kits/schemas/role-registry.schema.1.json +3 -2
  172. package/kits/skills/ec-skill/scripts/cli.mjs +3 -2
  173. package/kits/skills/ec-trigger/SKILL.md +4 -4
  174. package/kits/skills/personal-assistant/SKILL.md +109 -53
  175. package/kits/skills/personal-assistant/references/02-bootstrap.md +73 -30
  176. package/kits/skills/personal-assistant/scripts/clean.mjs +35 -18
  177. package/kits/skills/personal-assistant/scripts/init.mjs +41 -2
  178. package/kits/skills/personal-assistant/scripts/lib/persona.mjs +185 -0
  179. package/kits/skills/personal-assistant/scripts/migrate.mjs +55 -4
  180. package/kits/skills/personal-assistant/scripts/pa.mjs +173 -0
  181. package/kits/skills/personal-assistant/scripts/uninstall.mjs +130 -0
  182. package/kits/skills/personal-assistant/templates/persona-section.md +3 -3
  183. package/kits/templates/message-fragments/handoff-request-to-target.md +1 -1
  184. package/kits/templates/soul/00-GUIDE.md +39 -0
  185. package/kits/templates/soul/01-identity.md +5 -0
  186. package/kits/templates/soul/02-persona.md +11 -0
  187. package/kits/templates/soul/03-duties.md +5 -0
  188. package/kits/templates/soul/04-working-style.md +5 -0
  189. package/kits/templates/system-fragments/bootstrap.md +7 -7
  190. package/kits/templates/system-fragments/channel.md +2 -2
  191. package/kits/templates/system-fragments/commands.md +3 -2
  192. package/kits/templates/system-fragments/directory-contacts.md +9 -0
  193. package/kits/templates/system-fragments/memory.md +1 -1
  194. package/kits/templates/system-fragments/personal-assistant.md +50 -0
  195. package/kits/templates/system-fragments/reply.md +7 -0
  196. package/kits/templates/system-fragments/session.md +6 -2
  197. package/package.json +3 -2
  198. package/dist/cli/handoff-command.js +0 -353
  199. package/dist/directory/owner-directory-remark-operation.js +0 -147
  200. package/kits/docs/evolcore/self-summary.md +0 -29
@@ -4,10 +4,13 @@ import { createHash, randomUUID } from 'node:crypto';
4
4
  import { isValidAid } from '../aun/aid/validation.js';
5
5
  import { normalizeGroupAid } from '../aun/group/identity.js';
6
6
  import { readAuthoritativePersonalFsObject } from '../aun/group/fs-download.js';
7
- import { atomicRead, atomicReadBytes, atomicReadJson, atomicRemove, atomicWriteBytes, atomicWriteJson, atomicWriteText, existsAtomic } from '../utils/atomic-write.js';
7
+ import { atomicRead, atomicReadBytes, atomicRemove, atomicWriteBytes, atomicWriteJson, atomicWriteText, existsAtomic } from '../utils/atomic-write.js';
8
8
  import { logger } from '../utils/logger.js';
9
9
  import { resolveRoot } from '../paths.js';
10
+ import { contactAdmissionDirectory } from './contact-admission-paths.js';
10
11
  import { OWNER_DIRECTORY_MARKDOWN_FILE, renderOwnerDirectoryMarkdown } from './owner-directory-markdown.js';
12
+ import { OWNER_DIRECTORY_IDENTITY_FILE, buildOwnerDirectoryIdentity } from './owner-directory-identity.js';
13
+ import { resolveOwnerDirectoryRenderPolicy } from './owner-directory-policy.js';
11
14
  import { directoryContentDigest } from './canonical-digest.js';
12
15
  import { readAllRemarks, OWNER_DIRECTORY_REMARKS_DIR } from './owner-directory-remarks.js';
13
16
  import { archiveSnapshot, appendChanges, diffSnapshots, collectAgentMdRefreshAids, isValidContentDigest, } from './owner-directory-store.js';
@@ -50,6 +53,16 @@ const FAILURES_FILE = 'failures.jsonl';
50
53
  /** 失败记录保留条数与字节上限;超出从头丢,只留最近的。 */
51
54
  const FAILURE_KEEP_LINES = 20;
52
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;
53
66
  /** 连续失败到这个次数就把 WARN 升级成 ERROR,避免"没人看见的一行 WARN"。 */
54
67
  const FAILURE_ESCALATE_AFTER = 3;
55
68
  const MAX_DIRECTORY_ENTRIES = 100_000;
@@ -87,6 +100,9 @@ export class OwnerDirectoryCacheError extends Error {
87
100
  /** Per-Agent durable snapshots plus the derived directory.md that ECK loads. */
88
101
  export class OwnerDirectoryCache {
89
102
  options;
103
+ pendingInFlight;
104
+ applyTail = Promise.resolve();
105
+ fetchGeneration = 0;
90
106
  now;
91
107
  /**
92
108
  * 落地单飞。消息并发进来时,后到的调用方复用同一轮落地,而不是各自再跑一遍
@@ -120,12 +136,50 @@ export class OwnerDirectoryCache {
120
136
  this.now = options.now ?? Date.now;
121
137
  }
122
138
  // ── Authorization ───────────────────────────────────────────────────────────
139
+ /** A retired runtime must never mutate the current relation's shared files. */
140
+ canMutate() {
141
+ if (this.options.isCurrent && !this.options.isCurrent())
142
+ return false;
143
+ const version = this.options.relationVersion;
144
+ for (const file of [path.join(contactAdmissionDirectory(this.options.selfAid), 'binding.json'), this.authorizationPath(), this.cachePath('contacts')]) {
145
+ let raw;
146
+ try {
147
+ raw = JSON.parse(fs.readFileSync(file, 'utf8'));
148
+ }
149
+ catch (error) {
150
+ if (error.code === 'ENOENT')
151
+ continue;
152
+ return false;
153
+ }
154
+ // A newer disk generation is authoritative even for standalone cache users.
155
+ if (version === undefined && raw.relationVersion !== undefined)
156
+ return false;
157
+ if (version !== undefined && typeof raw.relationVersion === 'number' && raw.relationVersion > version)
158
+ return false;
159
+ if (raw.ownerAid !== this.options.ownerAid && (!this.options.isCurrent || !this.options.isCurrent()))
160
+ return false;
161
+ }
162
+ return true;
163
+ }
164
+ /** Local probes must not remove another runtime's in-progress atomic write. */
165
+ readLocalJson(file) {
166
+ try {
167
+ return JSON.parse(fs.readFileSync(file, 'utf8'));
168
+ }
169
+ catch (error) {
170
+ if (error.code === 'ENOENT')
171
+ return undefined;
172
+ throw error;
173
+ }
174
+ }
123
175
  /**
124
176
  * 记录 Owner 的授权。只保留"能不能读、读到什么时候"。
125
177
  *
126
178
  * 收到新授权意味着重新开始:失败计数清零,之前被拉黑的范围一并解除。
127
179
  */
128
180
  saveAuthorization(result) {
181
+ if (!this.canMutate())
182
+ return;
129
183
  logger.info(`[OwnerDirectoryCache] Saving authorization for Owner ${this.options.ownerAid}, status: ${result.status}`);
130
184
  if (result.owner_aid !== this.options.ownerAid || result.grantee_aid !== this.options.selfAid) {
131
185
  throw new OwnerDirectoryCacheError('INVALID_GRANT', 'directory/access result identity is invalid');
@@ -133,6 +187,11 @@ export class OwnerDirectoryCache {
133
187
  if (!GRANT_STATUSES.has(result.status)) {
134
188
  throw new OwnerDirectoryCacheError('INVALID_GRANT', 'directory/access status is invalid');
135
189
  }
190
+ if (this.options.relationVersion !== undefined) {
191
+ const marker = path.join(contactAdmissionDirectory(this.options.selfAid), 'binding.json');
192
+ fs.mkdirSync(path.dirname(marker), { recursive: true, mode: 0o700 });
193
+ atomicWriteJson(marker, { ownerAid: this.options.ownerAid, granteeAid: this.options.selfAid, relationVersion: this.options.relationVersion });
194
+ }
136
195
  // 撤销/拒绝:不留凭证也不留快照,准入随即回落到"名录不可用"。
137
196
  if (result.status !== 'active' && result.status !== 'sync_pending' && result.status !== 'revoke_pending') {
138
197
  this.revokeAuthorization(result.status);
@@ -140,6 +199,7 @@ export class OwnerDirectoryCache {
140
199
  }
141
200
  const grant = {
142
201
  schemaVersion: 2,
202
+ relationVersion: this.options.relationVersion,
143
203
  ownerAid: this.options.ownerAid,
144
204
  granteeAid: this.options.selfAid,
145
205
  grantedAt: this.now(),
@@ -158,29 +218,38 @@ export class OwnerDirectoryCache {
158
218
  * 这就是全部判断:有授权、未过期、没被远端明确拒绝过。**不按 scope 区分**——
159
219
  * 名录只有一份文件,能不能读由 storage 的 ACL 决定,不在这里重复判一次。
160
220
  */
161
- scopeAccess(_scope) {
221
+ scopeAccess(scope) {
222
+ return this.scopeAccessUnavailableReason(scope) ? 'unavailable' : 'authorized';
223
+ }
224
+ scopeAccessUnavailableReason(_scope) {
162
225
  const grant = this.loadGrant();
163
226
  if (!grant)
164
- return 'unavailable';
227
+ return 'authorization_missing_or_invalid';
165
228
  if (grant.expiresAt > 0 && grant.expiresAt <= this.now())
166
- return 'unavailable';
229
+ return 'authorization_expired';
167
230
  if (this.readSyncState().blockedScopes.length > 0)
168
- return 'unavailable';
169
- return 'authorized';
231
+ return 'scope_blocked';
232
+ return undefined;
170
233
  }
171
234
  // ── Pending update ──────────────────────────────────────────────────────────
172
235
  writePendingUpdate(update) {
173
- const stored = { schemaVersion: 1, ...update };
236
+ if (!this.canMutate())
237
+ return;
238
+ const stored = { schemaVersion: 1, ...update, relationVersion: this.options.relationVersion };
174
239
  fs.mkdirSync(this.options.directory, { recursive: true, mode: 0o700 });
175
240
  atomicWriteJson(this.pendingPath(), stored);
176
241
  }
177
242
  readPendingUpdate() {
178
- const raw = atomicReadJson(this.pendingPath());
243
+ const raw = this.readLocalJson(this.pendingPath());
179
244
  if (!isRecord(raw) || raw.schemaVersion !== 1 || raw.ownerAid !== this.options.ownerAid)
180
245
  return undefined;
246
+ if (this.options.relationVersion !== undefined && typeof raw.relationVersion === 'number' && raw.relationVersion !== this.options.relationVersion)
247
+ return undefined;
181
248
  return raw;
182
249
  }
183
250
  clearPendingUpdate() {
251
+ if (!this.canMutate())
252
+ return;
184
253
  try {
185
254
  atomicRemove(this.pendingPath());
186
255
  }
@@ -189,7 +258,7 @@ export class OwnerDirectoryCache {
189
258
  // ── handleOwnerChangedEvent ────────────────────────────────────────────────
190
259
  async handleOwnerChangedEvent(senderAid, digests) {
191
260
  if (senderAid !== this.options.ownerAid) {
192
- 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}`);
193
262
  }
194
263
  // 每条通知都是独立的变更事件:退避在这里归零,立即重试一次。
195
264
  // 通知本身是有来源保证的(App 对未 ACK 的通知会退避重发),不会造成风暴。
@@ -200,10 +269,15 @@ export class OwnerDirectoryCache {
200
269
  digests: digests ?? {},
201
270
  markedAtMs: this.now(),
202
271
  });
203
- 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'}`);
204
276
  }
205
277
  /** 授权被明确撤销或拒绝时,清掉本地快照,避免继续拿旧数据做准入判断。 */
206
278
  revokeAuthorization(status) {
279
+ if (!this.canMutate())
280
+ return;
207
281
  this.clearPullFailures();
208
282
  atomicRemove(this.authorizationPath());
209
283
  atomicRemove(this.cachePath(OWNER_DIRECTORY_SCOPES[0]));
@@ -223,14 +297,14 @@ export class OwnerDirectoryCache {
223
297
  * 不产生网络请求:只写 pending,真正的拉取推迟到下一条入站消息。
224
298
  */
225
299
  writeStartupPendingIfEmpty() {
226
- const key = this.options.directory;
300
+ const key = `${this.options.directory}:${this.options.relationVersion ?? 'legacy'}`;
227
301
  if (_startupCheckDone.has(key))
228
302
  return;
229
303
  _startupCheckDone.add(key);
230
304
  const scope = OWNER_DIRECTORY_SCOPES[0];
231
305
  if (this.scopeAccess(scope) !== 'authorized')
232
306
  return;
233
- if (this.readCachedSnapshot(scope))
307
+ if (this.options.relationVersion === undefined && this.readCachedSnapshot(scope))
234
308
  return;
235
309
  if (this.readPendingUpdate())
236
310
  return;
@@ -250,7 +324,32 @@ export class OwnerDirectoryCache {
250
324
  * 拆开的理由:网络拉取是所有 agent 共享的,落地是每个 agent 自己的,时机和
251
325
  * 代价都不一样——混在一起会让"来一条消息"既可能发网络请求又可能写盘。
252
326
  */
253
- async processPendingIfNeeded() {
327
+ async processPendingIfNeeded(trigger) {
328
+ if (this.options.relationVersion === undefined)
329
+ return this.processPendingOnce(trigger);
330
+ if (this.pendingInFlight)
331
+ return this.pendingInFlight;
332
+ const run = (async () => {
333
+ while (true) {
334
+ const before = this.readPendingUpdate();
335
+ if (!before || (this.options.isCurrent && !this.options.isCurrent()))
336
+ return;
337
+ await this.processPendingOnce(trigger);
338
+ const after = this.readPendingUpdate();
339
+ if (!after || (after.operationId === before.operationId && after.markedAtMs === before.markedAtMs))
340
+ return;
341
+ }
342
+ })();
343
+ this.pendingInFlight = run;
344
+ try {
345
+ await run;
346
+ }
347
+ finally {
348
+ if (this.pendingInFlight === run)
349
+ this.pendingInFlight = undefined;
350
+ }
351
+ }
352
+ async processPendingOnce(trigger) {
254
353
  const pending = this.readPendingUpdate();
255
354
  if (!pending)
256
355
  return;
@@ -262,7 +361,11 @@ export class OwnerDirectoryCache {
262
361
  }
263
362
  logger.info(`[OwnerDirectoryCache] Processing pending for ${this.options.ownerAid}, op=${pending.operationId}, attempt=${this.pullFailures + 1}`);
264
363
  try {
265
- 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);
367
+ if (this.options.relationVersion !== undefined)
368
+ await this._applyAll(fetched);
266
369
  this.clearPullFailures();
267
370
  this.clearPendingUnlessSuperseded(pending);
268
371
  }
@@ -328,9 +431,9 @@ export class OwnerDirectoryCache {
328
431
  * 写盘失败只 warn 不抛(共享缓存坏了下一次会重写);返回的是本次拿到的数据,
329
432
  * 即使共享缓存写失败,调用方仍可据此落地。
330
433
  */
331
- async fetchToSharedCache(digests) {
434
+ async fetchToSharedCache(digests, trigger = 'unspecified', operationId) {
332
435
  // ① 检查共享缓存:通知 digest 与共享缓存一致时,跳过网络请求
333
- const sharedFresh = OWNER_DIRECTORY_SCOPES.every(scope => {
436
+ const sharedFresh = this.options.relationVersion === undefined && OWNER_DIRECTORY_SCOPES.every(scope => {
334
437
  const hintDigest = digests?.[scope];
335
438
  if (!hintDigest)
336
439
  return false; // 无 hint(startup),需要拉
@@ -342,19 +445,26 @@ export class OwnerDirectoryCache {
342
445
  return this._assertComplete(this._readSharedCache());
343
446
  }
344
447
  // ② 模块级单飞:同进程只发一次网络请求
345
- const existing = _fetchInFlight.get(this.options.ownerAid);
448
+ const flightKey = this.options.relationVersion === undefined ? this.options.ownerAid
449
+ : `${this.options.ownerAid}:${this.options.selfAid}:${this.options.relationVersion}`;
450
+ const existing = _fetchInFlight.get(flightKey);
346
451
  const outcome = existing
347
452
  ? await existing
348
453
  : await (() => {
454
+ const startedAt = this.now();
349
455
  const fetchPromise = this._doFetch().then(result => {
350
- 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
+ }
351
461
  return result;
352
462
  }).finally(() => {
353
- if (_fetchInFlight.get(this.options.ownerAid) === fetchPromise) {
354
- _fetchInFlight.delete(this.options.ownerAid);
463
+ if (_fetchInFlight.get(flightKey) === fetchPromise) {
464
+ _fetchInFlight.delete(flightKey);
355
465
  }
356
466
  });
357
- _fetchInFlight.set(this.options.ownerAid, fetchPromise);
467
+ _fetchInFlight.set(flightKey, fetchPromise);
358
468
  return fetchPromise;
359
469
  })();
360
470
  // 远端明确拒绝:作废本地快照并标记 blocked,重试没有意义。逐个 scope 处理,
@@ -363,7 +473,8 @@ export class OwnerDirectoryCache {
363
473
  if (this.scopeAccess(scope) === 'authorized')
364
474
  await this.blockScope(scope);
365
475
  }
366
- return this._assertComplete(outcome.data, outcome.failures);
476
+ const complete = this._assertComplete(outcome.data, outcome.failures);
477
+ return complete;
367
478
  }
368
479
  /**
369
480
  * 已授权范围一个都没拿到,就不算拉取成功。
@@ -403,6 +514,9 @@ export class OwnerDirectoryCache {
403
514
  return promise;
404
515
  }
405
516
  async _applyFromSharedCacheOnce() {
517
+ // Never relabel an older relationship's shared bytes as a newly verified snapshot.
518
+ if (this.options.relationVersion !== undefined)
519
+ return false;
406
520
  // 热路径早退:每条入站消息都会调到这里,而绝大多数消息发生时名录早就落过盘。
407
521
  // 先只比 content_digest,命中就连 JSON 都不解析——`_readSharedCache` 会做
408
522
  // 逐条校验 + 全量摘要重算,那是拉取期才需要的成本。
@@ -469,8 +583,11 @@ export class OwnerDirectoryCache {
469
583
  *
470
584
  * 需求路径(`lookupByAid`、准入)用这个:用户正等着结果,不能只拉不落。
471
585
  */
472
- async pullAndApply(digests) {
473
- const fetched = await this.fetchToSharedCache(digests);
586
+ async pullAndApply(digests, trigger = 'unspecified') {
587
+ const generation = ++this.fetchGeneration;
588
+ const fetched = await this.fetchToSharedCache(digests, trigger);
589
+ if (generation !== this.fetchGeneration)
590
+ return;
474
591
  await this._applyAll(fetched);
475
592
  }
476
593
  /**
@@ -479,14 +596,19 @@ export class OwnerDirectoryCache {
479
596
  * 完整性由阶段一保证(`_assertComplete`);这里只跳过"拉取之后权限被撤"的范围。
480
597
  */
481
598
  async _applyAll(fetched) {
482
- for (const scope of OWNER_DIRECTORY_SCOPES) {
483
- if (this.scopeAccess(scope) !== 'authorized')
484
- continue;
485
- const file = fetched[scope];
486
- if (!file)
487
- continue;
488
- await this._applyFile(scope, file);
489
- }
599
+ const apply = async () => {
600
+ for (const scope of OWNER_DIRECTORY_SCOPES) {
601
+ if (this.scopeAccess(scope) !== 'authorized')
602
+ continue;
603
+ const file = fetched[scope];
604
+ if (!file)
605
+ continue;
606
+ await this._applyFile(scope, file);
607
+ }
608
+ };
609
+ const next = this.applyTail.then(apply);
610
+ this.applyTail = next.catch(() => { });
611
+ await next;
490
612
  }
491
613
  // ── 共享缓存($EVOLCORE_HOME/data/owner-directory/<ownerAid>/) ────────────
492
614
  _sharedCacheDir() {
@@ -574,7 +696,7 @@ export class OwnerDirectoryCache {
574
696
  * 和 `cmp` 都能直接对,排查时不用再区分"到底哪一份是真的"。本地需要的
575
697
  * 元数据(摘要、条数、时间)全部从字节和文档自身推导,不再另存一份。
576
698
  */
577
- _writeSharedCache(data) {
699
+ _writeSharedCache(data, trigger = 'unspecified', operationId, startedAt) {
578
700
  try {
579
701
  const dir = this._sharedCacheDir();
580
702
  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -582,6 +704,8 @@ export class OwnerDirectoryCache {
582
704
  const file = data[scope];
583
705
  if (!file)
584
706
  continue;
707
+ // 覆盖前先读出旧文件:落地记录要回答"变了什么",而旧字节马上就没了。
708
+ const prev = this._readSharedCacheDocumentSafely(scope);
585
709
  const target = this._sharedCachePath(scope);
586
710
  atomicWriteBytes(target, file.bytes);
587
711
  fs.chmodSync(target, 0o600);
@@ -595,12 +719,86 @@ export class OwnerDirectoryCache {
595
719
  logger.debug(`[OwnerDirectoryCache] utimes ${scope} failed: ${errorText(error)}`);
596
720
  }
597
721
  }
722
+ this._recordLanding(scope, file, prev, trigger, operationId, startedAt);
598
723
  }
599
724
  }
600
725
  catch (error) {
601
726
  logger.warn(`[OwnerDirectoryCache] Failed to write shared cache: ${errorText(error)}`);
602
727
  }
603
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
+ }
604
802
  // ── readSnapshot / lookupByAid ─────────────────────────────────────────────
605
803
  readSnapshot(scope) {
606
804
  if (!isOwnerDirectoryScope(scope))
@@ -619,7 +817,7 @@ export class OwnerDirectoryCache {
619
817
  // 需求路径必须"拉 + 落"一次做完:调用方在等这个结果,
620
818
  // 只更新共享缓存的话本地快照还是旧的,刚加的人照样查不到。
621
819
  const pending = this.readPendingUpdate();
622
- await this.pullAndApply(pending?.digests);
820
+ await this.pullAndApply(pending?.digests, 'lookup');
623
821
  // 这次拉取已经覆盖了 pending 的内容,标记可以清了;否则下一条消息
624
822
  // 会拿同一批 digest 再走一遍拉取路径。失败时不清,交给退避重试。
625
823
  if (pending)
@@ -669,7 +867,8 @@ export class OwnerDirectoryCache {
669
867
  const code = normalized instanceof OwnerDirectoryCacheError ? normalized.code : 'FETCH_ERROR';
670
868
  failures[scope] = `${code}: ${errorText(normalized)}`;
671
869
  logger.warn(`[OwnerDirectoryCache] Fetch failed for ${scope}: ${errorText(normalized)} (raw kept for diagnosis)`);
672
- this.options.onError?.(scope, normalized);
870
+ if (this.canMutate())
871
+ this.options.onError?.(scope, normalized);
673
872
  this._appendFetchFailure(scope, code, errorText(normalized));
674
873
  // 远端拒绝随结果返回,由调用方作废自己的本地快照;其它错误保持 pending,
675
874
  // 交给时间退避重试。拒绝信息必须在返回值里走——单飞复用者也要看得到。
@@ -765,6 +964,7 @@ export class OwnerDirectoryCache {
765
964
  for (const entry of entries) {
766
965
  if (!isRecord(entry))
767
966
  throw new OwnerDirectoryCacheError('INVALID_ENTRY', `${scope}.json has a non-object entry`);
967
+ normalizeEntry(entry); // Validate known optional admission fields before caching the raw object.
768
968
  if (typeof entry.aid !== 'string' || !entry.aid || !isValidAid(entry.aid)) {
769
969
  throw new OwnerDirectoryCacheError('INVALID_ENTRY', `${scope}.json has an entry with invalid aid`);
770
970
  }
@@ -900,6 +1100,8 @@ export class OwnerDirectoryCache {
900
1100
  }
901
1101
  // ── Internal: applyFile ──────────────────────────────────────────────────────
902
1102
  async _applyFile(scope, file) {
1103
+ if (!this.canMutate())
1104
+ return;
903
1105
  const prev = this.readCachedSnapshot(scope);
904
1106
  const localDigest = prev?.contentDigest;
905
1107
  if (file.contentDigest && localDigest && file.contentDigest === localDigest) {
@@ -911,12 +1113,18 @@ export class OwnerDirectoryCache {
911
1113
  }
912
1114
  const attemptedAt = this.now();
913
1115
  await this.updateFileState(scope, { lastAttemptAt: attemptedAt, status: 'syncing', error: undefined });
1116
+ if (!this.canMutate())
1117
+ return;
914
1118
  try {
915
1119
  const entries = file.entries.map(e => normalizeEntry(e));
916
1120
  const aids = new Set(entries.map(e => e.aid));
917
1121
  if (aids.size !== entries.length)
918
1122
  throw new OwnerDirectoryCacheError('DUPLICATE_AID', `${scope} has duplicate AIDs`);
919
1123
  const snapshot = {
1124
+ sourceRevision: file.raw.source_revision,
1125
+ ...(this.options.relationVersion !== undefined ? { relationVersion: this.options.relationVersion } : {}),
1126
+ blockedAids: file.blockedAids.filter(value => isRecord(value) && value.target_type === 'aid')
1127
+ .map(value => value.target_id),
920
1128
  ownerAid: this.options.ownerAid,
921
1129
  granteeAid: this.options.selfAid,
922
1130
  scope,
@@ -929,7 +1137,18 @@ export class OwnerDirectoryCache {
929
1137
  ...(file.owner ? { owner: file.owner } : {}),
930
1138
  ...(file.personalAssistant ? { personalAssistant: file.personalAssistant } : {}),
931
1139
  };
932
- archiveSnapshot(this.options.directory, scope);
1140
+ this.options.onSnapshotApplying?.(snapshot);
1141
+ if (!this.canMutate())
1142
+ return;
1143
+ archiveSnapshot(path.dirname(this.cachePath(scope)), scope);
1144
+ const prevMeta = prev ? { owner: prev.owner, personalAssistant: prev.personalAssistant } : undefined;
1145
+ const nextMeta = { owner: snapshot.owner, personalAssistant: snapshot.personalAssistant };
1146
+ const changes = diffSnapshots(scope, snapshot, prev, nextMeta, prevMeta);
1147
+ // 变更日志必须先于快照落盘:快照一覆盖,`prev` 就没了,日志里缺的那批
1148
+ // 永远补不回来。appendChanges 失败会抛,走下面的 catch → status=error,
1149
+ // 下次同步重试;重试时同一批变更会重新生成,appendChanges 自己按
1150
+ // contentDigest 去重,不会重复追加。
1151
+ appendChanges(this.options.directory, changes);
933
1152
  const stored = { schemaVersion: 2, ...snapshot };
934
1153
  fs.mkdirSync(this.options.directory, { recursive: true, mode: 0o700 });
935
1154
  atomicWriteJson(this.cachePath(scope), stored);
@@ -939,19 +1158,20 @@ export class OwnerDirectoryCache {
939
1158
  // 一起删,否则 atomicRead 会把 `agents.json_` 当成中断的 rename 恢复回来。
940
1159
  atomicRemove(path.join(this.options.directory, 'agents.json'));
941
1160
  logger.info(`[OwnerDirectoryCache] Applied ${scope}: total=${snapshot.total}`);
942
- const prevMeta = prev ? { owner: prev.owner, personalAssistant: prev.personalAssistant } : undefined;
943
- const nextMeta = { owner: snapshot.owner, personalAssistant: snapshot.personalAssistant };
944
- const changes = diffSnapshots(scope, snapshot, prev, nextMeta, prevMeta);
945
- appendChanges(this.options.directory, changes);
946
1161
  await this.updateFileState(scope, {
947
1162
  lastAttemptAt: attemptedAt,
948
1163
  lastSuccessAt: snapshot.fetchedAt,
949
1164
  snapshotId: snapshot.snapshotId,
950
1165
  status: 'ready',
951
1166
  error: undefined,
1167
+ // 成功即清零:否则 `status: ready` 与 `failureCount: 3` 并存,
1168
+ // 事后把这个状态文件当证据的人会被误导。
1169
+ failureCount: 0,
952
1170
  });
953
1171
  this.refreshMarkdown();
954
1172
  try {
1173
+ if (!this.canMutate())
1174
+ return;
955
1175
  if (this.options.onSnapshotChanged && changes.length > 0) {
956
1176
  const agentMdAids = collectAgentMdRefreshAids(changes, nextMeta, prevMeta, snapshot);
957
1177
  if (agentMdAids.length > 0)
@@ -970,7 +1190,8 @@ export class OwnerDirectoryCache {
970
1190
  else {
971
1191
  await this.updateFileState(scope, { lastAttemptAt: attemptedAt, status: 'error', error: errorText(error) });
972
1192
  }
973
- this.options.onError?.(scope, error);
1193
+ if (this.canMutate())
1194
+ this.options.onError?.(scope, error);
974
1195
  throw error;
975
1196
  }
976
1197
  }
@@ -982,12 +1203,13 @@ export class OwnerDirectoryCache {
982
1203
  const cached = this.snapshotCache.get(scope);
983
1204
  if (cached !== undefined && cached.stamp === stamp)
984
1205
  return cached.snapshot ?? undefined;
985
- const raw = stamp ? atomicReadJson(this.cachePath(scope)) : undefined;
1206
+ const raw = stamp ? this.readLocalJson(this.cachePath(scope)) : undefined;
986
1207
  const store = (snapshot) => {
987
1208
  this.snapshotCache.set(scope, { snapshot, stamp });
988
1209
  return snapshot ?? undefined;
989
1210
  };
990
1211
  if (!isRecord(raw) || raw.schemaVersion !== 2 || raw.ownerAid !== this.options.ownerAid
1212
+ || (this.options.relationVersion !== undefined && typeof raw.relationVersion === 'number' && raw.relationVersion !== this.options.relationVersion)
991
1213
  || raw.granteeAid !== this.options.selfAid || raw.scope !== scope
992
1214
  || !Array.isArray(raw.entries) || raw.entries.length !== raw.total) {
993
1215
  return store(null);
@@ -998,6 +1220,9 @@ export class OwnerDirectoryCache {
998
1220
  if (aids.size !== entries.length || entries.length > MAX_DIRECTORY_ENTRIES)
999
1221
  return store(null);
1000
1222
  return store({
1223
+ ...(typeof raw.sourceRevision === 'string' ? { sourceRevision: raw.sourceRevision } : {}),
1224
+ ...(Number.isSafeInteger(raw.relationVersion) ? { relationVersion: raw.relationVersion } : {}),
1225
+ blockedAids: parseBlockedAids(raw.blockedAids ?? []),
1001
1226
  ownerAid: this.options.ownerAid,
1002
1227
  granteeAid: this.options.selfAid,
1003
1228
  scope,
@@ -1034,6 +1259,8 @@ export class OwnerDirectoryCache {
1034
1259
  }
1035
1260
  // ── Internal: authorization / sync state / paths ────────────────────────────
1036
1261
  async blockScope(scope) {
1262
+ if (!this.canMutate())
1263
+ return;
1037
1264
  atomicRemove(this.cachePath(scope));
1038
1265
  this.snapshotCache.delete(scope);
1039
1266
  await this.updateSyncState(state => ({
@@ -1051,7 +1278,10 @@ export class OwnerDirectoryCache {
1051
1278
  }
1052
1279
  async updateSyncState(transform) {
1053
1280
  const run = this.stateWriteTail.then(() => {
1281
+ if (!this.canMutate())
1282
+ return;
1054
1283
  const state = transform(this.readSyncState());
1284
+ state.relationVersion = this.options.relationVersion;
1055
1285
  fs.mkdirSync(this.options.directory, { recursive: true, mode: 0o700 });
1056
1286
  atomicWriteJson(this.syncStatePath(), state);
1057
1287
  fs.chmodSync(this.syncStatePath(), 0o600);
@@ -1060,9 +1290,10 @@ export class OwnerDirectoryCache {
1060
1290
  await run;
1061
1291
  }
1062
1292
  readSyncState() {
1063
- const raw = atomicReadJson(this.syncStatePath());
1293
+ const raw = this.readLocalJson(this.syncStatePath());
1064
1294
  if (!isRecord(raw) || raw.schemaVersion !== 1 || raw.ownerAid !== this.options.ownerAid
1065
- || raw.granteeAid !== this.options.selfAid || !isRecord(raw.files)) {
1295
+ || raw.granteeAid !== this.options.selfAid || !isRecord(raw.files)
1296
+ || (this.options.relationVersion !== undefined && typeof raw.relationVersion === 'number' && raw.relationVersion !== this.options.relationVersion)) {
1066
1297
  return { schemaVersion: 1, ownerAid: this.options.ownerAid, granteeAid: this.options.selfAid, files: {}, blockedScopes: [] };
1067
1298
  }
1068
1299
  return {
@@ -1080,11 +1311,13 @@ export class OwnerDirectoryCache {
1080
1311
  * contacts 的那一份。
1081
1312
  */
1082
1313
  loadGrant() {
1083
- const raw = atomicReadJson(this.authorizationPath());
1314
+ const raw = this.readLocalJson(this.authorizationPath());
1084
1315
  if (!isRecord(raw))
1085
1316
  return undefined;
1086
1317
  if (raw.ownerAid !== this.options.ownerAid || raw.granteeAid !== this.options.selfAid)
1087
1318
  return undefined;
1319
+ if (this.options.relationVersion !== undefined && typeof raw.relationVersion === 'number' && raw.relationVersion !== this.options.relationVersion)
1320
+ return undefined;
1088
1321
  if (raw.schemaVersion === 2) {
1089
1322
  if (!Number.isSafeInteger(raw.grantedAt) || !Number.isSafeInteger(raw.expiresAt))
1090
1323
  return undefined;
@@ -1133,15 +1366,18 @@ export class OwnerDirectoryCache {
1133
1366
  * 授权真的不存在或快照文件真的不在盘上。其余情形保留现有内容不动。
1134
1367
  */
1135
1368
  refreshMarkdown() {
1369
+ if (!this.canMutate())
1370
+ return;
1136
1371
  const target = path.join(this.options.directory, OWNER_DIRECTORY_MARKDOWN_FILE);
1137
1372
  try {
1138
1373
  const snapshot = this.readCachedSnapshot('contacts');
1374
+ // 开关每次现读:`ec connect access set` 改完就调一个 refresh,不必让调用方再传一份。
1139
1375
  const markdown = renderOwnerDirectoryMarkdown({
1140
1376
  ownerAid: this.options.ownerAid,
1141
1377
  selfAid: this.options.selfAid,
1142
1378
  snapshot,
1143
1379
  remarks: this.remarksSnapshot(),
1144
- allowExternalContacts: this.options.allowExternalContacts?.(),
1380
+ policy: resolveOwnerDirectoryRenderPolicy(this.options.selfAid, snapshot),
1145
1381
  });
1146
1382
  if (!markdown) {
1147
1383
  if (!this.directoryGone()) {
@@ -1149,22 +1385,49 @@ export class OwnerDirectoryCache {
1149
1385
  return;
1150
1386
  }
1151
1387
  // 确证不可用时连同热备名一起删,避免 atomicRead 把中断的 rename 恢复回来。
1388
+ // identity.json 必须一起删:它是 PA / Owner 身份的唯一来源,留着等于让
1389
+ // 一个已作废的名录继续决定注入哪一段。
1152
1390
  atomicRemove(target);
1391
+ atomicRemove(path.join(this.options.directory, OWNER_DIRECTORY_IDENTITY_FILE));
1153
1392
  return;
1154
1393
  }
1155
1394
  fs.mkdirSync(this.options.directory, { recursive: true, mode: 0o700 });
1156
1395
  // 内容不变就不写盘:ECK 的注入按文件指纹走,无谓的写入会触发无谓的重新加载。
1396
+ let written = false;
1157
1397
  try {
1158
- if (atomicRead(target) === markdown)
1159
- return;
1398
+ written = atomicRead(target) === markdown;
1160
1399
  }
1161
1400
  catch { /* 读不出来就照写 */ }
1162
- atomicWriteText(target, markdown);
1401
+ if (!written)
1402
+ atomicWriteText(target, markdown);
1403
+ // 身份文件跟着渲染产物走:名录换了、PA 换了、开关换了,都会经过这里。
1404
+ this.writeIdentity(snapshot);
1163
1405
  }
1164
1406
  catch (error) {
1165
1407
  logger.warn(`[OwnerDirectoryCache] refreshMarkdown failed: ${errorText(error)}`);
1166
1408
  }
1167
1409
  }
1410
+ /**
1411
+ * 写 `directory/identity.json`:只存 Owner 与个人助理的身份字段。
1412
+ *
1413
+ * ECK 变量 `ownerAid` / `ownerName` / `personalAssistantAid` / `personalAssistantName`
1414
+ * 每轮都读它,所以字段必须窄——这里不存快照、不存条目、不存任何开关布尔。
1415
+ * `isPersonalAssistant` / `isOwner` 由调用方用 `selfAid` 即时比较,不落盘:
1416
+ * 落盘的布尔会过期,而且可以被手改文件伪造角色。
1417
+ *
1418
+ * 内容不变就不写盘,与 `directory.md` 同理。
1419
+ */
1420
+ writeIdentity(snapshot) {
1421
+ const target = path.join(this.options.directory, OWNER_DIRECTORY_IDENTITY_FILE);
1422
+ const payload = buildOwnerDirectoryIdentity(snapshot);
1423
+ const text = `${JSON.stringify(payload, null, 2)}\n`;
1424
+ try {
1425
+ if (atomicRead(target) === text)
1426
+ return;
1427
+ }
1428
+ catch { /* 不存在或读不出,照写 */ }
1429
+ atomicWriteText(target, text);
1430
+ }
1168
1431
  /**
1169
1432
  * 名录是否**确证**已不可用。
1170
1433
  *
@@ -1201,7 +1464,12 @@ export class OwnerDirectoryCache {
1201
1464
  authorizationPath() { return path.join(this.options.directory, 'authorization.json'); }
1202
1465
  syncStatePath() { return path.join(this.options.directory, 'sync-state.json'); }
1203
1466
  pendingPath() { return path.join(this.options.directory, 'pending.json'); }
1204
- cachePath(scope) { return path.join(this.options.directory, `${scope}.json`); }
1467
+ cachePath(scope) {
1468
+ // 快照只有一份,app-v1 与 legacy 共用同一路径。准入依据放在 daemon 管理的
1469
+ // data/contact-admission/ 下会让 App 侧写入、人工排查、目录命令各看一份副本;
1470
+ // 版本安全性由 relationVersion 校验负责,不靠换目录。
1471
+ return path.join(this.options.directory, `${scope}.json`);
1472
+ }
1205
1473
  }
1206
1474
  // ── Module-level helpers ─────────────────────────────────────────────────────
1207
1475
  /**
@@ -1228,11 +1496,24 @@ function parseIdentityField(value) {
1228
1496
  };
1229
1497
  }
1230
1498
  /**
1231
- * 把远端条目收敛成内部形状。未知字段直接丢弃(协议允许后续新增可选字段,
1232
- * 解析器忽略即可);已知字符串字段一律截断到 128 字符。
1499
+ * 把远端条目收敛成唯一的内部形状。
1500
+ *
1501
+ * 这是条目形态的唯一收敛点:apply 路径(远端文件)和 readCachedSnapshot(本地
1502
+ * 快照)都从这里出,所以下游看到的永远是同一种形状。
1503
+ *
1504
+ * 规则:
1505
+ * - 未知字段收进 `extra` 原样保留,不丢弃:远端新增字段时,本端旧版本仍要能
1506
+ * 在本地快照里看到它、在变更日志里记录它。丢弃只发生在本地快照这一层——
1507
+ * 共享缓存是远端原始字节,不受此影响,但准入和排查读的都是本地快照。
1508
+ * - `remark` / `type` / `exttype` / `description` / `baseagent` / `ownership_status`
1509
+ * **恒存在**,非字符串一律写成 `''`。远端有时发 `exttype: ""`、有时整个键不写,
1510
+ * 这两种在业务上是同一件事;若让它们分别变成 `''` 和 `undefined`,比较会判"变了",
1511
+ * 上游换一种序列化就把整份名录刷成变更。收敛到 `''` 后这类噪音消失。
1512
+ * - `ownerAid` 保持可选:它承载内外判据,缺失是真实状态(未归属),不能补空串。
1513
+ * - 数值字段只在是安全整数时保留;`null` / 缺失都落到"没有"。
1233
1514
  *
1234
1515
  * 注意:`content_digest` 必须在**原始**条目上计算,不能拿这里的输出回算——
1235
- * 归一化会把 null 变成缺失、把长字段截断。
1516
+ * 归一化会丢未知字段、补默认值、截断长字段。
1236
1517
  */
1237
1518
  function normalizeEntry(value) {
1238
1519
  if (!isRecord(value) || typeof value.aid !== 'string' || !isValidAid(value.aid)) {
@@ -1242,16 +1523,32 @@ function normalizeEntry(value) {
1242
1523
  aid: value.aid,
1243
1524
  name: typeof value.name === 'string' ? value.name : value.aid,
1244
1525
  };
1526
+ if (value.agent_scope !== undefined) {
1527
+ const scope = value.agent_scope;
1528
+ if (!isRecord(scope) || (scope.mode !== 'all' && scope.mode !== 'selected')) {
1529
+ throw new OwnerDirectoryCacheError('INVALID_ENTRY', 'invalid agent_scope');
1530
+ }
1531
+ if (scope.mode === 'all')
1532
+ entry.agent_scope = { mode: 'all' };
1533
+ else {
1534
+ if (!Array.isArray(scope.agent_aids) || scope.agent_aids.length === 0
1535
+ || scope.agent_aids.some(aid => typeof aid !== 'string' || !isValidAid(aid))
1536
+ || new Set(scope.agent_aids).size !== scope.agent_aids.length) {
1537
+ throw new OwnerDirectoryCacheError('INVALID_ENTRY', 'invalid selected agent_scope');
1538
+ }
1539
+ entry.agent_scope = { mode: 'selected', agent_aids: [...scope.agent_aids] };
1540
+ }
1541
+ }
1245
1542
  // 本地缓存用 camelCase 存,远端文档用 snake_case;两种都认,否则读回本地快照会丢字段。
1246
1543
  if (typeof value.owner_aid === 'string' && value.owner_aid.trim())
1247
1544
  entry.ownerAid = value.owner_aid.trim();
1248
1545
  else if (typeof value.ownerAid === 'string' && value.ownerAid.trim())
1249
1546
  entry.ownerAid = value.ownerAid.trim();
1250
- const allowed = ['remark', 'type', 'exttype', 'description', 'baseagent', 'ownership_status'];
1251
- for (const key of allowed) {
1252
- if (typeof value[key] === 'string' && value[key].length <= 128) {
1253
- entry[key] = value[key];
1254
- }
1547
+ // 恒存在的字符串字段:缺失 ≡ 空串。
1548
+ const textFields = ['remark', 'type', 'exttype', 'description', 'baseagent', 'ownership_status'];
1549
+ for (const key of textFields) {
1550
+ const raw = value[key];
1551
+ entry[key] = typeof raw === 'string' ? truncateCodePoints(raw, 128) : '';
1255
1552
  }
1256
1553
  if (Number.isSafeInteger(value.ownership_checked_at_ms)) {
1257
1554
  entry.ownership_checked_at_ms = value.ownership_checked_at_ms;
@@ -1259,8 +1556,207 @@ function normalizeEntry(value) {
1259
1556
  if (Number.isSafeInteger(value.agent_md_signed_at)) {
1260
1557
  entry.agent_md_signed_at = value.agent_md_signed_at;
1261
1558
  }
1559
+ // 读回本地快照时未知字段已经在 `extra` 里;远端原文里没有这个键。两条路径都要出同一种形状。
1560
+ const carried = isRecord(value.extra) ? sanitizeExtra(value.extra) : undefined;
1561
+ const fresh = collectUnknownFields(value);
1562
+ const extra = carried || fresh ? { ...(carried ?? {}), ...(fresh ?? {}) } : undefined;
1563
+ if (extra)
1564
+ entry.extra = extra;
1262
1565
  return entry;
1263
1566
  }
1567
+ function parseBlockedAids(value) {
1568
+ if (!Array.isArray(value) || value.some(aid => typeof aid !== 'string' || !isValidAid(aid))) {
1569
+ throw new OwnerDirectoryCacheError('INVALID_ENTRY', 'invalid blocked aids');
1570
+ }
1571
+ return [...value];
1572
+ }
1573
+ /** 已有 `extra` 读回来时限一遍大小,防止被本实例以外的途径写大的本地文件撑爆内存。 */
1574
+ function sanitizeExtra(value) {
1575
+ let bytes = 0;
1576
+ const kept = {};
1577
+ for (const [key, raw] of Object.entries(value)) {
1578
+ if (KNOWN_ENTRY_FIELDS.has(key))
1579
+ continue;
1580
+ let serialized;
1581
+ try {
1582
+ serialized = JSON.stringify(raw);
1583
+ }
1584
+ catch {
1585
+ continue;
1586
+ }
1587
+ if (serialized === undefined)
1588
+ continue;
1589
+ const size = Buffer.byteLength(key, 'utf8') + Buffer.byteLength(serialized, 'utf8');
1590
+ if (size > UNKNOWN_FIELD_MAX_BYTES || bytes + size > UNKNOWN_FIELDS_MAX_BYTES)
1591
+ continue;
1592
+ bytes += size;
1593
+ kept[key] = raw;
1594
+ }
1595
+ return Object.keys(kept).length > 0 ? kept : undefined;
1596
+ }
1597
+ /** 本版本认识的条目字段(两种拼写都算),其余进 `extra`。 */
1598
+ const KNOWN_ENTRY_FIELDS = new Set([
1599
+ 'aid', 'name', 'owner_aid', 'ownerAid', 'remark', 'type', 'exttype', 'description',
1600
+ 'baseagent', 'ownership_status', 'ownership_checked_at_ms', 'agent_md_signed_at',
1601
+ 'agent_scope',
1602
+ // `extra` 是本地快照自己的形状;读回时不能把它当成又一层未知字段。
1603
+ 'extra',
1604
+ ]);
1605
+ /**
1606
+ * 单条目未知字段的总字节上限。
1607
+ *
1608
+ * 目录对象整体受 `OWNER_DIRECTORY_MAX_OBJECT_BYTES`(128 KiB)约束,但那条是
1609
+ * 拉取前的预算;这里防的是"本地快照比远端还大"。远端以后若往条目里塞大字段,
1610
+ * 超出部分按字段粒度丢弃,并记一条 WARN——丢的是新字段,不能悄悄丢。
1611
+ */
1612
+ const UNKNOWN_FIELDS_MAX_BYTES = 4 * 1024;
1613
+ /** 单个未知字段的字节上限;超出整条丢弃(截断 JSON 值没有意义)。 */
1614
+ const UNKNOWN_FIELD_MAX_BYTES = 1 * 1024;
1615
+ /**
1616
+ * 收集本版本不认识的条目字段。
1617
+ *
1618
+ * 值原样保留(已经过 `JSON.parse`,一定是可序列化的 JSON 值),不递归改形。
1619
+ * 顺序按出现顺序落盘,但比较时由调用方规范化——字段顺序不同不算变化。
1620
+ */
1621
+ function collectUnknownFields(value) {
1622
+ let extra;
1623
+ let bytes = 0;
1624
+ for (const [key, raw] of Object.entries(value)) {
1625
+ if (KNOWN_ENTRY_FIELDS.has(key))
1626
+ continue;
1627
+ let serialized;
1628
+ try {
1629
+ serialized = JSON.stringify(raw);
1630
+ }
1631
+ catch {
1632
+ // 循环引用的对象不可能来自 JSON.parse,走到这里说明调用方传了非常规值。
1633
+ logger.warn(`[OwnerDirectoryCache] entry field ${key} is not JSON-serializable, dropped`);
1634
+ continue;
1635
+ }
1636
+ if (serialized === undefined)
1637
+ continue;
1638
+ const size = Buffer.byteLength(key, 'utf8') + Buffer.byteLength(serialized, 'utf8');
1639
+ if (size > UNKNOWN_FIELD_MAX_BYTES) {
1640
+ logger.warn(`[OwnerDirectoryCache] entry field ${key} exceeds ${UNKNOWN_FIELD_MAX_BYTES}B, dropped`);
1641
+ continue;
1642
+ }
1643
+ if (bytes + size > UNKNOWN_FIELDS_MAX_BYTES) {
1644
+ logger.warn(`[OwnerDirectoryCache] entry unknown fields exceed ${UNKNOWN_FIELDS_MAX_BYTES}B, ${key} and later dropped`);
1645
+ break;
1646
+ }
1647
+ bytes += size;
1648
+ extra ??= {};
1649
+ extra[key] = raw;
1650
+ }
1651
+ return extra;
1652
+ }
1653
+ /**
1654
+ * `extra` 的规范化序列化,用于"算不算变了"的比较。
1655
+ *
1656
+ * 放在这里而不是 store,是因为 store 已经 import 本模块;反向取值会形成运行时
1657
+ * 循环依赖,而这条路径在每条消息的准入上都会走到。
1658
+ *
1659
+ * `JSON.stringify` 依赖插入顺序,同一份远端数据换个字段顺序就会被判成变更;
1660
+ * 这里按键名排序后再序列化。值为 `undefined` 的键不会产生序列化输出,与缺失等价。
1661
+ */
1662
+ export function extraFingerprint(value) {
1663
+ if (!value)
1664
+ return '';
1665
+ const keys = Object.keys(value).sort();
1666
+ if (keys.length === 0)
1667
+ return '';
1668
+ return JSON.stringify(keys.map(key => [key, value[key] ?? null]));
1669
+ }
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
+ }
1755
+ function truncateCodePoints(text, max) {
1756
+ if (text.length <= max)
1757
+ return text;
1758
+ return Array.from(text).slice(0, max).join('');
1759
+ }
1264
1760
  function isPermissionDenied(error) {
1265
1761
  return error instanceof OwnerDirectoryCacheError
1266
1762
  && ['PERMISSION_DENIED', 'ACCESS_DENIED', 'FORBIDDEN'].includes(error.code);