@carloswon/cairn-memory 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/CHANGELOG.md +155 -81
  2. package/README.md +17 -1
  3. package/dist/src/agents/config.d.ts +14 -1
  4. package/dist/src/agents/config.js +17 -3
  5. package/dist/src/agents/config.js.map +1 -1
  6. package/dist/src/governance/apply.d.ts +4 -2
  7. package/dist/src/governance/apply.js +20 -0
  8. package/dist/src/governance/apply.js.map +1 -1
  9. package/dist/src/governance/revision-proposal.d.ts +80 -0
  10. package/dist/src/governance/revision-proposal.js +243 -0
  11. package/dist/src/governance/revision-proposal.js.map +1 -0
  12. package/dist/src/interfaces/app-service.d.ts +79 -0
  13. package/dist/src/interfaces/app-service.js +231 -2
  14. package/dist/src/interfaces/app-service.js.map +1 -1
  15. package/dist/src/interfaces/cli/main.js +459 -46
  16. package/dist/src/interfaces/cli/main.js.map +1 -1
  17. package/dist/src/interfaces/console/annotations.d.ts +96 -0
  18. package/dist/src/interfaces/console/annotations.js +274 -0
  19. package/dist/src/interfaces/console/annotations.js.map +1 -0
  20. package/dist/src/interfaces/console/assets/ui-js.js +289 -4
  21. package/dist/src/interfaces/console/assets/ui-js.js.map +1 -1
  22. package/dist/src/interfaces/console/server.js +66 -0
  23. package/dist/src/interfaces/console/server.js.map +1 -1
  24. package/dist/src/interfaces/mcp/server.js +113 -0
  25. package/dist/src/interfaces/mcp/server.js.map +1 -1
  26. package/dist/src/jobs/remote.d.ts +6 -0
  27. package/dist/src/jobs/remote.js.map +1 -1
  28. package/dist/src/store/index.d.ts +2 -0
  29. package/dist/src/store/index.js +2 -0
  30. package/dist/src/store/index.js.map +1 -1
  31. package/dist/src/store/memories.d.ts +13 -0
  32. package/dist/src/store/memories.js +29 -2
  33. package/dist/src/store/memories.js.map +1 -1
  34. package/dist/src/store/migrate.js +10 -1
  35. package/dist/src/store/migrate.js.map +1 -1
  36. package/dist/src/store/outbox.d.ts +1 -1
  37. package/dist/src/store/outbox.js.map +1 -1
  38. package/dist/src/store/project-alias.d.ts +13 -0
  39. package/dist/src/store/project-alias.js +55 -0
  40. package/dist/src/store/project-alias.js.map +1 -0
  41. package/dist/src/store/projects.d.ts +37 -0
  42. package/dist/src/store/projects.js +75 -0
  43. package/dist/src/store/projects.js.map +1 -0
  44. package/dist/src/store/schema.d.ts +11 -0
  45. package/dist/src/store/schema.js +55 -0
  46. package/dist/src/store/schema.js.map +1 -1
  47. package/dist/src/sync/apply.d.ts +4 -0
  48. package/dist/src/sync/apply.js +65 -3
  49. package/dist/src/sync/apply.js.map +1 -1
  50. package/dist/src/sync/backfill.d.ts +36 -0
  51. package/dist/src/sync/backfill.js +48 -0
  52. package/dist/src/sync/backfill.js.map +1 -0
  53. package/dist/src/sync/backup-store.d.ts +63 -0
  54. package/dist/src/sync/backup-store.js +173 -0
  55. package/dist/src/sync/backup-store.js.map +1 -0
  56. package/dist/src/sync/cryptoutil.d.ts +10 -2
  57. package/dist/src/sync/cryptoutil.js +22 -1
  58. package/dist/src/sync/cryptoutil.js.map +1 -1
  59. package/dist/src/sync/events.d.ts +17 -2
  60. package/dist/src/sync/events.js.map +1 -1
  61. package/dist/src/sync/orchestrate.js +5 -1
  62. package/dist/src/sync/orchestrate.js.map +1 -1
  63. package/dist/src/sync/pull.js +1 -1
  64. package/dist/src/sync/pull.js.map +1 -1
  65. package/dist/src/sync/push.d.ts +2 -0
  66. package/dist/src/sync/push.js +28 -2
  67. package/dist/src/sync/push.js.map +1 -1
  68. package/dist/src/sync/vault.d.ts +2 -1
  69. package/dist/src/sync/vault.js +2 -1
  70. package/dist/src/sync/vault.js.map +1 -1
  71. package/docs/cairn-security.md +14 -0
  72. package/docs/cairn-usage.md +99 -0
  73. package/package.json +4 -3
@@ -5,13 +5,18 @@ import { CairnError, isCairnError } from '../../core/errors.js';
5
5
  import { HOST_ADAPTERS, resolveDshHome, setDshProfile } from '../../agents/adapters.js';
6
6
  import { planAgentConfig, applyAgentConfig, planSignature, doctorAgentConfig, uninstallAgentConfig, } from '../../agents/config.js';
7
7
  import { backupDatabase, restoreFromBackup } from '../../store/backup.js';
8
+ import { scopeAllowsUpstream } from '../../core/scope.js';
8
9
  import { openStore } from '../../store/open.js';
10
+ import { addAlias, listProjects, resolveProject } from '../../store/projects.js';
9
11
  import { startConsoleServer } from '../console/server.js';
10
12
  import { exportConsoleHtml, normalizePersonalName } from '../console/export.js';
11
13
  import { readReviews, reviewPackForBatch, reviewSubmit } from '../console/review-store.js';
12
14
  import { judgementFromFlags } from '../../onboarding/judgement.js';
13
15
  import { loadPolicy, listPolicies, revokePolicy, signPolicy } from '../../onboarding/policy.js';
14
16
  import { revokeByPolicy, runAutoOnboarding } from '../../onboarding/auto.js';
17
+ import { ENV } from '../../sync/vault.js';
18
+ import { syncContext } from '../../sync/orchestrate.js';
19
+ import { uploadRemoteBackup, listRemoteBackups, restoreRemoteBackup } from '../../sync/backup-store.js';
15
20
  import { join } from 'node:path';
16
21
  /** 取值型标志;其余 --flag 一律按布尔处理,避免吞掉位置参数。 */
17
22
  const VALUE_FLAGS = new Set([
@@ -21,7 +26,13 @@ const VALUE_FLAGS = new Set([
21
26
  'home-dir', 'agent-kind', 'source-kind', 'proposed-by', 'items-file', 'batch', 'provider',
22
27
  'endpoint', 'bucket', 'prefix', 'base-url', 'recovery-file', 'port', 'input', 'item', 'export',
23
28
  'policy', 'file', 'id', 'scopes', 'max-sensitivity', 'min-confidence', 'note', 'items',
24
- 'category', 'action', 'since',
29
+ 'category', 'action', 'since', 'ids-file', 'keep', 'from-remote', 'to',
30
+ // promote / reject / doctor --archive-stale(add-candidate-promote-command +
31
+ // add-memory-importance-and-usage-signal)。漏登记会让 parseArgs 把它们当布尔
32
+ // true,str() 返回 undefined —— 命令静默不生效,且看起来"成功"。
33
+ 'scope-preset', 'scope-project', 'stale-days',
34
+ // project resolve --name(add-stable-project-identity)
35
+ 'name',
25
36
  ]);
26
37
  function parseArgs(argv) {
27
38
  const flags = {};
@@ -215,6 +226,229 @@ async function main() {
215
226
  out({ id: r.memory.id, status: r.memory.status }, flags);
216
227
  break;
217
228
  }
229
+ case 'rescope': {
230
+ // add-scope-migration D5:批注只表达意图(needs_rescope),执行留在终端——
231
+ // 与 forget --pending 同一套哲学:先列清单再逐条执行。
232
+ const preset = str(flags, 'scope-preset');
233
+ const force = flags['force'] === true;
234
+ const projectId = str(flags, 'scope-project');
235
+ if (flags['pending'] === true) {
236
+ if (!preset)
237
+ throw new CairnError('E_VALIDATION', '用法: cairn rescope --pending --scope-preset <preset> [--scope-project <id>] [--force] [--dry-run]');
238
+ const pending = service.listPendingRescope();
239
+ const dryRun = flags['dry-run'] === true;
240
+ const items = pending.map((p) => ({
241
+ annotationId: p.id,
242
+ memoryId: p.memoryId,
243
+ summary: p.memoryExcerpt,
244
+ note: p.note,
245
+ annotatedAt: p.createdAt,
246
+ memoryStatus: p.memoryStatus,
247
+ }));
248
+ if (!json) {
249
+ if (items.length === 0) {
250
+ console.log('待迁移清单为空:没有未处理的「需要迁移作用域」批注。');
251
+ }
252
+ else {
253
+ console.log(`待迁移清单 ${items.length} 条(WebUI 只是标记,作用域尚未改变):`);
254
+ for (const it of items) {
255
+ console.log(`- ${it.memoryId} ${it.summary ?? '(正文已掩码或不可用)'} · 标注于 ${it.annotatedAt}`);
256
+ }
257
+ }
258
+ }
259
+ if (dryRun) {
260
+ if (json)
261
+ out({ dryRun: true, pending: items.length, items, results: [] }, flags);
262
+ diag('--dry-run:只打印清单,未迁移任何记忆。');
263
+ break;
264
+ }
265
+ const results = [];
266
+ for (const p of pending) {
267
+ try {
268
+ if (p.memoryStatus == null) {
269
+ service.resolveAnnotation({ id: p.id, status: 'ignored', by: 'cli:rescope' });
270
+ results.push({ memoryId: p.memoryId, ok: false, reason: '记忆已不存在(批注已标记为忽略)' });
271
+ continue;
272
+ }
273
+ const r = service.rescopeMemory(p.memoryId, { scopePreset: preset, projectId, force });
274
+ service.resolveAnnotation({ id: p.id, status: 'resolved', by: 'cli:rescope' });
275
+ results.push({ memoryId: p.memoryId, ok: true, status: r.memory.status, reason: r.willLoseSync ? '已失去同步' : undefined });
276
+ }
277
+ catch (e) {
278
+ results.push({ memoryId: p.memoryId, ok: false, reason: e.message });
279
+ }
280
+ }
281
+ if (json) {
282
+ out({ dryRun: false, pending: items.length, items, results }, flags);
283
+ }
284
+ else {
285
+ for (const r of results) {
286
+ console.log(`- ${r.ok ? '已迁移' : '未处理'} ${r.memoryId}${r.reason ? `(${r.reason})` : ''}`);
287
+ }
288
+ const okCount = results.filter((r) => r.ok).length;
289
+ diag(`待迁移清单处理完毕:成功 ${okCount} 条,失败 ${results.length - okCount} 条。`);
290
+ }
291
+ break;
292
+ }
293
+ if (!preset)
294
+ throw new CairnError('E_VALIDATION', '用法: cairn rescope <id> --scope-preset <preset> [--scope-project <id>] [--force];或 cairn rescope --pending --scope-preset <preset>');
295
+ const idsFile = str(flags, 'ids-file');
296
+ let ids = [];
297
+ if (idsFile) {
298
+ const { readFileSync } = await import('node:fs');
299
+ ids = readFileSync(idsFile, 'utf8').split(/\r?\n/).map((l) => l.trim()).filter((l) => l.length > 0 && !l.startsWith('#'));
300
+ }
301
+ else if (args[0]) {
302
+ ids = [args[0]];
303
+ }
304
+ if (ids.length === 0)
305
+ throw new CairnError('E_VALIDATION', '用法: cairn rescope <id> --scope-preset <preset>;批量迁移用 --ids-file <file>(每行一个 id)');
306
+ // 预检汇总(只读探测,不代表执行判定;执行判定在 rescopeMemory 内):
307
+ // 将迁移 N 条,其中 M 条将失去同步,K 条预计被拒绝。
308
+ const target = service.resolveScope({ preset: preset, projectId });
309
+ let loseCount = 0;
310
+ const refusedPreview = [];
311
+ for (const id of ids) {
312
+ try {
313
+ const mem = service.store.memories.require(id);
314
+ const cur = service.store.scopes.requireById(mem.scopeId);
315
+ if (scopeAllowsUpstream(cur) && !scopeAllowsUpstream(target))
316
+ loseCount += 1;
317
+ if (mem.status === 'conflicted')
318
+ refusedPreview.push(`${id.slice(0, 8)} 冲突中`);
319
+ else if (mem.authority === 'user_explicit' && !force)
320
+ refusedPreview.push(`${id.slice(0, 8)} 需 --force`);
321
+ }
322
+ catch {
323
+ refusedPreview.push(`${id.slice(0, 8)} 不存在`);
324
+ }
325
+ }
326
+ if (!json) {
327
+ console.log(`将迁移 ${ids.length} 条 → ${target.preset}${projectId ? `(${projectId.slice(0, 8)})` : ''},其中 ${loseCount} 条将失去跨设备同步${loseCount > 0 ? '(迁移到 local_only 作用域后不再上行;云端旧密文不会自动删除)' : ''}。`);
328
+ if (refusedPreview.length > 0)
329
+ diag(`预计被拒绝 ${refusedPreview.length} 条:${refusedPreview.join(';')}`);
330
+ }
331
+ const results = [];
332
+ for (const id of ids) {
333
+ // 单条显式指定时失败必须硬退出(退出码合同:用法 2 / 治理拒绝 3 / 冲突 4);
334
+ // 只有 --ids-file 批量才逐条软报告(spec:单条失败不中断其余条目)。
335
+ if (idsFile) {
336
+ try {
337
+ const r = service.rescopeMemory(id, { scopePreset: preset, projectId, force });
338
+ results.push({ id, ok: true, toScope: r.scope.id, willLoseSync: r.willLoseSync });
339
+ }
340
+ catch (e) {
341
+ results.push({ id, ok: false, reason: e.message });
342
+ }
343
+ }
344
+ else {
345
+ const r = service.rescopeMemory(id, { scopePreset: preset, projectId, force });
346
+ results.push({ id, ok: true, toScope: r.scope.id, willLoseSync: r.willLoseSync });
347
+ }
348
+ }
349
+ if (json) {
350
+ out({ total: ids.length, willLoseSync: loseCount, targetScope: target.id, results }, flags);
351
+ }
352
+ else {
353
+ for (const r of results) {
354
+ console.log(`- ${r.ok ? '已迁移' : '拒绝'} ${r.id}${r.ok ? ` → ${r.toScope}${r.willLoseSync ? '(失去同步)' : ''}` : `(${r.reason})`}`);
355
+ }
356
+ const okCount = results.filter((r) => r.ok).length;
357
+ diag(`迁移完毕:成功 ${okCount} 条,失败 ${results.length - okCount} 条。`);
358
+ }
359
+ break;
360
+ }
361
+ case 'revision': {
362
+ // add-agent-managed-revision D1:采纳与拒绝是人的动作,只在这里(CLI)与本地控制台。
363
+ const sub = args[0];
364
+ const rest = args.slice(1);
365
+ if (sub === 'list') {
366
+ const status = str(flags, 'status') ?? 'pending';
367
+ const items = service.listRevisionProposals({ status, limit: flags['limit'] != null ? Number(flags['limit']) : undefined });
368
+ if (json) {
369
+ out({ status, total: items.length, items }, flags);
370
+ }
371
+ else {
372
+ diag(`修订提案(${status})共 ${items.length} 条`);
373
+ for (const r of items) {
374
+ console.log(`- ${r.id} [${r.status}${r.stale ? '·已陈旧' : ''}] ${r.memoryId.slice(0, 8)} ${r.beforeExcerpt ?? '(正文已掩码)'} → ${r.afterContent.split('\n')[0]?.slice(0, 60) ?? ''} · ${r.proposedBy} ${r.proposedAt}`);
375
+ }
376
+ if (items.length === 0)
377
+ diag('没有匹配的提案。全部状态用 --status all。');
378
+ }
379
+ break;
380
+ }
381
+ if (sub === 'show') {
382
+ const id = rest[0];
383
+ if (!id)
384
+ throw new CairnError('E_VALIDATION', '用法: cairn revision show <id>');
385
+ const r = service.listRevisionProposals({ status: 'all' }).find((x) => x.id === id);
386
+ if (!r)
387
+ throw new CairnError('E_NOT_FOUND', `提案不存在: ${id}`);
388
+ const mem = r.memoryExists ? service.store.memories.require(r.memoryId) : null;
389
+ if (json) {
390
+ out(r, flags);
391
+ }
392
+ else {
393
+ console.log(`提案 ${r.id} [${r.status}${r.stale ? '·已陈旧' : ''}]`);
394
+ console.log(`记忆 ${r.memoryId}${mem ? `(当前状态 ${mem.status})` : '(已不存在)'}`);
395
+ console.log(`提出 ${r.proposedBy} · ${r.proposedAt}${r.annotationId ? ` · 关联批注 ${r.annotationId}` : ''}`);
396
+ console.log(`理由 ${r.reason}`);
397
+ console.log('--- 改前(当前正文)---');
398
+ console.log(mem ? mem.content : '(记忆已删除,无法对照)');
399
+ console.log('--- 改后(提案正文)---');
400
+ console.log(r.afterContent);
401
+ if (r.rejectReason)
402
+ console.log(`拒绝理由:${r.rejectReason}`);
403
+ if (r.status === 'pending')
404
+ diag('待确认:采纳执行 cairn revision apply <id>;拒绝执行 cairn revision reject <id> "理由"');
405
+ }
406
+ break;
407
+ }
408
+ if (sub === 'apply') {
409
+ const ids = flags['all'] === true
410
+ ? service.listRevisionProposals({ status: 'pending' }).map((x) => x.id)
411
+ : [rest[0] ?? ''];
412
+ if (ids.length === 0 || ids[0] === '')
413
+ throw new CairnError('E_VALIDATION', '用法: cairn revision apply <id>;或 cairn revision apply --all(逐条应用)');
414
+ const results = [];
415
+ for (const id of ids) {
416
+ // 单条显式指定时失败必须硬退出(陈旧退 4);--all 才逐条软报告(spec:单条失败不影响其余)
417
+ if (flags['all'] === true) {
418
+ try {
419
+ const r = service.applyRevisionProposal(id);
420
+ results.push({ id, ok: true, status: r.memory.status });
421
+ }
422
+ catch (e) {
423
+ results.push({ id, ok: false, reason: e.message });
424
+ }
425
+ }
426
+ else {
427
+ const r = service.applyRevisionProposal(id);
428
+ results.push({ id, ok: true, status: r.memory.status });
429
+ }
430
+ }
431
+ if (json) {
432
+ out({ applied: results.filter((r) => r.ok).length, results }, flags);
433
+ }
434
+ else {
435
+ for (const r of results) {
436
+ console.log(`- ${r.ok ? '已采纳' : '未采纳'} ${r.id}${r.reason ? `(${r.reason})` : ''}`);
437
+ }
438
+ }
439
+ break;
440
+ }
441
+ if (sub === 'reject') {
442
+ const id = rest[0];
443
+ const reason = rest.slice(1).join(' ').trim();
444
+ if (!id || reason === '')
445
+ throw new CairnError('E_VALIDATION', '用法: cairn revision reject <id> "<理由>"');
446
+ const r = service.rejectRevisionProposal(id, reason);
447
+ out({ id: r.id, status: r.status }, flags);
448
+ break;
449
+ }
450
+ throw new CairnError('E_VALIDATION', '用法: cairn revision list [--status pending|applied|rejected|stale|all] | show <id> | apply <id>|--all | reject <id> "<理由>"');
451
+ }
218
452
  case 'audit': {
219
453
  // 只读审计查询(add-operation-audit):cairn audit list [--category --action --since --limit] [--json]
220
454
  if (args[0] !== 'list')
@@ -239,8 +473,72 @@ async function main() {
239
473
  break;
240
474
  }
241
475
  case 'forget': {
476
+ // add-memory-annotations D3:WebUI 只能标记 pending_forget,真正删除只在这里。
477
+ // MUST 先打印全部待删清单,再逐条执行并逐条报告(spec「命令行批量确认」)。
478
+ if (flags['pending'] === true) {
479
+ const pending = service.listPendingForget();
480
+ const dryRun = flags['dry-run'] === true;
481
+ const items = pending.map((p) => ({
482
+ annotationId: p.id,
483
+ memoryId: p.memoryId,
484
+ summary: p.memoryExcerpt,
485
+ note: p.note,
486
+ annotatedAt: p.createdAt,
487
+ memoryStatus: p.memoryStatus,
488
+ }));
489
+ if (!json) {
490
+ if (items.length === 0) {
491
+ console.log('待删清单为空:没有未处理的「标记待删」批注。');
492
+ }
493
+ else {
494
+ console.log(`待删清单 ${items.length} 条(WebUI 只是标记,记忆仍是活动状态):`);
495
+ for (const it of items) {
496
+ console.log(`- ${it.memoryId} ${it.summary ?? '(正文已掩码或不可用)'} · 标注于 ${it.annotatedAt}`);
497
+ }
498
+ }
499
+ }
500
+ if (dryRun) {
501
+ if (json)
502
+ out({ dryRun: true, pending: items.length, items, results: [] }, flags);
503
+ diag('--dry-run:只打印清单,未删除任何记忆。');
504
+ break;
505
+ }
506
+ const results = [];
507
+ for (const p of pending) {
508
+ try {
509
+ if (p.memoryStatus == null) {
510
+ // 记忆已不存在:批注留着只会永远挂在待办里,标记为忽略(不是删除动作)。
511
+ service.resolveAnnotation({ id: p.id, status: 'ignored', by: 'cli:forget' });
512
+ results.push({ memoryId: p.memoryId, ok: false, reason: '记忆已不存在(批注已标记为忽略)' });
513
+ continue;
514
+ }
515
+ if (p.memoryStatus === 'tombstoned') {
516
+ service.resolveAnnotation({ id: p.id, status: 'resolved', by: 'cli:forget' });
517
+ results.push({ memoryId: p.memoryId, ok: true, status: 'tombstoned', reason: '此前已是墓碑' });
518
+ continue;
519
+ }
520
+ const m = service.forgetMemory(p.memoryId, p.note.length > 0 ? `待删清单:${p.note}` : '待删清单确认(cairn forget --pending)');
521
+ service.resolveAnnotation({ id: p.id, status: 'resolved', by: 'cli:forget' });
522
+ results.push({ memoryId: p.memoryId, ok: true, status: m.status });
523
+ }
524
+ catch (e) {
525
+ results.push({ memoryId: p.memoryId, ok: false, reason: e.message });
526
+ }
527
+ }
528
+ if (json) {
529
+ out({ dryRun: false, pending: items.length, items, results }, flags);
530
+ }
531
+ else {
532
+ for (const r of results) {
533
+ console.log(`- ${r.ok ? '已遗忘' : '未处理'} ${r.memoryId}${r.status ? ` → ${r.status}` : ''}${r.reason ? `(${r.reason})` : ''}`);
534
+ }
535
+ const okCount = results.filter((r) => r.ok).length;
536
+ diag(`待删清单处理完毕:成功 ${okCount} 条,失败 ${results.length - okCount} 条。`);
537
+ }
538
+ break;
539
+ }
242
540
  if (!args[0])
243
- throw new CairnError('E_VALIDATION', '用法: cairn forget <id> [--reason "..."]');
541
+ throw new CairnError('E_VALIDATION', '用法: cairn forget <id> [--reason "..."];或 cairn forget --pending [--dry-run]');
244
542
  const m = service.forgetMemory(args[0], str(flags, 'reason') ?? null);
245
543
  out({ id: m.id, status: m.status }, flags);
246
544
  break;
@@ -284,12 +582,74 @@ async function main() {
284
582
  break;
285
583
  }
286
584
  case 'backup': {
585
+ // add-cloud-backup:--upload 走加密上传(独立前缀 + 设备密钥);默认仍是本地快照。
586
+ if (flags['list-remote'] === true) {
587
+ const ctx = syncContext(service.store);
588
+ if (!ctx)
589
+ throw new CairnError('E_VALIDATION', '远端未配置:先 cairn vault init-remote(备份通道与同步共用同一远端配置)');
590
+ const items = await listRemoteBackups(ctx.remote, service.store.identity.deviceId);
591
+ if (json) {
592
+ out({ device: service.store.identity.deviceId, total: items.length, items }, flags);
593
+ }
594
+ else {
595
+ diag(`设备 ${service.store.identity.deviceId} 的远端备份共 ${items.length} 份:`);
596
+ for (const it of items) {
597
+ console.log(`- ${it.name} ${(it.sealedBytes / 1024).toFixed(1)} KB · ${it.uploadedAt ?? '时间未知'}`);
598
+ }
599
+ }
600
+ break;
601
+ }
602
+ if (flags['upload'] === true) {
603
+ const ctx = syncContext(service.store);
604
+ if (!ctx)
605
+ throw new CairnError('E_VALIDATION', '远端未配置:先 cairn vault init-remote(备份必须端到端加密上传,不产生明文产物)');
606
+ const r = await uploadRemoteBackup(service.store, ctx.remote, ctx.vault, {
607
+ keep: flags['keep'] != null ? Number(flags['keep']) : undefined,
608
+ targetPath: str(flags, 'out'),
609
+ });
610
+ if (json) {
611
+ out(r, flags);
612
+ }
613
+ else {
614
+ console.log(`已上传 ${r.key}(密文 ${(r.sealedBytes / 1024).toFixed(1)} KB,明文快照 ${r.localSnapshot.path})`);
615
+ if (r.pruned.length > 0) {
616
+ for (const p of r.pruned)
617
+ console.log(`已按保留策略淘汰:${p}`);
618
+ }
619
+ if (r.pruneWarning)
620
+ diag(r.pruneWarning);
621
+ }
622
+ break;
623
+ }
287
624
  const target = str(flags, 'out') ?? join(service.store.paths.backupsDir, `cairn-backup-${Date.now()}.db`);
288
625
  const b = backupDatabase(service.store.db, target);
289
626
  out(b, flags);
290
627
  break;
291
628
  }
292
629
  case 'restore': {
630
+ // add-cloud-backup D5:远端恢复默认到新路径,绝不覆盖当前库;
631
+ // --force 的顺序是「先自动备份当前库 → 还原到暂存路径(全部校验)→ 通过才关库覆盖」。
632
+ const fromRemote = str(flags, 'from-remote');
633
+ if (fromRemote) {
634
+ const ctx = syncContext(service.store);
635
+ if (!ctx)
636
+ throw new CairnError('E_VALIDATION', '远端未配置:先 cairn vault init-remote');
637
+ if (flags['force'] === true) {
638
+ const safety = backupDatabase(service.store.db, join(service.store.paths.backupsDir, `pre-restore-${Date.now()}.db`));
639
+ diag(`已自动备份当前库:${safety.path}`);
640
+ // 先走完整校验链还原到暂存路径;任何一步失败都会抛错,当前库不受影响
641
+ const staging = await restoreRemoteBackup(service.store, ctx.remote, ctx.vault, fromRemote, {});
642
+ service.close();
643
+ const { resolvePaths } = await import('../../store/open.js');
644
+ const paths = resolvePaths(home ?? (process.env['CAIRN_HOME'] ?? ''));
645
+ restoreFromBackup(staging.restoredTo, paths.dbPath);
646
+ out({ overwritten: paths.dbPath, stagedFrom: staging.restoredTo, plainSha256: staging.plainSha256, safetyBackup: safety.path }, flags);
647
+ break;
648
+ }
649
+ const r = await restoreRemoteBackup(service.store, ctx.remote, ctx.vault, fromRemote, { toDir: str(flags, 'to') });
650
+ out({ restoredTo: r.restoredTo, plainSha256: r.plainSha256, verified: r.verified }, flags);
651
+ break;
652
+ }
293
653
  const backupPath = args[0];
294
654
  if (!backupPath)
295
655
  throw new CairnError('E_VALIDATION', '用法: cairn restore <backup.db> [--home <dir>]');
@@ -339,6 +699,33 @@ async function main() {
339
699
  out(service.status(), flags);
340
700
  break;
341
701
  }
702
+ case 'project': {
703
+ // 稳定项目身份(add-stable-project-identity D6):与 MCP 共用 store/projects.ts。
704
+ const sub = args[0] ?? 'list';
705
+ if (sub === 'resolve') {
706
+ const target = args[1];
707
+ if (!target)
708
+ throw new CairnError('E_VALIDATION', '用法: cairn project resolve <path-or-url> [--name N]');
709
+ out(resolveProject(service.store.db, target, { name: str(flags, 'name') }), flags);
710
+ }
711
+ else if (sub === 'list') {
712
+ const items = listProjects(service.store.db);
713
+ out({ count: items.length, items }, flags);
714
+ }
715
+ else if (sub === 'alias') {
716
+ if (args[1] !== 'add')
717
+ throw new CairnError('E_VALIDATION', '用法: cairn project alias add <project-id> <path-or-url>');
718
+ const projectId = args[2];
719
+ const target = args[3];
720
+ if (!projectId || !target)
721
+ throw new CairnError('E_VALIDATION', '用法: cairn project alias add <project-id> <path-or-url>');
722
+ out(addAlias(service.store.db, projectId, target), flags);
723
+ }
724
+ else {
725
+ throw new CairnError('E_VALIDATION', '用法: cairn project resolve <path-or-url> | list | alias add <project-id> <path-or-url>');
726
+ }
727
+ break;
728
+ }
342
729
  case 'vault': {
343
730
  const sub = args[0];
344
731
  if (sub === 'init-remote') {
@@ -352,7 +739,7 @@ async function main() {
352
739
  bucket: str(flags, 'bucket') ?? throwUsage('--bucket 必填'),
353
740
  prefix: str(flags, 'prefix') ?? 'cairn/',
354
741
  } : undefined,
355
- syncd: provider === 'syncd' ? { baseUrl: str(flags, 'base-url') ?? throwUsage('--base-url 必填') } : undefined,
742
+ syncd: provider === 'syncd' ? { baseUrl: str(flags, 'base-url') ?? (process.env[ENV.syncdUrl] || throwUsage('--base-url 必填(或用环境变量 CAIRN_SYNCD_URL)')) } : undefined,
356
743
  });
357
744
  out({ vaultId: r.vault.vaultId, provider: r.vault.provider, recovery: r.recovery, warning: '恢复材料请抄写到安全位置;密钥丢失 = 云端数据不可恢复' }, flags);
358
745
  }
@@ -385,8 +772,22 @@ async function main() {
385
772
  else if (sub === 'pull') {
386
773
  out(await service.syncPullCmd(), flags);
387
774
  }
775
+ else if (sub === 'backfill') {
776
+ // 冷启动对账:默认只读;只写本地 outbox,不与云端交互(spec cloud-sync)。
777
+ const rawLimit = str(flags, 'limit');
778
+ const limit = rawLimit == null ? undefined : Number(rawLimit);
779
+ if (limit !== undefined && (!Number.isInteger(limit) || limit <= 0)) {
780
+ throw new CairnError('E_VALIDATION', '--limit 必须是正整数');
781
+ }
782
+ const apply = flags['apply'] === true;
783
+ const r = service.syncBackfillCmd({ apply, limit });
784
+ out(r, flags);
785
+ diag(apply
786
+ ? `已新增 ${r.enqueued} 条上行任务,已存在 ${r.existing} 条,排除 ${r.excluded} 条(只写本地队列,未与云端交互)`
787
+ : `只读预演:候选 ${r.candidates} 条;加 --apply 才写本地队列(不与云端交互)`);
788
+ }
388
789
  else {
389
- throw new CairnError('E_VALIDATION', '用法: cairn sync push|pull');
790
+ throw new CairnError('E_VALIDATION', '用法: cairn sync push|pull|backfill [--apply] [--limit N]');
390
791
  }
391
792
  break;
392
793
  }
@@ -782,48 +1183,60 @@ function openBrowser(url) {
782
1183
  }
783
1184
  })();
784
1185
  }
785
- const HELP = `Cairn — 个人、多设备、多 Agent 的本地优先记忆主权层
786
-
787
- 用法: cairn <command> [args] [options]
788
-
789
- 命令:
790
- init 初始化数据目录并执行首次体检
791
- discover 元数据发现(不读正文) [--home-dir] [--project-root]
792
- import <文件...> 不可变快照导入(imported_unverified + local_only) [--agent-kind]
793
- onboarding status|next|auto 分批进度与待整理条目 [--batch] [--limit]
794
- skipped: 查看已跳过条目(出队但可查)[--batch] [--limit]
795
- auto: 按已签发策略自动整理 [--policy <id>] [--dry-run] [--redo] [--items a,b]
796
- revoke: 回滚某策略写进去的记忆(转墓碑)[--policy <id>] [--batch <id>]
797
- add "内容" 显式新增记忆 [--kind] [--scope] [--project] [--sensitive]
798
- [--judgement keep|skip|merge_into:<id> --confidence --rationale]
799
- search "关键词" 作用域约束检索 [--status] [--scope-id] [--include-expired]
800
- show <id> 记忆详情(修订/证据/冲突)
801
- update <id> "新内容" 用户更正(新修订,历史保留)
802
- forget <id> 遗忘(可审计 tombstone) [--reason]
803
- archive <id> 归档
804
- export 导出 [--format json|markdown] [--out FILE] [--include-archives]
805
- plan create|show|list 治理计划(create 需 --items-file,零写入)
806
- approve <plan-id> 本地签发一次性审批(绑定 plan_hash,30 分钟有效)
807
- apply <plan-id> --approval X 消费审批并幂等应用计划
808
- review pack|submit|list 双层建议的复核包与写回 [--batch] [--out] [--input]
809
- policy sign|list|show|revoke 自动整理策略(签发只在终端或本机控制台)[--file] [--id] [--force]
810
- ui 只读控制台(回环 HTTP;端口默认 7767,占用则随机)
811
- [--port N] [--no-open] [--export <file.html>] [--redact]
812
- vault init-remote|status|export-key|import-key 云同步 vault(OBS / 自建 syncd)
813
- sync push|pull 加密同步上行 / 下行(详见 docs/cairn-sync.md)
814
- backup / restore 一致性备份与恢复
815
- doctor 健康检查 [--host <agent>](诚实分级,无模型无云端核心可用)
816
- status 库状态摘要
817
- worker run-once 处理一轮后台任务 [--max N](默认不安装任何 hook)
818
- device status|re-enroll 设备身份与克隆恢复
819
- agent plan|apply|doctor|uninstall --host <agent> 宿主配置管理(plan 零写入);--host dsh 用于 DeepSeek Harness(Cordis 插件树,可加 --dsh-profile)
820
- uninstall 移除所有本产品宿主配置(数据库保留)
821
-
822
- 全局选项:
823
- --home <dir> 数据目录(默认 ~/.cairn;测试用 CAIRN_HOME)
824
- --json 机器可读输出(stdout 仅结果;诊断走 stderr)
825
- --agent-id <id> 调用方 Agent 身份(默认 cli)
826
-
1186
+ const HELP = `Cairn — 个人、多设备、多 Agent 的本地优先记忆主权层
1187
+
1188
+ 用法: cairn <command> [args] [options]
1189
+
1190
+ 命令:
1191
+ init 初始化数据目录并执行首次体检
1192
+ discover 元数据发现(不读正文) [--home-dir] [--project-root]
1193
+ import <文件...> 不可变快照导入(imported_unverified + local_only) [--agent-kind]
1194
+ onboarding status|next|auto 分批进度与待整理条目 [--batch] [--limit]
1195
+ skipped: 查看已跳过条目(出队但可查)[--batch] [--limit]
1196
+ auto: 按已签发策略自动整理 [--policy <id>] [--dry-run] [--redo] [--items a,b]
1197
+ revoke: 回滚某策略写进去的记忆(转墓碑)[--policy <id>] [--batch <id>]
1198
+ add "内容" 显式新增记忆 [--kind] [--scope] [--project] [--sensitive]
1199
+ [--judgement keep|skip|merge_into:<id> --confidence --rationale]
1200
+ search "关键词" 作用域约束检索 [--status] [--scope-id] [--include-expired]
1201
+ show <id> 记忆详情(修订/证据/冲突)
1202
+ update <id> "新内容" 用户更正(新修订,历史保留)
1203
+ forget <id> 遗忘(可审计 tombstone) [--reason]
1204
+ --pending 先列出 WebUI 标记的待删清单,再逐条遗忘 [--dry-run]
1205
+ rescope <id> 作用域迁移(不改状态/权威/正文) [--scope-preset] [--scope-project]
1206
+ --pending 先列出 WebUI 标记的待迁移清单,再逐条迁移 [--dry-run]
1207
+ [--force](user_explicit 记忆需显式确认)[--ids-file FILE]
1208
+ revision list|show|apply|reject AI 修订提案(方案卡):Agent 只能提案,采纳/拒绝是人的动作
1209
+ list [--status pending|applied|rejected|stale|all];apply <id>|--all;reject <id> "理由"
1210
+ archive <id> 归档
1211
+ export 导出 [--format json|markdown] [--out FILE] [--include-archives]
1212
+ plan create|show|list 治理计划(create 需 --items-file,零写入)
1213
+ approve <plan-id> 本地签发一次性审批(绑定 plan_hash,30 分钟有效)
1214
+ apply <plan-id> --approval X 消费审批并幂等应用计划
1215
+ review pack|submit|list 双层建议的复核包与写回 [--batch] [--out] [--input]
1216
+ policy sign|list|show|revoke 自动整理策略(签发只在终端或本机控制台)[--file] [--id] [--force]
1217
+ ui 只读控制台(回环 HTTP;端口默认 7767,占用则随机)
1218
+ [--port N] [--no-open] [--export <file.html>] [--redact]
1219
+ vault init-remote|status|export-key|import-key 云同步 vault(OBS / 自建 syncd;syncd 的 --base-url 可省,取 CAIRN_SYNCD_URL)
1220
+ sync push|pull|backfill 加密同步上行 / 下行;backfill 补齐未入队的上行任务
1221
+ [--apply] [--limit N](默认只读,不与云端交互;详见 docs/cairn-sync.md)
1222
+ backup / restore 一致性备份与恢复
1223
+ --upload 加密上传到远端(独立前缀 backups/<设备>/)[--keep N](默认保留 5 份)
1224
+ --list-remote 列出本设备的远端备份(名称/时间/密文字节)
1225
+ restore --from-remote <name> 下载解密校验后还原;默认到新路径,--force 覆盖当前库前自动备份之 [--to <dir>]
1226
+ doctor 健康检查 [--host <agent>](诚实分级,无模型无云端核心可用)
1227
+ status 库状态摘要
1228
+ project resolve|list 项目身份:id 是 UUID,路径/URL 只作别名
1229
+ resolve <path-or-url> [--name N];alias add <project-id> <path-or-url>
1230
+ worker run-once 处理一轮后台任务 [--max N](默认不安装任何 hook)
1231
+ device status|re-enroll 设备身份与克隆恢复
1232
+ agent plan|apply|doctor|uninstall --host <agent> 宿主配置管理(plan 零写入);--host dsh 用于 DeepSeek Harness(Cordis 插件树,可加 --dsh-profile)
1233
+ uninstall 移除所有本产品宿主配置(数据库保留)
1234
+
1235
+ 全局选项:
1236
+ --home <dir> 数据目录(默认 ~/.cairn;测试用 CAIRN_HOME)
1237
+ --json 机器可读输出(stdout 仅结果;诊断走 stderr)
1238
+ --agent-id <id> 调用方 Agent 身份(默认 cli)
1239
+
827
1240
  退出码: 0 成功; 1 故障; 2 用法/校验; 3 被治理拒绝; 4 状态冲突; 5 环境不可用`;
828
1241
  export async function runCli() {
829
1242
  try {