@jjh32456/dsh-longlive 1.6.7 → 1.8.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.
- package/CHANGELOG.md +70 -1508
- package/LICENSE +1 -1
- package/QUICKSTART.md +34 -13
- package/README.en.md +18 -7
- package/README.md +34 -9
- package/SPEC.md +5 -5
- package/cordis.patch.yml +23 -9
- package/docs/ANSWER-GUARD.md +92 -0
- package/docs/ARCHITECTURE.md +4 -3
- package/docs/AUTO-RECALL-WIRING.md +1 -1
- package/docs/AUTO-RECALL.md +15 -9
- package/docs/CONFIG.md +168 -35
- package/docs/ERRORS.md +17 -5
- package/docs/FAQ.md +7 -7
- package/docs/FEATURES.md +96 -28
- package/docs/MIGRATION-1.6.0.md +2 -2
- package/docs/OPERATIONS.md +6 -6
- package/docs/PANEL-INTEGRATION.md +6 -0
- package/docs/PRIVACY.md +88 -0
- package/docs/QUICKSTART.md +5 -5
- package/docs/README.en.md +4 -2
- package/docs/RESIDENT-WATCHER.md +1 -1
- package/docs/SESSION-WATCH.md +6 -6
- package/docs/TROUBLESHOOTING.md +4 -4
- package/package.json +47 -117
- package/runbook.md +2 -2
- package/scripts/backfill-auto-cards.mjs +98 -0
- package/scripts/install-surgery-task.ps1 +5 -2
- package/scripts/lib/session-watch-fixture.mjs +1 -1
- package/scripts/longlive-doctor.mjs +6 -0
- package/scripts/migrate-180.mjs +163 -0
- package/scripts/recall-index-build.mjs +128 -0
- package/scripts/session-watch-drill.mjs +1 -1
- package/scripts/surgery-run.cmd +1 -1
- package/scripts/unattended-surgery.ps1 +5 -2
- package/scripts/verify-card-anchors.mjs +138 -0
- package/src/actions/audit.js +125 -0
- package/src/actions/evidence.js +122 -0
- package/src/actions/fs.js +162 -0
- package/src/activity/index.js +760 -0
- package/src/activity/model.js +351 -0
- package/src/activity/store.js +644 -0
- package/src/activity/thinking.js +176 -0
- package/src/adapters/constants.js +11 -0
- package/src/adapters/engram/data/aliases.json +51 -0
- package/src/adapters/engram/data/policy.json +8 -0
- package/src/adapters/engram/data/routing-rules.json +546 -0
- package/src/adapters/engram/index.js +235 -0
- package/src/adapters/registry.js +315 -0
- package/src/answer/audit.js +193 -0
- package/src/answer/evidence.js +30 -0
- package/src/answer/guard.js +1370 -0
- package/src/answer/index.js +1067 -0
- package/src/answer/query.js +111 -0
- package/src/answer/second-hop.mjs +101 -0
- package/src/auto-truncate.js +1 -1
- package/src/config.js +171 -47
- package/src/deps.js +6 -4
- package/src/features.js +182 -6
- package/src/heartbeat.js +156 -23
- package/src/identity/handover.js +52 -1
- package/src/identity/index.js +13 -5
- package/src/identity/inject-position.js +2 -2
- package/src/index.js +97 -7
- package/src/lifecycle/gap-clocks.js +328 -0
- package/src/lifecycle/index.js +269 -0
- package/src/live.js +22 -2
- package/src/memory/activity-capture.js +229 -0
- package/src/memory/anchors.js +194 -0
- package/src/memory/audit-records.js +222 -0
- package/src/memory/auto-cards.js +401 -0
- package/src/memory/capture.js +442 -0
- package/src/memory/card-anchors.js +203 -0
- package/src/memory/conflicts.js +106 -0
- package/src/memory/decay.js +311 -0
- package/src/memory/distill.js +471 -0
- package/src/memory/event-index.js +917 -0
- package/src/memory/evidence-chain.js +295 -0
- package/src/memory/evidence.js +145 -0
- package/src/memory/filter-runner.js +1 -1
- package/src/memory/filter.js +5 -1
- package/src/memory/forget-v2.js +410 -0
- package/src/memory/forget.js +71 -0
- package/src/memory/frames-activation.js +247 -0
- package/src/memory/fts-query.js +174 -0
- package/src/memory/governance.js +604 -0
- package/src/memory/index.js +1 -0
- package/src/memory/l2-gate.js +169 -0
- package/src/memory/lock.js +121 -0
- package/src/memory/migrate.js +139 -0
- package/src/memory/recall-v2.js +223 -0
- package/src/memory/recall.js +65 -2
- package/src/memory/records.js +425 -0
- package/src/memory/retention.js +128 -0
- package/src/memory/review.js +124 -0
- package/src/memory/trust.js +88 -0
- package/src/memory/version-chain.js +264 -0
- package/src/memory/wal.js +137 -0
- package/src/memory/working-frame.js +516 -0
- package/src/metrics/classify.mjs +5 -3
- package/src/metrics/index.mjs +21 -1
- package/src/metrics/prestep-latency.mjs +300 -0
- package/src/metrics/store.mjs +25 -0
- package/src/policy-profile.js +18 -3
- package/src/recall/anaphora.mjs +87 -0
- package/src/recall/cards.mjs +7 -0
- package/src/recall/embedding.mjs +8 -8
- package/src/recall/entities.mjs +112 -0
- package/src/recall/index.js +235 -19
- package/src/recall/inject-order.mjs +10 -8
- package/src/recall/privacy.mjs +105 -16
- package/src/recall/recall-core.mjs +116 -10
- package/src/recall/shared-visibility.js +302 -0
- package/src/recall/time-normalizer.mjs +196 -0
- package/src/role/activation.js +191 -0
- package/src/role/attention.js +318 -0
- package/src/role/base.js +36 -0
- package/src/role/channels.js +423 -0
- package/src/role/index.js +425 -0
- package/src/role/interfaces.js +115 -0
- package/src/role/personality.js +370 -0
- package/src/role/readers.js +151 -0
- package/src/role/relationships.js +477 -0
- package/src/role/store.js +202 -0
- package/src/role/writeprotect.js +373 -0
- package/src/router/aliases.json +176 -25
- package/src/router/background/agent-runner.mjs +1 -1
- package/src/router/background/anchor.mjs +1 -1
- package/src/router/background/audit.mjs +2 -2
- package/src/router/background/budget-ledger.mjs +2 -2
- package/src/router/background/host-sim.mjs +1 -1
- package/src/router/background/memory.mjs +4 -4
- package/src/router/background/queue.mjs +1 -1
- package/src/router/background/retry.mjs +1 -1
- package/src/router/background/router.mjs +1 -1
- package/src/router/background/stream.mjs +1 -1
- package/src/router/background/tool-policy.mjs +1 -1
- package/src/router/design-headings.json +5 -5
- package/src/router/face/config.mjs +1 -1
- package/src/router/face/identity.mjs +3 -3
- package/src/router/judge.mjs +8 -7
- package/src/router/policies/generic.json +21 -4
- package/src/router/route.js +109 -22
- package/src/router/router.mjs +10 -6
- package/src/router/routing-rules.json +260 -445
- package/src/router/run-sim.mjs +8 -8
- package/src/router/runtime.js +23 -12
- package/src/router/service/board.mjs +95 -15
- package/src/router/service/config.mjs +5 -5
- package/src/router/service/context.mjs +1 -1
- package/src/router/service/hint.mjs +14 -0
- package/src/router/service/queue.mjs +1 -1
- package/src/router/service/service.mjs +27 -11
- package/src/router/shadow.mjs +4 -3
- package/src/surgery-recovery.js +2 -2
- package/src/tool-output.js +2 -2
- package/src/tools.js +39 -7
- package/src/truncate-visible.js +2 -2
- package/src/ui/actions.js +1312 -0
- package/src/ui/panel-api.js +367 -0
- package/src/ui/panel-auth.js +251 -0
- package/src/ui/panel-integrity.js +243 -0
- package/src/ui/routes-readonly.js +695 -0
- package/src/ui/routes.js +3 -0
- package/docs/DEV.md +0 -279
- package/docs/PRESENCE-BUS-WIRING.md +0 -491
- package/docs/PRESENCE-BUS.md +0 -694
- package/docs/SURGERY.md +0 -186
- package/scripts/mark-core-cards.mjs +0 -289
- package/scripts/pack.mjs +0 -392
- package/scripts/router-proposals.mjs +0 -386
- package/src/router/fixtures/M1.json +0 -16
- package/src/router/fixtures/M2.json +0 -16
- package/src/router/fixtures/M3.json +0 -20
- package/src/router/fixtures/M4.json +0 -20
- package/src/router/fixtures/M5.json +0 -45
- package/src/router/fixtures/M6.json +0 -53
- package/src/router/fixtures/M7.json +0 -46
- package/src/router/fixtures/S1.json +0 -20
- package/src/router/fixtures/S2.json +0 -23
- package/src/router/fixtures/S3.json +0 -20
- package/src/router/fixtures/S4.json +0 -34
- package/src/router/fixtures/S5.json +0 -43
- package/src/router/fixtures/S6.json +0 -47
- package/src/router/fixtures/T1.json +0 -23
- package/src/router/fixtures/T2.json +0 -16
- package/src/router/fixtures/T3.json +0 -19
- package/src/router/fixtures/T4.json +0 -16
- package/src/router/fixtures/X1.json +0 -17
- package/src/router/fixtures/X2.json +0 -20
- package/src/router/gen-design-headings.mjs +0 -107
- package/src/router/policies/owner-rulings-2026-11-03.json +0 -62
- package/test/auto-recall.test.mjs +0 -474
- package/test/auto-truncate.test.mjs +0 -931
- package/test/autobind.test.mjs +0 -385
- package/test/bus.test.mjs +0 -1572
- package/test/cli-guard.test.mjs +0 -198
- package/test/conclusion.test.mjs +0 -408
- package/test/config-schema.test.mjs +0 -204
- package/test/d6-output.test.mjs +0 -194
- package/test/d6.test.mjs +0 -395
- package/test/deps.test.mjs +0 -342
- package/test/doctor-setup.test.mjs +0 -297
- package/test/embedding-recall.test.mjs +0 -347
- package/test/feature-flags.test.mjs +0 -568
- package/test/filter-shadow.test.mjs +0 -170
- package/test/fixtures/baseline-0.8.0-registration.json +0 -556
- package/test/fixtures/d6-header-tools.json +0 -1
- package/test/fixtures/lock-child.mjs +0 -67
- package/test/fixtures/pre-step-container.mjs +0 -100
- package/test/fixtures/privacy-memory/topics/pii-unmarked.md +0 -9
- package/test/fixtures/privacy-memory/topics/secret-local-only.md +0 -11
- package/test/fixtures/profile-session-longlive-config.json +0 -20
- package/test/fixtures/proposal-cas-child.mjs +0 -66
- package/test/host-engine-status.test.mjs +0 -307
- package/test/hot-truncate.test.mjs +0 -1349
- package/test/identity-card-marker.test.mjs +0 -307
- package/test/identity-router/run.mjs +0 -721
- package/test/integration-pre-step.test.mjs +0 -553
- package/test/live.test.mjs +0 -1020
- package/test/maintenance-schedule.test.mjs +0 -538
- package/test/memory.test.mjs +0 -2828
- package/test/metrics.test.mjs +0 -478
- package/test/orchestrator.test.mjs +0 -266
- package/test/p1_probe.mjs +0 -97
- package/test/packaging.test.mjs +0 -182
- package/test/portability.test.mjs +0 -343
- package/test/rc4-regressions.test.mjs +0 -562
- package/test/rc5-regressions.test.mjs +0 -197
- package/test/rc6-chinese.test.mjs +0 -394
- package/test/router-1100/apply-off.test.mjs +0 -175
- package/test/router-1100/budget-reconcile.test.mjs +0 -215
- package/test/router-1100/config-context.test.mjs +0 -211
- package/test/router-1100/helpers.mjs +0 -129
- package/test/router-1100/hint-envelope.test.mjs +0 -150
- package/test/router-1100/lock-crossproc.test.mjs +0 -206
- package/test/router-1100/proposal-cas-crossproc.test.mjs +0 -184
- package/test/router-1100/router-apply.test.mjs +0 -372
- package/test/router-1100/router-fixb.test.mjs +0 -602
- package/test/router-1100/router-proposals.test.mjs +0 -405
- package/test/router-1100/router-queue-lease-wal.test.mjs +0 -355
- package/test/router-1100/router-security-cr.test.mjs +0 -333
- package/test/router-1100/service-lifecycle.test.mjs +0 -220
- package/test/router-1100/tools-contract.test.mjs +0 -164
- package/test/router-1100/turn-reflect-tick.test.mjs +0 -89
- package/test/router-1100/v6-contract.test.mjs +0 -158
- package/test/router-1100/v6b-contract.test.mjs +0 -293
- package/test/router-1100/v6c-contract.test.mjs +0 -249
- package/test/router-1100/wal-rotation.test.mjs +0 -375
- package/test/router-1100/wp1-config.test.mjs +0 -170
- package/test/router-1100/wp1-default-off.test.mjs +0 -77
- package/test/router-1100/wp1-model-status.test.mjs +0 -90
- package/test/router-1100/wp1-status.test.mjs +0 -220
- package/test/router-1100/wp1-tools.test.mjs +0 -146
- package/test/router-1100/wp5-cli.test.mjs +0 -240
- package/test/router-1100/wp5-model-auto.test.mjs +0 -418
- package/test/router-1100/wp6-merge.test.mjs +0 -386
- package/test/router-1100/wp6-wake.test.mjs +0 -502
- package/test/router-background/audit.test.mjs +0 -37
- package/test/router-background/budget-ledger.test.mjs +0 -330
- package/test/router-background/cross-process.test.mjs +0 -222
- package/test/router-background/fixtures/cross-child.mjs +0 -85
- package/test/router-background/fixtures/real-shapes.mjs +0 -239
- package/test/router-background/router.test.mjs +0 -1044
- package/test/router-background/stream-retry.test.mjs +0 -358
- package/test/router-background/tool-agent.test.mjs +0 -384
- package/test/router-face/bridge.test.mjs +0 -169
- package/test/router-face/face.test.mjs +0 -316
- package/test/router-failclosed.test.mjs +0 -466
- package/test/router-identity.test.mjs +0 -384
- package/test/router-l1-l2.contract.test.mjs +0 -1075
- package/test/router-memory-tools.test.mjs +0 -262
- package/test/router-policy.test.mjs +0 -225
- package/test/router-runtime.test.mjs +0 -438
- package/test/router-shadow.test.mjs +0 -287
- package/test/router.test.mjs +0 -903
- package/test/run-rc.mjs +0 -299
- package/test/run.mjs +0 -2469
- package/test/safety-defaults.test.mjs +0 -179
- package/test/seeded-load.test.mjs +0 -436
- package/test/session-original.test.mjs +0 -338
- package/test/surgery-recovery.test.mjs +0 -936
- package/test/t7_drive.mjs +0 -151
- package/test/tool-output.test.mjs +0 -393
- package/test/tool-schema.test.mjs +0 -177
- package/test/tools_contract.test.mjs +0 -716
- package/test/truncate-visible.test.mjs +0 -1150
- package/test/ui-flags.test.mjs +0 -477
- package/test/v4-hardening.test.mjs +0 -427
package/docs/PRESENCE-BUS.md
DELETED
|
@@ -1,694 +0,0 @@
|
|
|
1
|
-
# 跨会话通道 · session-bus v0 设计
|
|
2
|
-
|
|
3
|
-
> 状态:设计 + 可运行原型,**尚未接入宿主、尚未安装插件**。
|
|
4
|
-
> 范围:同一台 Windows 机器、同一个 DSH profile、同一个 Windows 用户。
|
|
5
|
-
> 日期:2026-11-04。原型:`prototype/bus.mjs`;测试:`test/bus.test.mjs`(15/15 通过)。
|
|
6
|
-
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
## 0. 一句话
|
|
10
|
-
|
|
11
|
-
给每个会话一个**文件邮箱**:发消息是原子写一个 JSON 文件,收消息是 `poll` 扫描自己的收件箱,处理完 `ack` 把它移进 `acked/`。存活判断只读 longlive 已有的 live 登记表;身份文件仍然只有 identity-router 一个读者、人类一个写者。它不是 RPC,不假装能叫醒一个空闲会话——它是**信箱**,下一次开门时取信。
|
|
12
|
-
|
|
13
|
-
---
|
|
14
|
-
|
|
15
|
-
## 1. 目标与非目标
|
|
16
|
-
|
|
17
|
-
### 目标
|
|
18
|
-
|
|
19
|
-
1. 同一台机器上的前台会话、后台会话、另一个窗口里的会话可以互发短消息。
|
|
20
|
-
2. 三个寻址维度:`sessionId`(精确)、`@别名`(1:1)、`#角色`(1:N)。
|
|
21
|
-
3. 至少一次投递;发送端可用 `dedupKey` 做幂等;接收端用 `ack` 确认。
|
|
22
|
-
4. 不依赖数据库、不依赖网络、不新增 npm 依赖;只用 Node 标准库。
|
|
23
|
-
5. 与 identity-router 的 `STATE.md` / `handover/*.md` 共用同一份身份,但**不篡改**身份文件。
|
|
24
|
-
6. 失败可见、可恢复:对方死了、消息堆了、重复消费了,都有明确行为,不静默丢。
|
|
25
|
-
|
|
26
|
-
### 非目标(v0 明确不做)
|
|
27
|
-
|
|
28
|
-
- **不跨机器**。不做网络传输、不做中继、不做同步盘。
|
|
29
|
-
- **v0 不做自动唤醒**:宿主已有唤醒 API,但 v0 选择邮箱轮询的取舍(见 §8)。
|
|
30
|
-
- **不做加密**。同一 Windows 用户信任边界内,文件 ACL 就是权限。
|
|
31
|
-
- **不做富媒体**。`body` 是 UTF-8 文本(可以是 JSON 字符串),不放二进制。
|
|
32
|
-
- **不做 exactly-once**。文件系统 + 崩溃恢复只能给 at-least-once。
|
|
33
|
-
- **不自动改 `handover/*.md`**。只写 outbox 草稿,合并由人/后续流程做。
|
|
34
|
-
- **不替代 engram / longlive**。总线只传“消息”,不传记忆库。
|
|
35
|
-
|
|
36
|
-
---
|
|
37
|
-
|
|
38
|
-
## 2. 事实基础(设计所依赖的已验证行为)
|
|
39
|
-
|
|
40
|
-
### 2.1 live 登记表
|
|
41
|
-
|
|
42
|
-
`@jjh32456/dsh-longlive` 在 `<memoryRoot>/.longlive/live/<sessionId>.json` 每个会话一行,字段:
|
|
43
|
-
|
|
44
|
-
```
|
|
45
|
-
schemaVersion, sessionId, pid, host, startedAt, updatedAt, heartbeatAt,
|
|
46
|
-
ttlMs, state, turn, goal, blocked_on, queued, last_action
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
- `ttlMs` 默认 `60000`,允许 `1000..86400000`。
|
|
50
|
-
- 声明状态:`idle | running | waiting | blocked | stale`;读取方计算 `dead | corrupt`。
|
|
51
|
-
- 有效状态规则(`liveEntry`):
|
|
52
|
-
- `age <= ttlMs` → fresh(pid 不推翻 fresh);
|
|
53
|
-
- `age > 4*ttlMs` → dead;
|
|
54
|
-
- 否则同 host 且 `pidAlive(pid) === false` → dead;
|
|
55
|
-
- 否则 `age > 2*ttlMs` → stale;
|
|
56
|
-
- 否则沿用声明状态。
|
|
57
|
-
- 写是 tmp + 读回 + rename(EPERM/EACCES/EBUSY 重试),完整外来 JSON 按 last-writer-wins 接受。
|
|
58
|
-
- `sessionId` 正则 `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$`,写盘前 lower-case;拒绝 NUL、绝对路径、`/`、`\`、`.`、`..`。
|
|
59
|
-
- 行路径有 realpath jail;符号链接行拒绝读取;路径被目录/链接占用时报 `E_LIVE_ROW_BLOCKED`。
|
|
60
|
-
- 本机实测 live 目录:`<memory-root>\.longlive\live\`(不是 `%USERPROFILE%\.dsh\longlive-memory`)。**所有插件必须共享同一个 `memoryRoot` 解析结果**,否则总线看到的存活状态全是 `missing`。
|
|
61
|
-
|
|
62
|
-
### 2.2 宿主钩子
|
|
63
|
-
|
|
64
|
-
- `session/event(turn/end)`:回合结束时触发;identity-router 用它写草稿。
|
|
65
|
-
- `session/disposed`:会话被优雅销毁时触发;进程被强杀不会触发。
|
|
66
|
-
- **没有 `session/end`**。不能假设“会话结束一定有一次回调”。
|
|
67
|
-
- `agent/pre-step` 是 waterfall,`step === 1` 时可追加一条用户消息(identity-router 已用此注入开机卡)。这是目前唯一验证过、能按会话注入内容的入口。
|
|
68
|
-
- 全局插件拿不到按会话区分的 system prompt(`system-prompt/assemble` 没有 agent/session 维度)。
|
|
69
|
-
- `agent/created` 不能改消息,只能记录来源。
|
|
70
|
-
|
|
71
|
-
### 2.3 identity-router v0 边界
|
|
72
|
-
|
|
73
|
-
- 读:`<memoryRoot>/STATE.md`、`<memoryRoot>/handover/*.md`。
|
|
74
|
-
- 写:**只写 outbox**;outbox 默认是 `<repo>/outbox/`,不是 memoryRoot(`writeback.js` 顶部注释与 `resolveOutboxDir` 都明确这一点)。
|
|
75
|
-
- 开机卡 ≤ 800 code points,四节 `▍我在哪 / ▍在等什么 / ▍最近三件 / ▍交接卡`,`buildOpenCard(input)` 是纯函数。
|
|
76
|
-
- `collectOpenCard(options)` 负责读盘并调用 `buildOpenCard`。
|
|
77
|
-
- 草稿文件名带短会话 id,永不覆盖(`-2`、`-3`……最多 50)。
|
|
78
|
-
|
|
79
|
-
> **边界结论**:identity-router v0 的“绝不写 memoryRoot”是硬约定。总线如果落在 `<memoryRoot>/.longlive/bus`,就是让插件往 memoryRoot 写东西——这是**新的写权限**,必须由 owner 明确批准,不能顺手加进 v0。见 §13 的两个落盘方案。
|
|
80
|
-
|
|
81
|
-
---
|
|
82
|
-
|
|
83
|
-
## 3. 总体结构
|
|
84
|
-
|
|
85
|
-
```
|
|
86
|
-
┌──────────────────────┐ ┌──────────────────────┐
|
|
87
|
-
│ session A │ │ session B │
|
|
88
|
-
│ identity-router │ │ identity-router │
|
|
89
|
-
│ ├─ pre-step: poll │ │ ├─ pre-step: poll │
|
|
90
|
-
│ ├─ turn/end: ack │ │ ├─ turn/end: ack │
|
|
91
|
-
│ └─ disposed: release│ │ └─ disposed: release│
|
|
92
|
-
└─────────┬────────────┘ └─────────┬────────────┘
|
|
93
|
-
│ send / poll / ack │
|
|
94
|
-
▼ ▼
|
|
95
|
-
┌─────────────────────────────────────────────┐
|
|
96
|
-
│ bus root │
|
|
97
|
-
│ inbox/<to>/<id>.json pending │
|
|
98
|
-
│ inbox/<to>/acked/<id>.json │
|
|
99
|
-
│ inbox/<to>/dead/<id>.<reason>.json │
|
|
100
|
-
│ aliases.json roles.json writer.lock │
|
|
101
|
-
└─────────────────────────────────────────────┘
|
|
102
|
-
│ 只读
|
|
103
|
-
▼
|
|
104
|
-
<memoryRoot>/.longlive/live/<sessionId>.json
|
|
105
|
-
(存活判断;bus 从不写 live 行)
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
三个原则:
|
|
109
|
-
|
|
110
|
-
1. **消息是文件,不是连接**。发送方写完即返回,不要求接收方在线。
|
|
111
|
-
2. **存活是提示,不是保证**。live 行只用于拒发/跳过死会话;真正送达以文件存在为准。
|
|
112
|
-
3. **身份是共享只读,写者唯一**。总线不碰 `STATE.md` / `handover/*.md`;只读它们做卡片。
|
|
113
|
-
|
|
114
|
-
---
|
|
115
|
-
|
|
116
|
-
## 4. 寻址
|
|
117
|
-
|
|
118
|
-
### 4.1 三种地址
|
|
119
|
-
|
|
120
|
-
| 形式 | 例子 | 语义 | 解析来源 |
|
|
121
|
-
|---|---|---|---|
|
|
122
|
-
| `sessionId` | `session-e219dedf-a08a-...` | 精确一个会话 | 调用方传入;规范化为小写 |
|
|
123
|
-
| `@alias` | `@reviewer` | 1:1 别名 | `<busRoot>/aliases.json` |
|
|
124
|
-
| `#role` | `#team` | 1:N 角色,去重后逐个投递 | `<busRoot>/roles.json` |
|
|
125
|
-
|
|
126
|
-
`send({to})` 先解析目标,再校验存活,再落盘。别名和角色文件**每次发送时读取**,不缓存,改完立即生效。
|
|
127
|
-
|
|
128
|
-
### 4.2 规范化规则
|
|
129
|
-
|
|
130
|
-
接收 `sessionId` 时:
|
|
131
|
-
|
|
132
|
-
1. `trim()`;空串拒绝。
|
|
133
|
-
2. 含 NUL、绝对路径、`/`、`\`、`.`、`..` → `E_PATH_OUTSIDE_ROOT`。
|
|
134
|
-
3. 不匹配 `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$` → `E_BAD_SESSION_ID`。
|
|
135
|
-
4. `toLowerCase()`;Windows 大小写不敏感,规范 id 一律小写。
|
|
136
|
-
5. 以 `.` 或空格结尾 → 拒绝(Windows 会静默去掉)。
|
|
137
|
-
6. 第一段是 `con/prn/aux/nul/com1..9/lpt1..9` → 拒绝(设备名)。
|
|
138
|
-
7. 返回值即落盘目录名;**绝不允许调用方传入未规范化的字符串拼路径**。
|
|
139
|
-
|
|
140
|
-
别名 `@name`:`^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$`,查找时大小写不敏感。别名不落盘成目录,只作为键,所以不需要 Windows 设备名规则,但仍限制字符集。
|
|
141
|
-
|
|
142
|
-
### 4.3 别名文件
|
|
143
|
-
|
|
144
|
-
```json
|
|
145
|
-
{
|
|
146
|
-
"reviewer": "session-bob",
|
|
147
|
-
"foreground": "session-e219dedf-a08a-4eed-9cd2-ef49cec29258"
|
|
148
|
-
}
|
|
149
|
-
```
|
|
150
|
-
|
|
151
|
-
- 值必须是单个合法 `sessionId` 字符串;也可以是 `{ "sessionId": "..." }`(原型兼容两种)。
|
|
152
|
-
- 重复键(大小写不同)按“找到的第一个”处理,不静默合并;建议写文件的人保证唯一。
|
|
153
|
-
- 别名指向的会话死了:`@alias` 是 1:1,按“直投”处理,默认抛 `E_PEER_DEAD`(不静默丢)。
|
|
154
|
-
- 别名修改只影响之后的发送;已经落盘的消息里 `to` 仍是旧 id,不会重写。
|
|
155
|
-
|
|
156
|
-
### 4.4 角色文件
|
|
157
|
-
|
|
158
|
-
```json
|
|
159
|
-
{
|
|
160
|
-
"team": ["session-bob", "session-carol", "session-bob"]
|
|
161
|
-
}
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
- 数组,成员是合法 `sessionId`;重复成员去重。
|
|
165
|
-
- 角色是“尽力而为”的 fan-out:
|
|
166
|
-
- 死会话 → `skipped: [{to, reason:"dead"}]`;
|
|
167
|
-
- 远程 host → `skipped: [{to, reason:"remote-host"}]`;
|
|
168
|
-
- 某个成员 inbox 满 → `skipped: [{to, reason:"backlog"}]`;
|
|
169
|
-
- 至少一个成功 → `{ok:true, partial:true, results, skipped}`;
|
|
170
|
-
- 全部失败 → `E_NO_LIVE_RECIPIENTS`。
|
|
171
|
-
- v0 **不做 `*` 通配广播**。要广播就显式建 `#all`,避免手滑。
|
|
172
|
-
- 角色成员上限原型未强制;建议配置层限制 64(开放问题)。
|
|
173
|
-
|
|
174
|
-
### 4.5 “前台/后台/别的窗口”怎么表示
|
|
175
|
-
|
|
176
|
-
总线不知道窗口焦点,也不应该猜。做法是人工/配置维护:
|
|
177
|
-
|
|
178
|
-
```json
|
|
179
|
-
{ "foreground": "session-...", "background": "session-..." }
|
|
180
|
-
```
|
|
181
|
-
|
|
182
|
-
或由未来 UI 在会话启动时原子更新 `aliases.json`。**不要**根据 live 的 `state === 'running'` 推断“前台”——`running` 只表示在跑,不表示可见。
|
|
183
|
-
|
|
184
|
-
---
|
|
185
|
-
|
|
186
|
-
## 5. 消息格式
|
|
187
|
-
|
|
188
|
-
### 5.1 信封
|
|
189
|
-
|
|
190
|
-
```json
|
|
191
|
-
{
|
|
192
|
-
"v": 1,
|
|
193
|
-
"id": "m-0abc12345-0001-00a1b2-9f3c1d",
|
|
194
|
-
"from": "session-alice",
|
|
195
|
-
"to": "session-bob",
|
|
196
|
-
"kind": "note",
|
|
197
|
-
"body": "音频导出来了,在 D:\\work\\out\\mix.wav",
|
|
198
|
-
"ts": 1762300000000,
|
|
199
|
-
"ttl": 86400000,
|
|
200
|
-
"host": "jjh",
|
|
201
|
-
"dedupKey": "mix-export-2026-11-04"
|
|
202
|
-
}
|
|
203
|
-
```
|
|
204
|
-
|
|
205
|
-
| 字段 | 必填 | 类型/范围 | 说明 |
|
|
206
|
-
|---|---|---|---|
|
|
207
|
-
| `v` | 是 | `1` | schema 版本;不兼容变更升 2 |
|
|
208
|
-
| `id` | 是 | 匹配 `^m-[a-z0-9]+(?:-[a-z0-9]+)*$` | 全局唯一;见 §5.2 |
|
|
209
|
-
| `from` | 是 | 合法 `sessionId` | 发送方;必须等于 bus 绑定的 sessionId |
|
|
210
|
-
| `to` | 是 | 合法 `sessionId` | 接收方;解析后的规范 id |
|
|
211
|
-
| `kind` | 是 | `note\|task\|reply\|handover\|control` | 语义见 §5.3 |
|
|
212
|
-
| `body` | 是 | 非空 UTF-8,≤ 8192 code points | 纯文本;可以是 JSON 字符串 |
|
|
213
|
-
| `ts` | 是 | epoch ms,> 0 | 发送方时钟;用于排序/过期 |
|
|
214
|
-
| `ttl` | 是 | `0 < ttl <= 604800000`(7 天) | 默认 24h;接收方判断 |
|
|
215
|
-
| `host` | 是 | 非空字符串 | 发送方 hostname;接收方必须匹配本机 |
|
|
216
|
-
| `dedupKey` | 否 | 非空,≤ 128 code points | 幂等键;同键同 body/kind 去重 |
|
|
217
|
-
|
|
218
|
-
**不放进信封的**:优先级、replyTo、附件、加密标记。v0 需要回复就用 `kind:"reply"` + body 里写原 id;需要结构化内容就把 JSON 放进 `body`。加字段必须升 `v`,不能悄悄塞。
|
|
219
|
-
|
|
220
|
-
### 5.2 消息 id
|
|
221
|
-
|
|
222
|
-
两种生成方式:
|
|
223
|
-
|
|
224
|
-
1. **普通发送**:
|
|
225
|
-
```
|
|
226
|
-
m-<9 位 base36 毫秒时间戳>-<4 位 base36 进程内序号>-<6 位 base36 pid>-<6 位 hex 随机>
|
|
227
|
-
```
|
|
228
|
-
长度可控,前 9 位可反解时间(用于 `since` 回退),进程内序号降低同毫秒碰撞。
|
|
229
|
-
2. **带 `dedupKey`**:
|
|
230
|
-
```
|
|
231
|
-
m-<sha256(from + "\0" + to + "\0" + dedupKey)[0..32]>
|
|
232
|
-
```
|
|
233
|
-
同一发送方、同一接收方、同一键 → 同一 id → 文件已存在 → 返回 `deduped:true`。
|
|
234
|
-
若已有文件但 body/kind 不同 → `E_DEDUP_CONFLICT`(不静默覆盖,避免“重试时内容变了”却以为成功)。
|
|
235
|
-
|
|
236
|
-
`id` 只用于文件名和 ack,不承载权限。`ack` 前用正则校验,绝不把它拼进 `..`。
|
|
237
|
-
|
|
238
|
-
### 5.3 kind 语义
|
|
239
|
-
|
|
240
|
-
| kind | 用途 | 是否进开机卡 | 是否可能进 handover |
|
|
241
|
-
|---|---|---|---|
|
|
242
|
-
| `note` | 通知、状态、FYI | 是(一行摘要) | 否 |
|
|
243
|
-
| `task` | 请对方做一件事 | 是(一行摘要) | 否 |
|
|
244
|
-
| `reply` | 对某条消息的回答 | 是 | 否 |
|
|
245
|
-
| `handover` | 交接信息,可能较长 | 是(一行摘要) | 是,单独落 outbox |
|
|
246
|
-
| `control` | 机器控制(预留:ack/nack/lease) | **否** | 否 |
|
|
247
|
-
|
|
248
|
-
`control` 默认不展示,防止内部协议文本污染卡片;v0 原型没有真正使用它,只保留枚举。
|
|
249
|
-
|
|
250
|
-
---
|
|
251
|
-
|
|
252
|
-
## 6. 投递语义
|
|
253
|
-
|
|
254
|
-
### 6.1 至少一次(at-least-once)
|
|
255
|
-
|
|
256
|
-
- `poll()` **不删除**消息,只读并排序返回。
|
|
257
|
-
- `ack(id)` 把 `<id>.json` 从 `inbox/<sessionId>/` 移到 `inbox/<sessionId>/acked/<id>.json`。
|
|
258
|
-
- 消费者在“处理完”之后才 ack;崩溃在 poll 与 ack 之间 → 下次重新投递。
|
|
259
|
-
- 没有 exactly-once,也没有事务。消费者必须按 `id` 幂等(例如卡片里同一条消息出现两次,不能重复执行副作用)。
|
|
260
|
-
|
|
261
|
-
### 6.2 去重键(发送端幂等)
|
|
262
|
-
|
|
263
|
-
- 同一 `(from,to,dedupKey)` → 同一 `id` → 同一文件。
|
|
264
|
-
- 第二次 send 读到已存在文件:
|
|
265
|
-
- body 与 kind 相同 → `{deduped:true}`,不新增;
|
|
266
|
-
- 不同 → `E_DEDUP_CONFLICT`。
|
|
267
|
-
- 没带 `dedupKey` 的 send 每次生成新 id;网络/进程重试会产生重复,接收端只能靠 id 不同而无法自动合并。**要重试就必须带 dedupKey**。
|
|
268
|
-
|
|
269
|
-
### 6.3 过期丢弃
|
|
270
|
-
|
|
271
|
-
- 接收方判断:`now > ts + ttl` → 不返回,删除文件,`expired++`。
|
|
272
|
-
- 过期是**逻辑时间**,不是文件 mtime;发送方时钟偏快会让消息活更久,偏慢会提前死。同机时钟通常一致;跨时区不影响 epoch ms。
|
|
273
|
-
- 没被 poll 的过期文件会留在磁盘,直到下一次 poll 或未来的 janitor;不占投递配额以外的语义。
|
|
274
|
-
- `ttl` 上限 7 天,防止“僵尸消息”无限期占坑。
|
|
275
|
-
|
|
276
|
-
### 6.4 排序与游标
|
|
277
|
-
|
|
278
|
-
- `poll` 按 `(ts, id)` 升序返回;这不是跨发送方的因果序。同一毫秒内两条消息的顺序由 id 字典序决定,**不保证等于发送顺序**。
|
|
279
|
-
- `since` 支持:
|
|
280
|
-
- 数字:epoch ms,返回 `ts > since`;
|
|
281
|
-
- ISO 时间字符串:同上;
|
|
282
|
-
- 消息 id:先查 pending/acked 文件拿 `ts`,再按 `(ts,id)` 严格大于;找不到文件时用 id 前 9 位时间戳回退。
|
|
283
|
-
- 数字/ISO 游标会**排除同一毫秒**的消息;要精确续读,用最后一条消息的 id。
|
|
284
|
-
- `cursor` 正常返回本次最后一条的 id;没有新消息时原样返回传入的 `since`。
|
|
285
|
-
- **超前消息不参与游标**:若本次投递的消息里有 `ts > now`(仍在 `maxClockSkewMs` 容忍窗内),返回的 `cursor` 改为数字 `now`(epoch ms),而不是该消息的 id。id 游标按 `(ts,id)` 比较,会把之后 `ts` 更小的正常消息永久压在下面;夹到 `now` 后下一轮会重放那条超前消息(at-least-once,ack 幂等),但不再挡任何正常消息。见 §7.4 与 WIRING §3.5。
|
|
286
|
-
|
|
287
|
-
### 6.5 积压上限
|
|
288
|
-
|
|
289
|
-
- 每个收件箱默认最多 1000 条 pending `.json`;`acked/` 和 `dead/` 不计。
|
|
290
|
-
- 达到上限:直投 `E_BACKLOG_FULL`;角色投递跳过该成员并记 `reason:"backlog"`。
|
|
291
|
-
- 上限检查是“读数量 + 写文件”的近似;并发发送可能短暂超过 1 条。严格上限需要额外锁,v0 不做,文档明确。
|
|
292
|
-
- 没有自动丢弃;消费者必须 drain + ack,或等 TTL。
|
|
293
|
-
|
|
294
|
-
### 6.6 ack 语义
|
|
295
|
-
|
|
296
|
-
- 只有收件箱主人能 ack:`ack` 用 bus 绑定的 `sessionId`,不接受调用方传别的 id。
|
|
297
|
-
- 重复 ack:目标已在 `acked/` → `{ok:true, already:true}`。
|
|
298
|
-
- 不存在:`{ok:false, code:"E_NOT_FOUND"}`(不是异常,方便重试逻辑)。
|
|
299
|
-
- ack 之后消息仍在 `acked/`,用于重复 ack 判定与审计;生产环境建议 7 天后 GC(原型未实现)。
|
|
300
|
-
- ack 是“我收到了”,不是“我处理成功了”。需要处理确认就再发一条 `kind:"reply"`。
|
|
301
|
-
|
|
302
|
-
---
|
|
303
|
-
|
|
304
|
-
## 7. 落盘位置与原子性
|
|
305
|
-
|
|
306
|
-
### 7.1 目录布局
|
|
307
|
-
|
|
308
|
-
```
|
|
309
|
-
<busRoot>/
|
|
310
|
-
aliases.json # 可选;1:1 别名
|
|
311
|
-
roles.json # 可选;1:N 角色
|
|
312
|
-
writer.lock # 单写者租约(身份/handover 合并用)
|
|
313
|
-
inbox/
|
|
314
|
-
<sessionId>/
|
|
315
|
-
<messageId>.json # pending,创建后不可变
|
|
316
|
-
acked/<messageId>.json # 已确认
|
|
317
|
-
dead/<messageId>.<reason>.json# corrupt / foreign,隔离
|
|
318
|
-
```
|
|
319
|
-
|
|
320
|
-
### 7.2 两个候选 busRoot
|
|
321
|
-
|
|
322
|
-
| 方案 | 路径 | 优点 | 代价 |
|
|
323
|
-
|---|---|---|---|
|
|
324
|
-
| A. v0 接线默认(推荐先走) | `<work-dir>\identity-router\outbox\bus` 或 `DSH_SESSION_BUS_ROOT` 指定的仓库外目录 | 不违反 identity-router “绝不写 memoryRoot”;零新权限;便于只读试验 | 不在 memoryRoot 备份范围内;换仓库/换机器要显式搬 |
|
|
325
|
-
| B. 生产归属 | `<memoryRoot>/.longlive/bus` | 与 live 登记表同根;随记忆目录备份;`.longlive` 本来就是插件状态目录 | 插件开始写 memoryRoot,**需要 owner 明确批准**;identity-router v0 不能自己这么干 |
|
|
326
|
-
|
|
327
|
-
原型对两者都支持:`createBus({root, memoryRoot})` 只要求 `root` 可写,`memoryRoot` 只用于定位 live 登记表。**WIRING 采用 A**,把 B 列为需要单独批准的升级项。不要因为“都在 .longlive 下”就默认 B 合规——v0 的约定是身份插件不写记忆根。
|
|
328
|
-
|
|
329
|
-
### 7.3 原子写
|
|
330
|
-
|
|
331
|
-
发送一条消息:
|
|
332
|
-
|
|
333
|
-
1. 校验并规范化 `to`;`ensureDirInside(root, inbox/<to>)`。
|
|
334
|
-
2. 若目标文件已存在:读它,按 dedup 规则返回或报冲突。
|
|
335
|
-
3. 生成信封;在**同一目录**写临时文件 `.tmp-<pid>-<12 hex>`(6 字节随机数的 hex,`open(..., 'wx')`)。
|
|
336
|
-
4. `writeFileSync(fd, text)` → 尽力 `fsync(fd)` → `close`。
|
|
337
|
-
5. `renameSync(tmp, target)`;Windows 上 EPERM/EACCES/EBUSY 重试 5 次、每次 5ms(Atomics.wait 同步睡眠)。
|
|
338
|
-
6. 失败清理临时文件;若 rename 时目标已被别人创建,读回目标:内容一致按 dedup 处理,否则 `E_DEDUP_CONFLICT`。
|
|
339
|
-
|
|
340
|
-
因此读方永远看不到半截 JSON:要么没有文件,要么是完整信封。
|
|
341
|
-
|
|
342
|
-
### 7.4 读与隔离
|
|
343
|
-
|
|
344
|
-
- `poll` 只读 `inbox/<sessionId>/*.json`,不递归。
|
|
345
|
-
- 每个文件 `lstat`:必须是普通文件;符号链接跳过(不读、不删)。
|
|
346
|
-
- JSON 解析失败、字段不合法、`to` 不匹配、`host` 不匹配 → 分别计入 `corrupt` / `foreignHost`,移到 `dead/`,继续处理其余消息;一条坏消息不能拖垮整个收件箱。
|
|
347
|
-
- `aliases.json` / `roles.json` 解析失败 → 发送时 `E_BAD_ADDRESS_BOOK`,fail closed(不猜)。
|
|
348
|
-
- 所有路径都以 `realpath(root)` 为基准;`ensureDirInside` 拒绝符号链接目录和 realpath 逃逸。真实路径检查从**最近存在的祖先**开始(路径不存在时逐级向上),所以 `root\escape\missing\deep.json`(`escape` 是指向根外的 junction)也会被拒绝,而不是先建目录再逃逸。任何路径段含 `:`(Windows ADS)或目标本身是符号链接/junction → `E_PATH_OUTSIDE_ROOT`。
|
|
349
|
-
- `poll` 对 `ts > now + maxClockSkewMs`(默认 300000)的消息计入 `futureTs`,移入 `dead/<id>.future-ts.json`,不返回、不当作游标;调用方传入超未来的 `since` 时按“重放全部 pending”处理(结果带 `futureCursor:true`),不夹到 `now`——向前夹会静默丢掉已排队的消息。
|
|
350
|
-
- 容忍窗内(`ts <= now + 300000`)的超前消息会被正常投递,但**不能当游标**:若直接返回它的 id,之后 `ts` 更小的正常消息会被 `(ts,id)` 游标永久过滤且 `futureCursor` 仍为 false,等于静默丢消息(红队 P24)。因此 poll 只要投递了 `ts > now` 的消息,`cursor` 就夹到 `now`:下一轮重放该超前消息(at-least-once),正常消息照常可见。窗口语义(5 分钟)写在 WIRING §3.5。
|
|
351
|
-
|
|
352
|
-
### 7.5 为什么不直接用 SQLite
|
|
353
|
-
|
|
354
|
-
- 单文件、零依赖、可被人眼检查和手工修复;一个会话一个目录,排障简单。
|
|
355
|
-
- 消息量小(每会话每天几十到几百条),文件系统足够。
|
|
356
|
-
- 原子 rename 在 NTFS 本地盘可靠;SQLite 反而引入 WAL/锁/版本兼容问题。
|
|
357
|
-
- 代价:没有事务性多收件箱写入、没有索引、积压扫描 O(n)。v0 接受,n 由 1000 上限约束。
|
|
358
|
-
|
|
359
|
-
---
|
|
360
|
-
|
|
361
|
-
## 8. 唤醒方式:轮询 vs 事件
|
|
362
|
-
|
|
363
|
-
### 8.1 结论先说
|
|
364
|
-
|
|
365
|
-
**v0 的投递路径只有轮询;但“不能唤醒”不是物理限制。** 宿主有唤醒 API:`ctx.agents.get(id)?.followup(msg)` 能让一个 **live、空闲** 的会话开始新一轮(`asar/agent.js:597`、`asar/agent-loop.js:806-807`、`README.md:47`);**cold** 会话(进程已退出/未启动)由 api-session-controller 的 resume 路径恢复(`api-session-controller:228,794,950`),恢复后照常从 inbox 读取。v0 选择邮箱轮询是取舍:不依赖未稳定导出的内部 API、不必处理会话忙/重启窗口,代价是延迟上界 = 对方下一次 `agent/pre-step`。两条路的接线见 WIRING §5.4。
|
|
366
|
-
|
|
367
|
-
### 8.2 具体挂点
|
|
368
|
-
|
|
369
|
-
| 时机 | 做什么 | 为什么 |
|
|
370
|
-
|---|---|---|
|
|
371
|
-
| `agent/pre-step`,`step === 1` | `poll` 未读;把摘要并进开机卡;记录待 ack id | 与 identity-router 现有注入点重合,已验证 |
|
|
372
|
-
| `session/event` `turn/end` 且 `data.reason.kind === 'completed'` | ack 本轮卡片里展示过的消息;可选合并 handover | 宿主的 `turn/end` 也在 `finally` 里发,error/aborted 回合不能 ack(否则消息永久消失) |
|
|
373
|
-
| `session/disposed` | 释放 writer 租约;不强制 ack | 优雅退出;强杀时不会触发 |
|
|
374
|
-
| 任意后续 step(可选) | 若配置 `pollEveryStep`,按节流(≥1s)poll 新消息 | 长回合内也能收信;v0 默认关闭,避免每步 IO |
|
|
375
|
-
|
|
376
|
-
### 8.3 事件驱动能做到什么、不能做到什么
|
|
377
|
-
|
|
378
|
-
- **进程内**:`fs.watch(inbox, ...)` 可以在一个已经在等待的进程里降低延迟;但 watch 会漏事件、会重命名抖动、跨进程不保证。它只能当“提示”,收到提示后仍要 `poll` 对账。原型不实现。
|
|
379
|
-
- **跨进程/跨窗口**:宿主有两条已验证的路——live 空闲会话用 `ctx.agents.get(id)?.followup(msg)`,cold 会话用 api-session-controller resume(见 §8.1 的源码位置)。v0 不接它们,只投邮箱;不要用 `session_live_update` 假装唤醒——那只是写登记表,不会调度。
|
|
380
|
-
- **live / cold 在 v0 的行为**:live 会话等下一次 `agent/pre-step` 自己取;cold 会话等下一次启动/resume 后读 inbox。两者都不需要总线侧定时器。
|
|
381
|
-
- **UI 提示**:未来可以做未读角标,但那是客户端插件的事,不是投递语义。
|
|
382
|
-
- **后台会话**:即使它是 `running`,消息也要等它下一次 `pre-step`;如果它卡在长工具调用里,延迟就是那个工具的时长。
|
|
383
|
-
|
|
384
|
-
### 8.4 延迟与成本
|
|
385
|
-
|
|
386
|
-
- 每次 `poll` 扫一个目录,最多 1000 个 pending;空收件箱是一次 `existsSync`,成本可忽略。
|
|
387
|
-
- 只在 `step === 1` poll,长会话不会每步扫盘。
|
|
388
|
-
- 不建议 100ms 级定时轮询:v0 不调用宿主唤醒 API,轮询再密也不会让空闲会话开始一轮,只是耗电。
|
|
389
|
-
|
|
390
|
-
---
|
|
391
|
-
|
|
392
|
-
## 9. 安全
|
|
393
|
-
|
|
394
|
-
### 9.1 信任边界
|
|
395
|
-
|
|
396
|
-
v0 的边界是:**同一台机器 + 同一个 Windows 用户 + 同一个 DSH profile**。
|
|
397
|
-
|
|
398
|
-
- 没有认证、没有 HMAC、没有每会话 token。同一用户下的任何进程都能读写 busRoot。
|
|
399
|
-
- `from` 由 bus 绑定到创建时的 `sessionId`,正常 API 不能冒充别人;但能直接写文件的本机进程可以伪造。**这不是 v0 能防的**,要防需要 ACL + 签名 + 密钥管理,属于 v2。
|
|
400
|
-
- 不要把密钥、token、密码放进 `body`;磁盘上是明文,`acked/` 还会留一段时间。
|
|
401
|
-
- 跨用户:busRoot 应放在用户 profile/仓库下,靠 NTFS ACL 隔离;原型不主动改 ACL,部署时用 `icacls` 收紧(见 WIRING)。
|
|
402
|
-
|
|
403
|
-
### 9.2 同 profile
|
|
404
|
-
|
|
405
|
-
- `busRoot` 和 `memoryRoot` 都来自同一个 profile 配置;别名/角色只在该 root 内有效。
|
|
406
|
-
- 不同 profile 默认不共享 root。若两个 profile 显式指向同一个 root,它们可以互通——这是配置选择,不是默认行为。
|
|
407
|
-
- 不要用 `C:\ProgramData` 之类全局可写目录做 root。
|
|
408
|
-
|
|
409
|
-
### 9.3 路径 jail
|
|
410
|
-
|
|
411
|
-
原型逐层拒绝:
|
|
412
|
-
|
|
413
|
-
1. root 必须是本地路径,UNC(`\\server\share`)直接 `E_UNC_NOT_ALLOWED`。
|
|
414
|
-
2. root 用 `realpath` 解析;后续所有路径基于 real root。
|
|
415
|
-
3. `sessionId` 规范化 + 正则 + 保留名 + 结尾点/空格检查。
|
|
416
|
-
4. `ensureDirInside`:**`mkdir` 之前**先做真实路径检查——从最近存在的祖先 `realpath` 开始,不存在的段按词法拼接,真实路径必须仍在 root 内;`mkdir` 之后 `lstat` 拒绝符号链接,`realpath` 复核。NTFS junction 祖先不能在根外建目录。
|
|
417
|
-
5. 写文件(`fencedWrite`)前用同一套真实路径解析:目标不存在就逐级找最近存在祖先;任何一段含 `:`(Windows ADS)拒绝;目标本身是符号链接/junction 也拒绝。逃逸一律 `E_PATH_OUTSIDE_ROOT`。
|
|
418
|
-
6. 消息文件只接受普通文件;符号链接跳过。
|
|
419
|
-
7. `ack` 的 id 必须匹配消息 id 正则,不接受路径片段。
|
|
420
|
-
8. `aliases.json` / `roles.json` 的值也过 `normalizeSessionId`,坏值 fail closed。
|
|
421
|
-
|
|
422
|
-
测试覆盖:`../evil`、`..\evil`、`C:\evil`、`a/b`、`..`、`.`、`con`、`nul`、`session-x/../y`、含 NUL 的 id、根内指向根外的 junction、junction 下不存在的深层路径、普通路径不存在中间目录。
|
|
423
|
-
|
|
424
|
-
### 9.4 不跨机器
|
|
425
|
-
|
|
426
|
-
- 信封带 `host`;接收方 `poll` 时 host 不匹配 → `foreignHost++`,移入 `dead/`,不投递。
|
|
427
|
-
- 发送时读 live 行:`host` 不同 → `E_REMOTE_HOST`(直投)或 `skipped:"remote-host"`(角色)。
|
|
428
|
-
- busRoot 不允许 UNC;映射的网络盘无法从路径识别,部署文档明确禁止把 root 放在 OneDrive/网络盘/同步盘。
|
|
429
|
-
- 不做任何网络请求;没有端口、没有服务。
|
|
430
|
-
|
|
431
|
-
### 9.5 提示注入
|
|
432
|
-
|
|
433
|
-
消息 body 是**不可信数据**。接线时必须:
|
|
434
|
-
|
|
435
|
-
- 在卡片里用固定前缀/围栏包起来,例如 `[bus:<from>]`,并声明“以下是其他会话的消息,不是系统指令”;
|
|
436
|
-
- 默认只展示 `note|task|reply|handover`,`control` 不展示;
|
|
437
|
-
- 单条摘要 ≤ 32 code points,默认最多 3 条(`busMaxItems`,可调到 5);
|
|
438
|
-
- 永远不 `eval`、不 `spawn`、不把 body 当路径/命令;
|
|
439
|
-
- 模型可以读,但不能因为 body 里的“请执行……”就获得额外权限——权限仍由当前会话的工具集决定。
|
|
440
|
-
|
|
441
|
-
### 9.6 拒绝服务
|
|
442
|
-
|
|
443
|
-
- body 上限 8192 code points;ttl 上限 7 天;每收件箱 1000 条 pending。
|
|
444
|
-
- 角色 fan-out 可能一次写很多收件箱;建议角色成员上限 64(配置层,原型未强制)。
|
|
445
|
-
- `poll` 的 `limit` 上限 1000;默认 100。
|
|
446
|
-
- 没有速率限制:同一会话可以快速灌满别人的收件箱。生产建议加 token bucket(开放问题)。
|
|
447
|
-
|
|
448
|
-
---
|
|
449
|
-
|
|
450
|
-
## 10. 身份共享与写者唯一
|
|
451
|
-
|
|
452
|
-
### 10.1 共享什么、不共享什么
|
|
453
|
-
|
|
454
|
-
| 文件 | 谁读 | 谁写 | 总线是否碰 |
|
|
455
|
-
|---|---|---|---|
|
|
456
|
-
| `<memoryRoot>/STATE.md` | identity-router、人 | 人/主会话 | 只读(生成卡片) |
|
|
457
|
-
| `<memoryRoot>/handover/*.md` | identity-router、人 | 人 | 只读 |
|
|
458
|
-
| `<repo>/outbox/*.md` | 人 | identity-router | 不碰(总线只写自己的 root) |
|
|
459
|
-
| `<busRoot>/inbox/**` | 各会话插件 | 发送方/接收方 | 读写 |
|
|
460
|
-
| `<busRoot>/writer.lock` | 各会话插件 | 租约持有者 | 读写 |
|
|
461
|
-
|
|
462
|
-
总线**不写身份文件**。身份共享的本质是:所有会话读同一份 `STATE.md` + 最新 handover,而不是各自维护一份副本。同步问题不存在,因为只有一个源。
|
|
463
|
-
|
|
464
|
-
### 10.2 单写者租约
|
|
465
|
-
|
|
466
|
-
`writer.lock` 是一个 advisory lease:
|
|
467
|
-
|
|
468
|
-
```json
|
|
469
|
-
{
|
|
470
|
-
"schemaVersion": 2,
|
|
471
|
-
"holder": "session-alice",
|
|
472
|
-
"nonce": "9f2c1d7a4b8e0f63a5c9d1e2b7f4086a",
|
|
473
|
-
"token": 7,
|
|
474
|
-
"pid": 12345,
|
|
475
|
-
"host": "jjh",
|
|
476
|
-
"acquiredAt": "2026-11-04T03:20:00.000Z",
|
|
477
|
-
"expiresAt": "2026-11-04T03:50:00.000Z",
|
|
478
|
-
"ttlMs": 1800000
|
|
479
|
-
}
|
|
480
|
-
```
|
|
481
|
-
|
|
482
|
-
- 获取:`open(lock, 'wx')` 原子创建;已存在则读:
|
|
483
|
-
- `expiresAt` 已过 → 可抢占;
|
|
484
|
-
- 同 host 且 pid 不存活 → 可抢占;
|
|
485
|
-
- 否则返回 `{ok:false, holder, expiresAt, reason:"held"}`。
|
|
486
|
-
- **同 holder 再 claim = 续租**:token/nonce 不变,只刷新 `expiresAt`/`ttlMs`,不产生新 acquisition;但**必须带本次 acquisition 的 nonce**——缺 → `E_NONCE_REQUIRED`,错 → `E_LEASE_AUTH`。知道 session id 不等于拥有租约(P08)。
|
|
487
|
-
- 鉴权:每次 acquisition 生成随机 `nonce`(32 hex),只在该次 `claimWriter` 返回值里给出;释放/续租/写回都要带它,知道 session id 不够。
|
|
488
|
-
- 释放:holder + nonce 都对才能删;不是 holder 返回 `not-holder`,nonce 不对返回 `bad-nonce`,不误删。
|
|
489
|
-
- 续租:`renewWriter({nonce, token, ttlMs})`,或同 holder 再 `claimWriter`;默认 TTL **1800000 ms(30 分钟)**。
|
|
490
|
-
- 写回(fencing):`fencedWrite({file, token, nonce, value})` 必须带当前 `token`;锁被新持有者接管后,旧持有者的写回抛 `E_LEASE_LOST`,不会覆盖新值。
|
|
491
|
-
- **串行化(P13)**:所有写路径(`claimWriter` / `renewWriter` / `releaseWriter` / `fencedWrite`)都在 `<root>/writer.commit.lock` 这一把跨进程互斥锁内执行。锁用 `open(..., 'wx')` 创建,内容 `{pid, host, at, ownerId}`(`ownerId` 每次获取随机生成);抢不到以 4ms 自旋重试(上限 15s);同 host 且 pid 已死,或 mtime 超过 30s → stale,可回收。同一进程对同一 root 重入直接放行,避免测试 hook 里同步 `claimWriter` 死锁。
|
|
492
|
-
- **锁只能由持有者释放(P09)**:`finally` 先读回 `writer.commit.lock`,仅当 `ownerId` 与本次获取的一致才 unlink;锁被 stale 回收或接管后旧持有者看到的是别人的 `ownerId`,保留新锁不动。不做这一步时,被抢占的旧持有者退出会删掉新持有者的锁,第三个进程就能在新持有者仍写的时候进入临界区(租约复检挡住了脏写,但互斥已经破了)。读不出记录或缺 `ownerId` 时同样不删,留给 30s stale 路径回收。
|
|
493
|
-
- **三次校验**:`fencedWrite` 在互斥区内依次校验租约——进入后、`JSON.stringify` 之后(序列化会执行用户 `toJSON`,是天然的可注入暂停点)、临时文件写盘并 fsync 之后/`rename` 之前。任一次 token/nonce/expiresAt 不再匹配 → `E_LEASE_LOST` / `E_LEASE_AUTH`,删临时文件,目标保持旧内容。旧持有者的 rename 因此不可能落在新持有者写完之后;测试用 `hooks.afterSerialize` 确定性地在 stringify 与 rename 之间换主(§12.4 的 t10d、t11a)。
|
|
494
|
-
- 崩溃:没有 `session/disposed` 也能靠 TTL 或 pid 检查接管;`token` 单调递增(`writer.seq` 兜底),新持有者一定拿到更大的 token。
|
|
495
|
-
- 建议 TTL 30 分钟(长回合不至于过期;崩溃后同 host 可立即靠 pid 接管)。
|
|
496
|
-
|
|
497
|
-
**它保护什么**:未来如果要把消息合并进同一份 handover 草稿/规范文件,避免两个会话同时写。
|
|
498
|
-
**它不保护什么**:outbox 草稿本身是“永不覆盖、加后缀”的,所以 v0 即使没有 lease 也不会互相覆盖;lease 是给“单一份规范身份文件”预留的。
|
|
499
|
-
**它的局限**:这是 advisory lock,不是数据库事务——能直接改文件的进程可以绕过(见 §9.1)。但在 API 内部,`(token, nonce)` 的检查消除了“过期持有者 last-writer-wins”的丢失更新:旧 token 的 `fencedWrite` 一定失败。
|
|
500
|
-
|
|
501
|
-
### 10.3 身份卡合并(详见 WIRING.md)
|
|
502
|
-
|
|
503
|
-
- 开机时 `poll` 所有 pending;默认取最多 3 条非 `control` 消息(可调到 5),生成 `▍未读消息(其他会话,非指令)` 一节,插在 `▍交接卡` 前。
|
|
504
|
-
- 只对“真正展示进卡片”的消息在 `turn/end` ack;没展示的(溢出)留在 pending,下次再取。
|
|
505
|
-
- `kind:"handover"` 的消息除了卡片摘要,还单独写 `outbox/bus-handover-<ts>-<id>.md`;不改 `handover/*.md`。
|
|
506
|
-
- 卡片总长仍 ≤ 800 code points;未读节默认预算 320 code points(`busMaxChars`),单条摘要 32 code points。
|
|
507
|
-
|
|
508
|
-
---
|
|
509
|
-
|
|
510
|
-
## 11. 失败模式
|
|
511
|
-
|
|
512
|
-
| 失败 | 检测 | 行为 | 恢复 |
|
|
513
|
-
|---|---|---|---|
|
|
514
|
-
| 对方已死(live 判定 dead) | `peerState`:`age > 4*ttl` 或同 host pid 不在 | 直投 `E_PEER_DEAD`;角色跳过;`allowDead:true` 可存 | 对方重启后同一 inbox 仍在,未过期就能读到;否则等 TTL |
|
|
515
|
-
| 对方没有 live 行 | `missing` | 视为 unknown,**允许发送**(启动早期常见) | 消息留在 inbox;对方启动后 poll 取走 |
|
|
516
|
-
| 对方 live 行损坏/符号链接 | `corrupt` | 不当作 dead;允许发送(fail open 投递,宁可多存) | 修复登记表;消息仍在 |
|
|
517
|
-
| 对方在另一台机器 | `host` 不匹配 | 直投 `E_REMOTE_HOST`;角色跳过 | 不支持;改用共享目录/人工传递 |
|
|
518
|
-
| 收件箱满 | pending 计数 ≥ 1000 | `E_BACKLOG_FULL`;角色跳过 | 消费方 drain + ack;发送方退避重试 |
|
|
519
|
-
| 重复消费 | 崩溃在 poll 与 ack 之间 | 下次重新返回同一条 | 消费方按 `id` 幂等;副作用去重 |
|
|
520
|
-
| 重复发送 | 发送方超时重试 | 无 dedupKey → 两条不同 id;有 dedupKey → 同 id | 重试一律带 dedupKey |
|
|
521
|
-
| 同键不同内容 | 文件已存在且 body/kind 不同 | `E_DEDUP_CONFLICT`,不覆盖 | 换新键;或人工检查旧消息 |
|
|
522
|
-
| 消息损坏/字段不合法 | JSON parse 失败/校验失败 | 移入 `dead/`,`corrupt++`,继续 | 修文件后手工移回;或忽略 |
|
|
523
|
-
| 外来 host 消息 | `host` 不匹配 | 移入 `dead/`,`foreignHost++` | 正常隔离,不需处理 |
|
|
524
|
-
| 半截写 | 读方看不到临时文件;rename 原子 | 不会发生半截 JSON | 崩溃留下的 `.tmp-*` 可安全清理(原型不自动清) |
|
|
525
|
-
| 磁盘满/权限错 | `E_WRITE` / `E_BAD_ROOT` | send 抛错;插件降级为“不投递” | 清盘/修 ACL;消息未写,重试 |
|
|
526
|
-
| 时钟跳变 | 过期判断异常 | 跳快→提前过期;跳慢→延后 | 同机 NTP;不超过 7 天 TTL;关键消息用 id 游标 |
|
|
527
|
-
| 发送时钟超前 | `ts > Date.now() + maxClockSkewMs`(默认 300000ms) | `E_BAD_CLOCK`,不建目录、不写文件 | 校时;区分注入的测试时钟与系统时钟 |
|
|
528
|
-
| 消息 ts 在未来(收侧) | `ts > now + maxClockSkewMs` | `futureTs++`,移入 `dead/<id>.future-ts.json`,不返回、不当游标 | 正常消息照常可见;坏消息可人工检查 |
|
|
529
|
-
| 写路径竞争/租约换主 | 提交锁 + 三次 lease 校验 | 旧持有者 `E_LEASE_LOST`(或 `E_LEASE_AUTH`),目标保持旧内容 | 重新 `claimWriter` 后重写;不会 last-writer-wins |
|
|
530
|
-
| 会话被强杀 | 无 `disposed` | lease 等 TTL/pid 接管;未 ack 消息重投 | 重启后 poll 恢复 |
|
|
531
|
-
| 插件 poll 抛错 | 异常 | 接线层 catch,卡片照常生成(没有未读节) | 记录 warning;下轮再试 |
|
|
532
|
-
| 消息洪水 | 积压上限 | 后来的发送被拒 | 限流(未实现);人工清理/扩容 |
|
|
533
|
-
|
|
534
|
-
---
|
|
535
|
-
|
|
536
|
-
## 12. 原型 API 与测试
|
|
537
|
-
|
|
538
|
-
### 12.1 工厂
|
|
539
|
-
|
|
540
|
-
```js
|
|
541
|
-
import { createBus } from './prototype/bus.mjs';
|
|
542
|
-
|
|
543
|
-
const bus = createBus({
|
|
544
|
-
root: '<work-dir>/session-bus/queue', // 必填,本地可写目录
|
|
545
|
-
sessionId: 'session-alice', // 绑定后 send 的 from / ack 的收件人
|
|
546
|
-
host: 'jjh', // 默认 os.hostname()
|
|
547
|
-
memoryRoot: '<memory-root>', // 用于定位 .longlive/live
|
|
548
|
-
now: () => Date.now(), // 测试注入
|
|
549
|
-
maxBodyChars: 8192,
|
|
550
|
-
maxPending: 1000,
|
|
551
|
-
maxClockSkewMs: 300000, // 发送侧未来时钟容忍;收侧用同一阈值
|
|
552
|
-
referenceNow: () => Date.now(), // 只给发送侧墙钟哨兵用(测试可钉死)
|
|
553
|
-
hooks: {}, // 测试 seam,如 afterSerialize
|
|
554
|
-
});
|
|
555
|
-
```
|
|
556
|
-
|
|
557
|
-
### 12.2 方法
|
|
558
|
-
|
|
559
|
-
| 方法 | 输入 | 成功返回 | 主要错误 |
|
|
560
|
-
|---|---|---|---|
|
|
561
|
-
| `send({to, body, kind?, ttl?, dedupKey?, allowDead?})` | 见 §5 | `{ok, id, from, results[], skipped[], partial?}` | `E_PEER_DEAD`, `E_REMOTE_HOST`, `E_BACKLOG_FULL`, `E_BODY_TOO_LARGE`, `E_BAD_*`, `E_DEDUP_CONFLICT` |
|
|
562
|
-
| `poll({sessionId?, since?, limit?})` | `sessionId` 默认绑定值 | `{ok, sessionId, messages[], cursor, scanned, expired, corrupt, foreignHost, futureTs, futureCursor, hasMore}` | `E_BAD_SINCE`, `E_PATH_OUTSIDE_ROOT` |
|
|
563
|
-
| `ack(id)` | 消息 id | `{ok, already}` 或 `{ok:false, code:"E_NOT_FOUND"}` | `E_BAD_MESSAGE_ID`, `E_ACK_FAILED` |
|
|
564
|
-
| `peerState(id)` | 会话 id | `{state, remote?, live}` | `E_BAD_SESSION_ID` |
|
|
565
|
-
| `claimWriter({holder?, ttlMs?, nonce?})` | 默认绑定 sessionId;同 holder 续租必须带 nonce | `{ok, holder, token, nonce, expiresAt, created, renewed?}` 或 `{ok:false, holder, reason, code?}` | `E_LEASE_WRITE`, `E_NONCE_REQUIRED`, `E_LEASE_AUTH` |
|
|
566
|
-
| `renewWriter({nonce, token?, holder?, ttlMs?})` | 必须带 acquisition nonce | `{ok, renewed, holder, token, nonce, expiresAt}` 或 `{ok:false, reason}` | `E_LEASE_WRITE` |
|
|
567
|
-
| `releaseWriter({holder?, nonce, token?})` | holder + nonce 都对才删 | `{ok, released, holder?}` | `E_LEASE_WRITE` |
|
|
568
|
-
| `fencedWrite({file, token, nonce, value, holder?})` | 相对 root 或 root 内绝对路径;不能是 root 本身或已存在目录 | `{ok, file, holder, token}`;锁内三次校验 | `E_LEASE_LOST`, `E_LEASE_AUTH`, `E_PATH_OUTSIDE_ROOT`, `E_BAD_PATH`, `E_BAD_VALUE`, `E_WRITE` |
|
|
569
|
-
| `writerStatus()` | — | `{ok, held, holder?, expiresAt?}` | — |
|
|
570
|
-
|
|
571
|
-
`send` 的 `results[]` 每项:`{to, id, deduped, peerState?, path}`;角色 fan-out 时部分成功 `partial:true`。
|
|
572
|
-
|
|
573
|
-
### 12.3 错误码分组
|
|
574
|
-
|
|
575
|
-
- 参数:`E_BAD_SESSION_ID`, `E_BAD_TARGET`, `E_BAD_ALIAS`, `E_BAD_ADDRESS_BOOK`, `E_BAD_BODY`, `E_BODY_TOO_LARGE`, `E_BAD_KIND`, `E_BAD_TTL`, `E_BAD_DEDUP_KEY`, `E_BAD_SINCE`, `E_BAD_MESSAGE_ID`, `E_BAD_CLOCK`, `E_BAD_PATH`, `E_BAD_VALUE`
|
|
576
|
-
- 路径/安全:`E_PATH_OUTSIDE_ROOT`, `E_UNC_NOT_ALLOWED`, `E_BAD_ROOT`
|
|
577
|
-
- 投递:`E_PEER_DEAD`, `E_REMOTE_HOST`, `E_BACKLOG_FULL`, `E_NO_LIVE_RECIPIENTS`, `E_UNKNOWN_TARGET`
|
|
578
|
-
- 幂等:`E_DEDUP_CONFLICT`
|
|
579
|
-
- 租约:`E_LEASE_WRITE`(拿不到提交锁/写锁失败), `E_LEASE_LOST`(过期或被接管), `E_LEASE_AUTH`(nonce 错), `E_NONCE_REQUIRED`(同 holder 续租缺 nonce)
|
|
580
|
-
- 存储:`E_WRITE`, `E_ACK_FAILED`, `E_CORRUPT_TARGET`
|
|
581
|
-
- 状态:`E_NO_SESSION`, `E_FROM_MISMATCH`, `E_NOT_FOUND`
|
|
582
|
-
|
|
583
|
-
### 12.4 测试(50 例,全部通过)
|
|
584
|
-
|
|
585
|
-
```powershell
|
|
586
|
-
& '%USERPROFILE%\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe' `
|
|
587
|
-
--test '<work-dir>\session-bus\test\bus.test.mjs'
|
|
588
|
-
```
|
|
589
|
-
|
|
590
|
-
`test/` 目录形式同样可用:`node --test test/`(Node 24 的位置参数按文件/glob 解析,目录由 `test/package.json` 的 `main` 指向 `bus.test.mjs`;不带 shim 时 Node 会把目录当模块解析而报 `MODULE_NOT_FOUND`)。直接 `node test/bus.test.mjs` 也可,输出自定义 runner 的 `ok N -` 行。
|
|
591
|
-
|
|
592
|
-
| # | 用例 | 覆盖点 |
|
|
593
|
-
|---|---|---|
|
|
594
|
-
| 1 | send/poll/ack round trip | 基本回路、字段 |
|
|
595
|
-
| 2 | poll is at-least-once | 未 ack 前重复投递 |
|
|
596
|
-
| 3 | duplicate ack is idempotent | 重复 ack、未知 id |
|
|
597
|
-
| 4 | dedupKey send idempotency and conflict | 幂等发送、同键冲突 |
|
|
598
|
-
| 5 | TTL expiry discards | 注入时钟、过期删除 |
|
|
599
|
-
| 6 | dead session refusal and allowDead / role skip | live 判定、死信、角色跳过 |
|
|
600
|
-
| 7 | path escape and bad session ids | 越权路径、保留名、NUL |
|
|
601
|
-
| 8 | backlog cap | 积压上限、ack 后恢复 |
|
|
602
|
-
| 9 | restart recovery with a new handle | 进程重启/新句柄读同一目录 |
|
|
603
|
-
| 10 | concurrent delivery from three processes | 3 进程 × 15 条,45 条不丢不重 |
|
|
604
|
-
| 11 | alias and role addressing | 别名、角色去重 |
|
|
605
|
-
| 12 | cross-host isolation | 远程 live 行、外来 host 消息隔离 |
|
|
606
|
-
| 13 | corrupt message isolation | 坏 JSON 不拖垮收件箱 |
|
|
607
|
-
| 14 | input validation limits | body/kind/ttl/dedupKey/空目标 |
|
|
608
|
-
| 15 | writer lease uniqueness and stale takeover | 租约互斥、释放、过期接管 |
|
|
609
|
-
| 16 | `t10a` fencedWrite token rejection | 缺 token / 旧 token → `E_LEASE_LOST`,不落盘;变异 M13 必红 |
|
|
610
|
-
| 17 | `t10b` fencedWrite nonce rejection | 错 nonce / 缺 nonce → `E_LEASE_AUTH`,不落盘;变异 M14 必红 |
|
|
611
|
-
| 18 | `t10c` same-holder re-claim without nonce | `E_NONCE_REQUIRED`,锁文件字节不变;P08 |
|
|
612
|
-
| 19 | `t10d` TOCTOU takeover after stringify | hook 内换主 → `E_LEASE_LOST`,旧文件不变;P13 |
|
|
613
|
-
| 20 | `t10e` commit lock visible and stale reclaim | 锁文件含 pid/host,结束后删除;死 pid 可回收 |
|
|
614
|
-
| 21 | `t10f` junction escape | 根内 junction 指向根外 → `E_PATH_OUTSIDE_ROOT`;P12 |
|
|
615
|
-
| 22 | `t10g` nearest existing ancestor / file symlink | 深层不存在路径仍拒绝逃逸;合法缺失目录是 `E_WRITE` |
|
|
616
|
-
| 23 | `t10h` sender future clock | 超 skew → `E_BAD_CLOCK` 且无文件;小偏移可用;P14 |
|
|
617
|
-
| 24 | `t10i` receiver future-ts quarantine and cursor | `futureTs/futureCursor`,坏消息进 dead,正常消息不丢 |
|
|
618
|
-
| 25 | `t11a` cross-process commit lock | 第二进程阻塞 ≥800ms 后 `held`,子进程退出后接管成功 |
|
|
619
|
-
| 26 | `t12a` WIRING pendingAckIds merge / sessionKeyFor | R2、R3 的文档口径与 `mergePendingAckIds` 行为 |
|
|
620
|
-
| 27 | `t12b` DESIGN invariants | commit lock、E_NONCE_REQUIRED、maxClockSkewMs、future-ts、realpath jail |
|
|
621
|
-
| 28 | `t13a` commit lock release checks the owner | 外来 `ownerId` 记录不被旧持有者删除;ownerId 每次获取都不同;F1/P09 |
|
|
622
|
-
| 29 | `t13b` three-process stale reclaim keeps the new lock | B 的锁被接管后 B 退出不删 C 的锁(D 进程在 C 临界区内观察);F1/P09 |
|
|
623
|
-
| 30 | `t13c` fencedWrite rejects the bus root itself | `file:"."` / 绝对 root → `E_BAD_PATH`,root 外不出现 `.tmp-*`;F2/P17 |
|
|
624
|
-
| 31 | `t13d` fencedWrite rejects a directory target | 目录目标 → `E_BAD_PATH`,普通文件写入不受影响;F2 |
|
|
625
|
-
| 32 | `t13e` poll clamps the cursor for ahead-of-clock messages | 超前 299s 的消息不再挡住后续正常消息,改为 at-least-once 重放;F3/P24 |
|
|
626
|
-
| 33 | `t13f` poll keeps id cursors for on-time traffic | 未超前时不夹游标;正好 300000ms 边界仍投递并夹到 `now`;F3 |
|
|
627
|
-
| 34 | `t13g` DESIGN/WIRING document owner and skew-window semantics | `ownerId`、5 分钟窗口、at-least-once 重放、`E_BAD_PATH` |
|
|
628
|
-
|
|
629
|
-
红队第三轮 F1/F2/F3 的回归见第 28–33 例;对应变异(去掉 owner 校验、去掉 root/目录守卫、去掉游标夹取)必须把它们打红,见 `FIX-REPORT-V4.md`。
|
|
630
|
-
|
|
631
|
-
红队第二轮变异 M13(删 token 校验)与 M14(删 nonce 校验)现在分别被第 16、17 例捕获(改前两例均 29/29 绿)。
|
|
632
|
-
|
|
633
|
-
测试临时目录在 `<work-dir>\session-bus\.tmp-test\`,每个用例结束后递归删除。并发用例用 `process.execPath` 起 3 个 Node 子进程,不依赖 PATH。
|
|
634
|
-
|
|
635
|
-
---
|
|
636
|
-
|
|
637
|
-
## 13. 部署与配置
|
|
638
|
-
|
|
639
|
-
### 13.1 配置项(建议)
|
|
640
|
-
|
|
641
|
-
| 配置 | 环境变量 | 默认 | 说明 |
|
|
642
|
-
|---|---|---|---|
|
|
643
|
-
| `busEnabled` | `DSH_SESSION_BUS_ENABLED` | `false` | 关闭时完全不触碰总线 |
|
|
644
|
-
| `busRoot` | `DSH_SESSION_BUS_ROOT` | 空 → 外部 outbox/bus | 本地绝对路径;拒绝 UNC |
|
|
645
|
-
| `memoryRoot` | `DSH_IDENTITY_MEMORY_ROOT` | identity-router 的默认 | 必须与 longlive 实际使用的 root 一致 |
|
|
646
|
-
| `busMaxItems` | `DSH_SESSION_BUS_MAX_ITEMS` | `3` | 开机卡最多展示几条(可调到 5) |
|
|
647
|
-
| `busMaxChars` | `DSH_SESSION_BUS_MAX_CHARS` | `320` | 未读节预算 |
|
|
648
|
-
| `busAckOn` | — | `turn-end` | `turn-end | never` |
|
|
649
|
-
| `busWriterTtlMs` | — | `1800000`(ms) | 30 分钟租约;单位毫秒 |
|
|
650
|
-
| `busPollEveryStep` | — | `false` | 长回合内额外 poll(节流 ≥1s) |
|
|
651
|
-
|
|
652
|
-
### 13.2 权限
|
|
653
|
-
|
|
654
|
-
- busRoot 只给当前 Windows 用户读写;部署时建议:
|
|
655
|
-
```powershell
|
|
656
|
-
icacls "<work-dir>\session-bus\queue" /inheritance:r /grant:r "$env:USERNAME:(OI)(CI)F"
|
|
657
|
-
```
|
|
658
|
-
(这是部署建议,本次调研没有执行,也没有改任何 ACL。)
|
|
659
|
-
- 不要把 busRoot 放进 OneDrive、Dropbox、Git 工作区自动同步目录或网络盘;rename 语义和共享冲突会破坏原子性。
|
|
660
|
-
- 定期清 `dead/`、`acked/`、孤儿 `.tmp-*`(建议 7 天);原型不做 janitor,避免后台定时器。
|
|
661
|
-
|
|
662
|
-
### 13.3 上线顺序
|
|
663
|
-
|
|
664
|
-
1. `busEnabled=false`,先只读 review 设计/原型。
|
|
665
|
-
2. 用外部 root 在测试会话开 `busEnabled=true`,`busAckOn=turn-end`。
|
|
666
|
-
3. 观察 `poll` 的 `corrupt/foreignHost/expired` 计数与卡片长度。
|
|
667
|
-
4. 通过后再讨论是否把 root 迁到 `<memoryRoot>/.longlive/bus`(需要 owner 批准新的 memoryRoot 写权限)。
|
|
668
|
-
5. 不要在这次只读调研里安装插件、改 profile、改宿主。
|
|
669
|
-
|
|
670
|
-
---
|
|
671
|
-
|
|
672
|
-
## 14. 开放问题
|
|
673
|
-
|
|
674
|
-
1. **busRoot 归属**:v0 走外部 outbox/bus,还是直接批准 `<memoryRoot>/.longlive/bus`?后者结构上更合理(与 live 同根、随记忆备份),但违反 identity-router v0 “不写 memoryRoot”的约定,需要 owner 明确点头。
|
|
675
|
-
2. **唤醒**:宿主已有 `followup`(live 空闲会话)与 api-session-controller resume(cold 会话)两条路,v0 仍选邮箱轮询。要不要在 v1 对 live 会话加“投递后 followup 提醒”?需要先解决:会话忙时是否排队、重启窗口内 id 失效、以及 `followup` 的稳定导出。
|
|
676
|
-
3. **ack 时机**:`turn/end` 自动 ack 是“回合结束”而不是“消息处理成功”。任务类消息是否要改成显式 ack 工具?显式更准,但多一步模型操作。
|
|
677
|
-
4. **认证**:同用户信任是否足够?如果要防同用户恶意进程伪造 `from`,需要 per-session 密钥/HMAC,以及密钥不进日志的完整方案。
|
|
678
|
-
5. **排序**:同毫秒消息按 id 字典序,不等于发送顺序。是否需要 v2 加 `seq`(每发送方单调递增)?
|
|
679
|
-
6. **保留/GC**:`acked/` 保留多久?`dead/` 保留多久?谁跑 janitor(插件定时器 vs 会话启动时)?
|
|
680
|
-
7. **限流**:角色 fan-out 上限多少?是否需要每发送方 token bucket,防止一个会话灌爆所有人?
|
|
681
|
-
8. **广播**:要不要受控的 `#all`?还是永远只允许显式角色?
|
|
682
|
-
9. **跨 profile**:两个 profile 指向同一 busRoot 是否允许?默认应该禁止,但配置上如何表达?
|
|
683
|
-
10. **UI**:未读角标/发消息面板是否要做?这属于客户端插件,和投递层解耦。
|
|
684
|
-
11. **schema 演进**:`replyTo`、`priority`、`contentType` 是否值得进 v2?还是继续用 body 里的 JSON?
|
|
685
|
-
12. **lease 竞态**:advisory lease 在“同时判定过期”时可能双写;是否接受,还是改用目录 rename/文件句柄锁?
|
|
686
|
-
|
|
687
|
-
---
|
|
688
|
-
|
|
689
|
-
## 15. 结论
|
|
690
|
-
|
|
691
|
-
- 这个设计能解决“同一台机器不同会话互发消息、共享身份”的核心问题,且不引入服务、端口、依赖。
|
|
692
|
-
- 它诚实地区分两个边界:**v0 不自动唤醒**(宿主有 API,但是取舍,见 §8),**不能跨机器**。
|
|
693
|
-
- 它把“身份共享”收敛为“同一份只读文件 + 单写者租约”,而不是每个会话复制一份身份。
|
|
694
|
-
- 原型 15 个用例覆盖了并发、重复、过期、死会话、越权、积压、重启、幂等;剩下的是接线与产品决策,不是协议本身。
|