# dsh-heartbeat · 设计与维护手册（DESIGN.md）

> 面向后续开发者与维护者。需求与决策记录见内部文档（不随仓库发布）；
> 本文描述**实际实现**：框架结构、模块实现、参数位置、诊断方法、宿主契约备忘。
> 宿主版本：DSH 0.1.2-rc.1 实测（hb-probe 探针 + 源码阅读，见 §3）；0.1.5-rc.2 经 npm 包逐包源码对比（2026-09-11，C19/C20）+ 实机升级验证（2026-09-12：会话 v3 迁移、心跳、投递全部正常）。

---

## 1. 快速事实卡

| 项 | 值 |
|---|---|
| 形态 | DSH cordis 插件（进程内服务 + web client 卡片 + 独立 CLI） |
| 宿主 | DSH 0.1.2-rc.1 实测 / 0.1.5-rc.2 已核对（见适配声明），web profile，Node ≥ 22.19（实测 24.19） |
| 适配声明 | **v1.2 需要 DSH ≥ 0.1.2-rc.1，并兼容 0.1.5-rc.2**（peer `^0.1.1-rc.2 \|\| ^0.1.5-rc.2`）；升级到 0.1.5 会触发会话格式 v3 自动迁移（C20，**先备份 `~/.dsh/sessions`**）。旧宿主（≤ 0.1.1-rc.2）请用 v1.0（v1.1 依赖 `snapshotEvents()` 与 agent 预设机制） |
| 平台 | Windows 专属（PowerShell 探针 + DPAPI + WinRT toast） |
| 语言/构建 | TypeScript + tsup（ESM）；测试 node:test + tsx，91 个 |
| 运行数据 | `dataDir`（默认 `<包根>/data`；可在 profile 的 cordis.patch.yml 按 id 覆盖钉到自定义位置） |
| 心跳节律 | 默认 20 min/跳（设置页/CLI 可调）；沉默轮零模型调用 |
| 核心循环 | `core/orchestrator.ts`：§7 七相（维护→采集→闲逛→闸门→Digest→聚焦推理→投递→留痕） |

## 2. 总体架构

### 2.1 七相主循环（core/orchestrator.ts）

```
定时器（intervalMin，首跳 boot+15s，单次）
 ① 维护   seeds gc / 日志 retention / 画像合并触发判断（单飞）/ inbox 健康检查
 ② 采集   screenpulse（截图+前台，加密落盘）→ envpulse（idle+窗口类别，明文）→ watchlist（6h 节流）
 ②′ 闲逛  条件触发（窗口 11-15/17-21 + ≥4h 间隔 + focus 冷却）；模型调用（仅 web_search）；
          结果由【代码】入池 seeds + completeWander 登记节流（D10，模型不碰登记）
 ③ 闸门   纯代码：静默窗 → 忙时窗口类别 → 在场联动 → 每日 cap → 冷却；判定留痕
 ④ Digest 现拼三切面（tact/topic/wander，≤800 tok）+ 时间 + 素材池 top + 账本待办
 ⑤ 反刍+投递（2026-09-16 改版）：⑤a 引擎室反刍备料（零工具）输出机器 JSON {speak,text,seed_ids}，从 activeSeeds 挑 ≤3 条各压缩成一句；⑤b 素材包三段式（buildMaterialPrompt）——①声明『这是心跳插件素材投递…』＋②备好的素材（每条一句，不带理由不排序）＋③（3 条里 ≥2 条 used≥1 时）『也可以说一句真心话』——注入投递目标会话的 voiceAgent，由它判断说不说/说哪条，话落在用户读的会话；归账 = attributionIds（seed_ids 优先 + ≥8 字符包含匹配兜底）
 ⑥ 投递   正身=专用心跳会话（followup 轮次已落盘）+ toast 提示（仅"有新消息"）+ D13 绑定会话投递
 ⑦ 留痕   heartbeat.jsonl（spoke/silent/spoke_failed + 原因）+ ledger + confirmSend（仅成功时计数，A5）
```

- **成本模型**：闸门前置 → SILENT 轮零 token；闲逛只在窗口开时调模型；合并裁决 12–24h 一次。
- **单飞**：beat 级 `beating` 锁 + 画像合并 `consolidating` 锁，杜绝重入。
- **离线补偿**：错过的心跳跳过；开机首跳只做维护相（表达由 cap/冷却自然拦截）。

### 2.2 模块依赖（单向）

```
core(paths/path-guard/atomic-fs/audit-log/runtime) ← 一切模块
config(load/schema) ← orchestrator, cli
vault(vault.ts + assets/vault.ps1) ← seeds, screen, gate(sent), profile(全部), ledger(明文部分)
gate(busy-rules) ← env(窗口类别), orchestrator
seeds/pool ← orchestrator(闲逛入池/归账)
core/material（反刍备料/素材包三段式，纯函数） ← orchestrator
screen/vision（ModLens 视觉桥，C23） ← orchestrator（表达相起头）
profile/{inbox,store,schema,consolidate,digest} ← orchestrator, cli（⑧consolidate 产聊天种子入池）
browse ← orchestrator(闲逛/定向), cli
notify ← orchestrator(投递后提示)
screen, env, rhythm, ledger ← orchestrator
ui(client.js) ── 通过 settings 命名空间与 host 解耦通信
cli(dist/cli) ── 独立进程，读写 data/（与宿主不共享内存状态）
```

### 2.3 进程模型

1. **宿主进程内插件**：定时器、编排、探针 spawn、模型轮次（经专用心跳会话）。
2. **PowerShell 子进程**：idle/frontwin/screenpulse/notify/vault（短命，按需 spawn）。
3. **CLI**（`dist/cli/index.js`）：独立进程，直接读写 `data/`；改不了运行中宿主的内存状态
   （间隔等 live 参数的生效以设置页/settings 命名空间为准）。

## 3. 宿主集成契约（★ 升级 DSH 版本前必读）

以下全部经 hb-probe 探针 + 源码阅读实测（2026-09-06 首次；2026-09-10 针对 `0.1.2-rc.1` 复查并补 C12–C17）。DSH 升级后逐条复查：

| # | 契约 | 细节 |
|---|---|---|
| C1 | 插件装载 | 包主入口导出 `{name, inject, Config(schemastery), apply(ctx, config)}`；`package.json` 的 `dsh.bundle.patch` 指向随包 cordis.patch.yml；`dsh plugin --profile X add <pkg>` = pnpm 安装 + `dsh.profile.bundles` 自动对账（声明 `dsh.bundle` 的依赖自动入层） |
| C2 | **effect 语义** | `ctx.effect(fn, label)`：**fn 立即执行**，fn 的**返回值**才是 fiber 卸载时调用的 disposer（vision-router：`effect(() => releaseTransport)`）。把清理逻辑直接写进 fn = 立即自我销毁（r5 踩坑） |
| C3 | agent 获取三态 | 会话 live（UI 开着/已 resume）→ `ctx.agents.get(sessionId)` 直接取裸 agent；持久化但空闲 → `agents.resume({resumeSessionId, setup})`；全新 → `agents.create({sessionId, meta:{cwd}, setup})`。create 对已持久化 id 报 "already owns this identity"；resume 对 live 会话报 "while it is live"。**0.1.2-rc.1 起还必须显式传 `agentOptions`（C12）、在 `setup` 里加入预设（C13）**；`setup` 可以是 async——工厂会 await 它，抛错即回滚创建 |
| C4 | 句柄解包 | `agents.create/resume` 返回 **`AgentHandle{agent, dispose}`**，裸 agent 在 `.agent` 上 |
| C5 | 模型轮次 | `agent.followup(createUserMessage({content, source:{kind:'plugin', plugin, form:'snapshot', sections}}))` + `await agent.whenIdle()`；助手文本扫描事件流里 `type含'assistant'` 的事件提取（content 可能是字符串/数组/嵌套，见 orchestrator.assistantText；**必须排除 reasoning 块，见 C14**）。**0.1.2-rc.1 移除了 `Session.events`**：改读 `snapshotEvents(fromSeq?, toSeqExclusive?)` + `seq`，插件侧封装 `sessionEvents()` / `sessionEventCount()` 做兼容回退 |
| C6 | 工具限制 | `agentCtx.get('tools').restrict({allow:['web_search']})` —— 在 `setup(agentCtx)` 钩子里调用，按 agent 作用域终身生效（需求 8 的模型侧硬保险）。**只能点名"继承层"里的工具**：`dsh-tools` 的 `view(scope)` 把 agent 自身层的注册只加进 `knownNames`、**不加进 `restrictableNames`**，所以没有预设的裸 agent 连 `web_search` 都点不了名（`tools.restrict() names unknown global tool "web_search"`）——见 C13。另：`tools.schemas()` 不传 scope 拿的是**全局视图**，不能拿来判断预设是否挂上，判据是同行的 `restrict=ok` |
| C7 | pre-step 注入 | `ctx.on('agent/pre-step', async ({agent,turn,step,signal}, next) => {...}, {prepend:true})`；waterfall：`await next()` 后返回 `{kind:'enter', messages:[...]}` 追加式注入（不碰前缀）。**step===1 且末事件 `agent/inbox/spliced` = 用户发起轮次；step>1 且 `step/end` = 任务中途**（日常会话时间注入/状态栏的门控信号） |
| C8 | settings | **两代 API（v1.6.0 起特性探测并存）**。0.1.5-rc.2（dsh-settings 0.1.5）：旧自由函数 `installSettingsSection` **已删除**，改为宿主 `settings` 服务（cordis Service 名 `"settings"`）的实例方法 `provider.installSection(ctx, 'heartbeat', Config, entry, {setSource, onChange})`，且插件模块 `inject` **必须声明 `'settings'`**（严格解析，未声明即拒——与 C21 同族）；0.1.1/0.1.2 时代包内仍是自由函数 `installSettingsSection(ctx, settingsNamespace(ns), …)`。**此包是插件运行时真依赖，必须放 dependencies**（v1.5.1 误挪 peer 后 profile 里的实体包被清掉，节律配置"保存不生效 + 重启回默认"——2026-09-18 修）。client：`ctx.settingsScope.bind({namespace})` → `getSnapshot()/subscribe()/set(field, value)`，落宿主 settings 服务的 user 层持久化 |
| C9 | client 契约 | `dsh.client:{platform:'web'}` + exports `"./client"`；client 模块 = `window.__ModuleLoader__.load({id, factory})`，**factory 必须返回带 `apply` 的对象**（client 侧也跑 cordis，同样校验）；设置卡片 = `ctx.slots.inject('settings.section', function*(){ yield ctx.slots.register({name:'settings.section', id, order, label, inject}, ReactComponent) })`；client inject 服务：`settingsScope / slots / locale / sessions / remote` |
| C10 | 安装是复制 | `file:` 协议安装 = 目录拷贝，**改源码后必须重拷 dist 到 node_modules 副本或重跑 `dsh plugin add`**，否则跑的是旧代码 |
| C11 | 持久化布局 | `~/.dsh/sessions/<cwd-slug>/<sessionId>/session.jsonl.zstd`（zstd 可用 node:zlib 解）；会话 flush 是惰性的，活跃内容可能只在内存 |
| C12 | **模型路由（0.1.2-rc.1 变更）** | `agents.create/resume` 的 `agentOptions` 默认 `{}`，**0.1.2-rc.1 起不再代填部署默认**：不传就 `options.model === undefined`，内置 persona（0.1.5 起拆为 `deployment:persona-prefix`/`-suffix` 段，原 `deployment:persona`，`You are a coding agent powered by the {{model}} model…`）插值失败，**每一轮**都在起点抛 `prompt variable "{{model}}" has no value for this assembly (section "deployment:persona")`。宿主自己的做法（`dsh-api-session-controller` 的 `agentOptions()`）是读默认选择；插件侧 `defaultAgentOptions(ctx)` 调 `ctx.get('agentDefaultModel').currentSelection()` → `{provider, model, reasoningEffort?}`。**投递目标的 resume 同样必须带它**（2026-09-10 晚踩坑）：`acquireTargetAgent` 漏传时拉起的 agent 没有模型路由（审计 `deliver_target_resumed model="(none)"`），投递回合每次都死在 `{{model}}` 插值上；更要命的是宿主会把该 agent 当作这个会话的 live agent 继续复用（`api-session` 的 `createOrAdopt`：`live !== undefined → return live`），于是**报错出现在用户自己的会话里**。修好后投递一结束就 `handle.dispose()`（审计 `deliver_target_released`），把被插件改造过的 agent 还回去，宿主会在用户下次打开该会话时按自己的 composition 重建 |
| C13 | **agent 预设** | `agents.create/resume` 发布的是**裸 agent**：不加入任何预设时，工具/提示段/技能目录全部按**空全局层**解析（`dsh-agent-presets` 原话："agent \"X\" was published without joining an agent preset; its tools, prompt sections, and skill catalog resolve against the empty global layer"），部署预设里的 `web_search` 因此完全不存在，闲逛相只能返回空数组。修法：在 `setup(agentCtx)` 里 `await agentCtx.get('agentPresets').mount(agentCtx, id)`（async，要求 `scopeOf(agentCtx)` 有效，id 缺省用 `defaultId`）。预设布局：`<dshHome>/.agent-presets/<id>/{agent.cordis.yml, preset.yml}`（随附预设根 `<dsh-agent-presets>/presets/`；组合文件名固定 `COMPOSITION_FILE='agent.cordis.yml'`；id 需匹配 `[a-z0-9][a-z0-9-]*`）。服务另有 `list/read/copy/mount/composeFrom/standingKeyFor/select`。**预设目录在用户家目录**，插件不要求用户手抄：模板随包在 `assets/presets/heartbeat/`，启动时自动补齐（见 C18） |
| C18 | **预设自动安装** | 插件启动时（`ctx.inject(['agentPresets'], …)` 里）取 `agentPresets.roots`（**公开 getter**，返回 `resolvedRoots`）里 `trust === 'user'` 的那一项，作为真正被扫描的用户预设根——不必自己猜 `~/.dsh`，也不依赖 `@deepseek-ai/dsh-home-paths`（该包**不在** profile 的 node_modules 里，import 不到）。`installBundledPreset()` 的语义：目录/文件缺失 → 建（`created`）；目录在但缺 `agent.cordis.yml` → 补（`repaired`）；**已有 composition 文件一个字节都不动**（`exists`，手改过的自定义预设安全），只有 `force` 才覆盖（`restored`）；`installPreset:false` → `skipped-disabled`。CLI 走 `conventionalUserPresetRoot()`（`$DSH_HOME.trim() || home/.dsh` + `/.agent-presets`）。另：`dsh-agent-presets` 的 `list()` 每次调用都重新 readdir（`scanRoot`，**无缓存**），所以运行期新建的预设目录对下一次 `mount()` 立即可见，**不需要重启宿主** |
| C14 | **事件形态** | `assistant/message` 的 `content` 是**块数组**：`[{type:'reasoning',text:…},{type:'text',text:…}]` —— reasoning 块同样带 `text` 字段，若按 `typeof c.text === 'string'` 过滤，会把思考草稿与正文**无分隔拼接**（`…{"speak":false}{"speak":false}`），JSON 解析必崩（`SyntaxError: Unexpected non-whitespace character after JSON at position 15`）。**读模型输出必须排除 reasoning 块**；流式事件里另有 `{type:'block-start',blockType:'reasoning'}` 与 `block-end.block.type` 可判 |
| C15 | **client 模块身份** | client 模块的注册 id 必须**严格等于包名**：`dsh-client-modules` 的 `resolveSource(entry)` 取 `entry.options.name` → `resolveMeta` → `locatePkgJson`/`nearestPackage` 向上找 `package.json` 并要求 `name === expectedPackageName`；不匹配返 null，该包被从 client 组合里**静默剔除**——**没有任何报错**，host 半照跑、数据照写，只是设置页整块消失。三处必须一致：`package.json.name`、`cordis.patch.yml` 里 insert 行的 `name`、`client.js` 的 `window.__ModuleLoader__.load({id})` |
| C16 | **前端 bundle 缓存** | client bundle 由宿主**启动时**读入内存并按内容打 immutable 缓存（组合 URL 形如 `/plugins/??ids/client.js&rev`），`dsh-client-modules` 内**没有 fs.watch**（热重载只在 dev 模式）→ 改 `client.js` 后刷新页面无效，**必须重启 DSH** |
| C17 | 会话标题存储 | 0.1.2 起标题在**每会话一条记录**：`~/.dsh/storages/session_projcache/sessions/<sessionId>.json` 的 `rows.title.val`（子代理会话的记录没有 `session-` 前缀，应跳过）；旧的单文件聚合 `~/.dsh/storages/session_projcache.json` 只作兼容回退 |
| C19 | **0.1.5 事件形态（assistant/attempt）** | 0.1.5-rc.1 起 `assistant/chunk` 事件**更名** `assistant/attempt`（载荷 `{turn, step, stream: AssistantStreamRecord[]}`，失败/重试/取消的尝试整段嵌入）；新增 surface 事件 `system/message`（系统提示作为 surface 节点 0 记入日志）。对插件的影响面：①`terminalTurnError()` 兼容扫描两种事件（`turn/end` 的 error reason 主路径未变）；②`assistantText()` 不受影响——`assistant/message` 仍带 `message: AssistantMessage`，attempt 事件无 content 会被空文本自然跳过；③观察相按事件类型过滤、光标按 seq 索引，插入新事件类型无影响 |
| C20 | **0.1.5 持久层重构（格式 v3 迁移）** | 持久层拆成中立契约包 `dsh-session-persistence` + 独立后端 `dsh-session-persistence-jsonl`（仍是一个仅追加 `.jsonl.zstd` 产物/会话）。`SESSION_FORMAT_VERSION` **0 → 3**：旧版本头被拒绝（"session header version must be 3"），宿主内置**代际迁移**——保留历史代文件（`session.jsonl.zstd` = v0），首次访问时解码-迁移-校验后发布当前代文件（版本化文件名），源文件只读不改。**升级宿主前必须备份 `~/.dsh/sessions`**（用户数据危险操作）；会话目录从单文件变多代文件布局，`scripts/repair-session.mjs` 的"先找备份再改 v0 文件"手册要按新布局复查（迁移后的当前代是 v3 格式，修复工具只应再碰 v0 历史代） |
| C21 | **0.1.5 cordis 严格服务解析（自定义 RPC 通道退役 → /api 精确路由）** | 0.1.5 的 cordis 解析器沿 fiber 链找服务，访问许可由 fiber 的模块级 `inject` 声明决定；而 cordis `Service` 把 `this.ctx` **固定在提供方自己的上下文**（client-connection 的模块 inject 只有 `['credentials']`）。于是 `connection.rpc.handle(channel, …)` 内部的 `owner.webServer.register(route)` 是在**别人的 fiber** 上读 `webServer` → 必抛 `cannot get property "webServer" without inject`——**调用方无论怎么 inject 都救不了**（现场取证 2026-09-12：合并 inject `['connection','webServer']` + effect 包裹仍是此错，`scoped` 本身读 webServer 正常）。症状：路由不存在 → 浏览器 POST `<channel>/<endpoint>` 落到 `dsh-host-frontend-static` 的 **fallback 座位** → **HTTP 405**（卡片全部分区"加载失败"，host 静默）。**0.1.5 正解**：`connection.fetch.register()` 在 `/api` 下注册精确 Fetch 路由——只写 connection 内部路由表、不碰任何其他服务，0.1.2/0.1.5 的 `/api` 共享处理器都先查精确路由，两代通用；浏览器认证由 `/api` 前缀的 `requestRejection` 统一把关。信封与 `/api` 同构（`client-request`/`server-response`），端点名走 `payload.endpoint`；客户端 `rpc.call('/api', 'heartbeat', {endpoint, …})`。**鉴别**：405 = 路由没注册；404 = 端点不匹配；401/403 = /api 认证拦截 |
| C22 | **兴趣/时段卡片编辑（interests-edit，v1.4.0）** | 权威文件仍是 `interests.json`（browse.ts `loadInterests`：用户层**整体取代**出厂层）。卡片编辑走 `interests.list/add/remove/setWindows` 四端点；**首次成功变更时把出厂文件逐字节复制进用户层**（D22 首编继承），此后用户层即唯一权威——出厂文件更新不再自动跟上。读取（`interests.list`）与**失败的校验**都是只读，绝不顺手创建用户层（否则看一眼卡片就接管了出厂配置）。窗口校验：HH:MM、同日起始<结束、1–6 个、两两不重叠（裁判取第一个命中窗口，重叠会静默改变优先级）；兴趣条目：trim+折叠空白、≤60 字、大小写不敏感去重、≤32 条。`_comment` 等未知顶层键在保存时保留 |
| C23 | **ModLens 视觉缝隙（screen/vision.ts，v1.6.0）** | 截图描述走宿主 profile 里的 `@liustack/modlens` CLI（与插件同在 profile node_modules 树，**运行时向上解析** `dist/main.js`，不存绝对路径；解析不到 = 视觉静默关闭）。调用形态 `node main.js -i <解密截图> -o <tmpJson> -p <provider> --timeout <ms>`，输出 JSON 取 `result.summary`（宽容解析 result.summary/summary/ocr.full_text）。**必须 `-p` 钉死 provider**：默认链先探测 Antigravity CLI 登录态，未配置时干转 ~97s 后 exit 1（2026-09-18 现场故障）；默认 `-p openai`（本部署的 glm-4v-flash 通道），`data/settings/vision.json` 的 `{provider,prompt}` 可覆盖。stderr 捕获（截 4000 字）进 `screen_vision` 审计行。异步 spawn（同步会冻结宿主事件循环）；截图"解密→用→焚"复用 screenpulse 的 unlockShot/burnUnlocked |

## 4. 模块详解

### 4.1 core/（地基 + 编排）

| 文件 | 职责 | 关键点 |
|---|---|---|
| `paths.ts` | dataDir 解析 + 包定位 | 优先级：env `HEARTBEAT_DATA_DIR` > 插件 config `dataDir` > `<包根>/data`；`initWorkspace` 幂等建目录（data/settings/logs/tmp/exports） |
| `preset-install.ts` | 随包预设的安装/校验（C18） | `bundledPresetDir(moduleUrl, id)` 从模块 URL 向上 ≤5 层找 `assets/presets/<id>/agent.cordis.yml`（dist/index.js 与 dist/cli/index.js 两种深度都能命中）；`userPresetRoot(roots)` 取 roster 里 `trust==='user'` 的根；`installBundledPreset()` 永不覆写已有 composition；`presetStatus()` 供 `preset status` 比对模板 |
| `path-guard.ts` | 路径白名单守卫 | **先 `fs.realpathSync` 规范化（不存在的目标：realpath 最深存在祖先 + 回拼缺失尾部），再与规范化后的 dataDir 做大小写不敏感、带分隔符边界的前缀比对**。必测向量：`..` 穿越/符号链接/8.3 短名/大小写/UNC（tests/path-guard.test.ts） |
| `atomic-fs.ts` | 原子写 | 同目录随机 tmp + rename（Windows 下替换写）；`shredFileSync` 覆写 x N 后删除 |
| `audit-log.ts` | JSONL 审计 | `appendAuditLine` / `readAuditLines`（坏行保留为标记）/ `pruneAuditFile`（按龄裁剪，原子重写） |
| `runtime.ts` | 运行时单例 | paths/guard/policy 注入各模块；测试用 reset 钩子 |
| `orchestrator.ts` | 七相编排 | 见 §2.1；⑤a 反刍备料 + ⑤b 素材包投递（buildRuminationPrompt / buildMaterialPrompt，见 `material.ts`）；`agentTurn` 提取助手文本（形态防御 + 失败落盘事件窗口形态；取最后一个含中文行，过滤工具收尾标签，2026-09-16 修）；归账 = attributionIds（seed_ids 优先 + 输出↔素材包含匹配，轻引导）（≥8 字符）；投递 = D13 绑定会话 splice（wakeup=true，live 才投） |

### 4.2 config/（三层优先级，从低到高）

1. **出厂** `config/policy.json`（包内只读）；
2. **用户文件层** `data/settings/policy.json`（deepMerge，非法即 fail-closed）；
3. **组合条目覆盖** cordis.patch.yml 里 `id: heartbeat` 的 config（`intervalMin`/`maxDailySend`，0=不覆盖）；
4. **settings 命名空间 live 值**（设置页保存的 `intervalMin`/`maxDailySend`，经 hooks 实时生效并重排定时器）。

> 注意：`intervalMin`/`maxDailySend` 这两个 UI 字段只在 settings/entry 层有意义（0=沿用 policy 文件）。
> 其余全部参数只有第 1/2 层（policy.json 的子树），改 `data/settings/policy.json` 后重启生效。

### 4.3 vault/（加密）

- `assets/vault.ps1`：DPAPI（CurrentUser）整文件加解密，KHBV1 ASCII 头；**ASCII-only**（避 PS5.1 代码页坑）。
- `vault.ts`：`loadJson/saveJson`（密文自动识别、明文兼容读）、`encryptFile/decryptFile`、`load/saveEncryptedText`（seeds.jsonl/inbox/journal 用）、`readText/writeText`（ledger 等明文）。
- v2 加固：明文临时窗**只落 `data/tmp/`**（v1 在目标旁）；所有路径先过守卫；加密失败 fail-closed。
- `burn-list.ts`：**焚毁清单单一事实源**（v1 曾两份硬编码漂移漏文件）；burn=预演/`--yes`（覆写x3+删）/`--all`（连 data/settings）；`uninstall --purge` 复用同一清除核心；焚后 journal 重建并写 `BURN_EVENT`。

### 4.4 gate/（分寸闸门）

- 判定顺序（`evaluateGate` 纯函数，全部可单测）：静默窗 → 忙时窗口类别（live frontwin 探针优先，快照 >15s 不采信）→ 在场 active → 每日 cap → 冷却 → SPEAK。
- `confirmSend` **只在投递成功后调用**（A5：失败不计数不留冷却）；读写 sent.json（DPAPI）。
- 配置读失败 → 最保守 SILENT（fail-closed）。

### 4.5 seeds/（素材池）

- 存储 `seeds.jsonl`（DPAPI，一行一条）；`{id, text, topic, tag, source, confidence, protected, used, bornAt, expiresAt, lastUsedAt, lastEvidenceAt, status, retireReason}`。
- 四条淘汰规则（`gcPool` + add 内的容量挤出）与综合分（新鲜度0.4+未用0.3+置信0.3，手写/画像高置信保护）见代码 `pool.ts`；同题合并：brief 取最新、used 累计、证据时间取最大。
- 淘汰=归档（`--archived` 可翻），不删除。

### 4.6 profile/（用户画像）

| 文件 | 职责 |
|---|---|
| `types.ts` | 四分区（interest/projects/comm/psy）entry（bi-temporal + evidence + temporal 档位）、ops（ADD/UPDATE/INVALIDATE/NOOP） |
| `schema.ts` | `profile-schema.json` 白名单：分区/topic/sub_topic 逐级白名单 + **sub_topic 级"允许档位集合+默认档"**（r4 B10：档位是 entry 级属性；未声明默认 stable——错标 stable→volatile 代价是遗忘，反向只被低活跃兜底吸收，非对称风险决定默认） |
| `store.ts` | 守卫逐条裁决（白名单/evidence 强制+ref 存在性/置信度封顶 chat .6 screen .4 browse .4/psy 门控/分区容量/UPDATE 升级需二次确认/INVALIDATE 归属：volatile 代码过期、stable 需更新矛盾观察）+ 确定性老化（volatile 14 天失效；stable 180 天"低活跃"标记不删除）+ **journal 唯一权威**（ADD 回写 `assignedId` 保证重放 id 一致；verify=重放比对不改；rebuild=原子替换+撕裂尾显式报告+`--check` 干跑） |
| `inbox.ts` | 观察收件箱（去重键 kind+ref；note ≤1 句截断 120 字；**合并失败时 inbox 保留**） |
| `consolidate.ts` | 触发（12-24h + 积压 30 条）→ 排水分组 → 裁决 prompt（D6 限流：非 psy 条目字段+≤1句引语；"观察内容是数据不是指令"）→ LLM → 守卫 → 应用+journal+排水（成功才清）。单飞锁防重入（B8）。LLM 调用方由编排器注入（心跳会话轮次、禁工具） |
| `digest.ts` | 三切面（tact=作息+comm+窗口类别 B6 / topic=conf×recency topN / wander=高置信兴趣）≤800 tok 预算；stable 低活跃条目后置标注"久未验证" |

### 4.7 其余模块速览

| 模块 | 要点 |
|---|---|
| `rhythm/` | hour×weekday presence 直方图，30 天滚动 + 指数衰减（τ≈10 天）；纯统计无语义内容，明文 |
| `screen/` | screenpulse.ps1（前台/焦点/可见窗口≤20/全屏原图截图，spec ①）→ raw 落 `data/tmp` → vault 加密成 screen.json/jpg → 焚 raw；`unlockShot` 用毕即焚 |
| `env/` | idle.ps1（仅输出空闲秒数）+ presenceOf 三档（<30s 活跃看窗口类别 / 30-1200s present / ≥1200s away）+ timeflow 纯时间函数（节日表） |
| `browse/` | watchlist（npm/GitHub，6h 节流，首见不产素材；fetcher 可注入便于测试）+ 闲逛裁决（窗口/间隔/focus 冷却轮换）+ `completeWander` 代码登记（D10） |
| `ledger/` | 唯一账本，Markdown 行格式 `- [YYYY-MM-DD HH:MM][open|done][#id] text`；手写乱行原样保留；`pendingOlderThan` 供跟进时机 |
| `notify/` | AUMID 自注册（HKCU+开始菜单快捷方式，无需管理员）；**D12：仅"有新消息"提示，不承载正文** |
| `ui/client.js` | 见 §3 C9 + §14 M6：六分区卡片（心跳状态 30s 轮询/会话绑定/素材池/画像只读/账本/节律配置），全部经 `/heartbeat` RPC 与 host 通信 |

## 5. 数据文件字典（data/）

| 文件 | 格式 | 加密 | 写入者 | 读取者 | retention |
|---|---|---|---|---|---|
| `settings/policy.json` | JSON | 否 | 手编/UI（未接） | config.load（启动） | 永久 |
| `settings/profile-schema.json` | JSON | 否 | 手编 | profile.schema（启动） | 永久 |
| `settings/bindings.json` | JSON | 否 | CLI `bind` / 手编 | orchestrator（每跳现读） | 永久 |
| `profile.json` | JSON | DPAPI | store（合并裁决后） | digest/consolidate/CLI | 永久（可由 journal 重建） |
| `profile_inbox.jsonl` | JSONL | DPAPI | 观察来源 | 合并排水 | 排水即清 |
| `profile_journal.jsonl` | JSONL | DPAPI | store（权威流水） | verify/rebuild | 按年分片（v1.5） |
| `profile_rhythm.json` | JSON | 否 | rhythm（每跳衰减+采样） | digest.tact | 30 天滚动 |
| `seeds.jsonl` | JSONL | DPAPI | seeds.pool | digest/闲逛/CLI | 归档保留 |
| `ledger.md` | Markdown | 否 | 用户/心跳留痕/CLI | digest/CLI | 永久（人可读是设计目标） |
| `screen.json` / `screen.jpg` | JSON/JPEG | DPAPI | collectScreen | 按需解锁 | 只留最新 |
| `envpulse.json` | JSON | 否（纯聚合） | collectPulse | gate/观察 | 只留最新（原始流 retention 48h 已接线，流本身 v1.1） |
| `browse.json` | JSON | DPAPI | browse（watch/wander 状态） | 闲逛裁决/CLI | 永久（可焚） |
| `gate.json` | JSON | DPAPI | confirmSend/orchestrator | gate/status | 永久（可焚） |
| `sent.json` | JSON | DPAPI | confirmSend（仅成功投递） | gate（cap/冷却） | 每日滚动 |
| `cursors.json` | JSON | 否（游标） | observeBoundSessions | 同左 | 永久 |
| `tmp/` | 任意 | — | 加解密中间产物 | — | 用毕即焚（burn 清） |
| `exports/` | Markdown | — | `profile export` | 人 | 手动 |
| `logs/heartbeat.jsonl` | JSONL | 否（脱敏审计） | 全链路留痕 | 人/诊断 | 30 天 |
| `logs/rebuild-report.txt` | 文本 | 否 | rebuild（撕裂尾报告） | 人 | 永久 |

## 6. 参数修改指南

| 想改什么 | 位置 | 生效方式 |
|---|---|---|
| 心跳间隔 / 每日表达上限 | **设置页"心跳"卡片**（推荐，写入 settings 命名空间，live 重排定时器）；或 `data/settings/policy.json` 的 `heartbeat.intervalMin` / `gate.maxDailySend`（重启生效） | 卡片即时 / 文件重启 |
| 静默时段、冷却 | `data/settings/policy.json` → `gate.quietHours` / `gate.cooldownMinutes`（用户层 deepMerge 出厂值） | 重启 |
| 闲逛窗口/最短间隔 | `data/settings/policy.json` → `browse.*`（注意 `config/interests.json` 的 `_schedule.windows` 存在时优先于 policy） | 重启 |
| 素材池上限/TTL 阶梯/冷板凳/评分权重 | `policy.json` → `seeds.*`（用户层覆盖对应子键即可，如只覆盖 `seeds.maxActive: 30`） | 重启 |
| 画像合并触发/分区容量/置信度封顶/volatile 14d/stable 180d | `policy.json` → `profile.*` | 重启 |
| **画像能记什么**（隐私边界） | `data/settings/profile-schema.json`：分区/topic/subtopic 白名单 + 各 sub_topic `allowed`/`default` 档位；**白名单外一概不收** | 重启 |
| 追踪哪些 npm/GitHub | `config/watchlist.json`（出厂）；在 `data/settings/watchlist.json` 放同名文件则**整体替换** | 重启 |
| 兴趣种子/闲逛 schedule | `config/interests.json`（出厂）；用户层替换同上 | 重启 |
| 忙闲类别表（哪些进程算忙） | `config/busy-rules.json`（busy/idle 进程映射 + 全屏游戏规则） | 重启 |
| 数据目录位置 | profile 的 `cordis.patch.yml` → `id: heartbeat, config.dataDir`（本机已钉到工作区）；或 env `HEARTBEAT_DATA_DIR` | 重启 |
| 日志保留期 | `policy.json` → `retention.*`（envpulse 流 48h / 决策日志 30 天） | 重启（维护相自动清理） |
| 心跳 agent 用哪个预设 / 是否自动装预设 | profile 的 `cordis.patch.yml` → `id: heartbeat, config.agentPreset`（默认 `heartbeat`）/ `config.installPreset`（默认 `true`） | 重启 |

> 原则（设计红线）：**画像只供给，不自动改配置**——rhythm 显示凌晨活跃也不会替你改 quiet_hours。

## 7. 诊断手册

### 7.1 第一步永远是读审计日志

`data/logs/heartbeat.jsonl`（每行一个 JSON 事件）。事件字典：

| 事件 | 含义 | 关注点 |
|---|---|---|
| `plugin_init` / `orchestrator_started` / `orchestrator_disposed` | 插件装载/定时器启动/卸载 | started 后紧跟 disposed = 效果作用域被立即销毁（effect 契约错误） |
| `beat_start` | 一跳开始 | 没有它 = 定时器没活（看 disposed 是否过早/插件是否加载） |
| `agent_create_start/ok/failed`、`agent_resume_start/ok`、`agent_reuse_live`、`agent_acquire_failed`、`agent_resume_failed` | 专用会话获取三态 + 自愈 | failed 带 error：identity 冲突→应走 resume；while it is live→应走 get；timeout→工厂挂起；resume 失败（正身被删）自动 fallback create（`selfHealed: true`），心跳不死 |
| `home_reset` | `bind remove` 了正身会话 | 正身已重置，下次心跳创建新正身；旧会话从此安静 |
| `phase_done: maintenance/collect/wander` | 各相完成锚点 | 停在哪相，问题在哪相 |
| `silent`（reason） | 沉默判定 | reason：quiet hours / busy window(...) / master actively typing / daily cap / cooldown / no material（⑤a 无素材） |
| `spoke` | 已开口（文本前 80 字） | 应伴随 toast；`delivered` 行 = 绑定会话投递 |
| `deliver_target_live` / `deliver_target_resumed` / `deliver_target_resume_failed` / `deliver_target_released` | 表达轮挑投递目标 | live = 目标会话已有活 agent；resumed = 插件自己拉起来的（**必须带 agentOptions**，C12），其 `model` 字段正常应等于部署默认模型；released = 投递结束已 `dispose` 还回去；resume_failed 时若还有别的目标会继续试 |
| `spoke_failed` | 投递/生成失败 | reason：no heartbeat agent / unparseable / non-Chinese output（整段无中文才拒，见 §7.2）/ confirm 拒绝 |
| `observed` / `observe_error` | 绑定会话观察 | added 条数 / 异常 |
| `wander` / `wander_parse_error` | 闲逛结果 | registered 条数 / 解析失败 |
| `consolidation` / `consolidation_failed` | 画像合并 | applied/rejected 计数 / LLM 输出不可用 |
| `interval_changed` | settings/入口覆盖生效 | 确认卡片保存的值是否落到运行时 |
| `retention` / `BURN_EVENT` | 清理/焚毁 | BURN_EVENT 是焚毁唯一痕迹 |
| `preset_install` | 启动时对齐随包预设 | action：`exists`（已有，一字节没动）/ `created` / `repaired`（幽灵目录被补全）/ `restored`（force 覆盖）/ `skipped-*` / `error`；`skipped-no-root` = roster 里没有 user 根 |
| `rpc_registered` | RPC 路由注册成功 | v1.2.1 起：`route=/api/heartbeat` 出现 = 卡片 RPC 可用；缺失 = 注册失败（C21） |
| `agent_deferred` / `beat_agentless` | 引擎室获取瞬态失败退避重试 | resume 报"owned/迁移未完成"等非 not-found 错误时**不再弃家重建**（2026-09-13 修：旧逻辑曾因启动竞态把引擎室甩到空白会话）；60s×2ⁿ 退避（上限 30 min），成功后复位 |
| `status_written` / `status_write_failed` | M7 状态数据源每跳写入 | scene：`quiet-hours > just-spoke > wandering > busy > present > away`；`data/settings/status.json` 明文（D21 红线：零时间词） |
| `time_injected` | M7 自研时间注入（D20） | 门控 = step===1 且用户发起（末事件 `agent/inbox/spliced`）且距上次 ≥ timeInjectMin；节流状态在 `data/time-inject-state.json`（按会话，重启不丢）；官方 time-context 已停用（用户 patch 移除，D20） |
| `statusbar_track` | 状态栏轨道翻转（M7c，D19） | `system-prompt`（in-history 模型）/ `pre-step`（其余 + 无证据的新会话）/ `off`（开关关闭）；只在翻转时记一条；轨道**钉在轮次起点**（step===1 重钉），中途能力翻转不会劈开同一轮 |
| `interests_updated` | 兴趣/浏览时段卡片编辑（v1.4.0，C22） | `action=add/remove/set-windows`，`detail` 为条目文本或窗口 JSON（截 80 字）；只在成功时记一条，失败原因走 RPC err 回卡片 |
| `screen_vision` | 每跳视觉识别（v1.6.0，C23） | `ok=true/false`；失败带 `error`（ModLens 退出码 + stderr 成 140 字）。识别失败时画面与窗口标题**都不进**反刍提示词（规格②隐私红线） |
| `refill_wander` / `phase_done phase=refill_wander` | 补货闲逛（v1.6.0，spec ⑥） | `focus` + `registered` 条数；触发 = 话题种子 ≤4 且当日补货 <2（本地日，browse.json `refillCount`）；绕过窗口/4h 间隔，保留 focus 3 天冷却 |
| `decision_deferred` | 反刍（decision）轮超时降级（v1.6.0） | 240s whenIdle 超时**不再打成 `beat_error`**（2026-09-19 现场决策轮跑满预算）——记本行 + best-effort `agent.cancel()` 掉孤儿轮次，本跳按沉默处理，素材留下一跳；`reason` 带超时原文 |

### 7.2 症状 → 排查表

| 症状 | 排查顺序 |
|---|---|
| 完全没有心跳（无任何日志行） | ① 插件是否装入：`node_modules/dsh-heartbeat` 存在且 bundle 登记含它；② 启动有无 "Failed to load plugins" 横幅；③ `plugin_init` 缺失 = apply 未跑，看启动报错 |
| 有 `plugin_init` 无 `beat_start` | `orchestrator_started` 后紧跟 `orchestrator_disposed`？= 定时器被立即销毁（effect 返回值契约，见 C2）；或 fiber 被宿主卸载 |
| `agent_create_failed: already owns this identity` | 会话已持久化，应走 resume——确认 dist 是最新（C10 复制安装） |
| `agent_acquire_failed: while it is live` | 会话在 UI 开着（live），应先 `agents.get`——确认三态获取代码在 |
| 一直沉默（`silent: quiet hours`） | 正常（夜间）；白天仍静默看 reason：cap 满（`status` 的摘要）/ 冷却未过 / 忙时窗口 |
| 开口了但没通知 | `spoke` 行存在则 toast 环节查 `notify check`；通知只提示不承载正文（D12） |
| 通知出现但会话里是沉默 | 沉默误判为开口（r5 修过：标记任意位置匹配 + 中文兜底闸）；确认 dist 已同步最新 |
| `spoke_failed: unparseable / non-Chinese` | 模型输出不合契约；`turn_extraction_empty` 事件会带事件窗口形态（升级宿主后重点复查 C5） |
| 画像不增长 | `profile verify` 看 journal 一致性；inbox 是否有积压（`shouldConsolidate` 触发条件）；schema 白名单是否太紧 |
| 怀疑画像文件损坏 | `profile verify`（只报不修）→ `profile rebuild --check`（看 diff）→ `profile rebuild`（真重建） |
| 设置页整块没有心跳区块（host 照常跑、数据照常写） | client 模块被**静默剔除**：`package.json.name` ≠ `cordis.patch.yml` insert 的 `name` ≠ `client.js` 的注册 id（C15）；三处统一为包名后**重启**（C16） |
| 每跳 `beat_error: Cannot read properties of undefined (reading 'length')` | 宿主移除了 `Session.events`（0.1.2-rc.1）→ 改走 `snapshotEvents()/seq`（C5/C14）；确认 dist 已同步（C10） |
| 每轮 prompt 组装抛 `prompt variable "{{model}}" has no value …(section "deployment:persona")` | agent 没有模型路由（C12）：审计 `agent_create_start` / `agent_resume_ok` 会打 `model` 字段，出现 `(none)` 即确诊 |
| 闲逛相 0.4 秒结束、永远返回 `{"items":[]}`，`tool_policy` 报 `unknown global tool "web_search"` | agent 没加入预设（裸 agent，C13）：先 `node dist/cli/index.js preset status`（看 installed/是否与模板一致）；不一致或缺失就 `preset install`（手改过想还原加 `--force`，C18）；再看 `tool_policy` 行是否为 `preset=mounted(...) restrict=ok` |
| 素材投递偶尔 `spoke_failed: non-Chinese output discarded`（尤其目标 agent 收到素材包后爱调工具时） | **根因（2026-09-16 修）**：`agentTurn` 从目标会话事件倒序取最后一个非空 assistant 文本，`assistantText` 拼接了所有 text 段；voiceAgent 回合以工具调用收尾时，末行是 `</tool_calls>`（纯 ASCII），⑤b 旧逻辑取最后一行 + 中文兜底闸就把它判成“非中文”丢弃——**不是投递坏了，是取末行没跳过工具收尾标签**。已修：`spokenLines` 过滤工具收尾标签行（`/^<\/?tool_calls?>$/i`），再取最后一个含中文的行（`cnLine`），兜底用最后一行；non-Chinese 闸放宽为**整段无中文才拒**。确认 dist 已同步（C10）并重启 |
| **投递会话里自己冒出** `prompt variable "{{model}}" has no value`（引擎室侧反而安静） | 看同一时刻的 `deliver_target_resumed`：`model` 为 `(none)` = 插件 resume 投递目标时没带 `agentOptions`（C12）；同一跳还会有 `turn_extraction_empty label=expression turnError=…` 与 `spoke_failed: non-Chinese output discarded`（空文本被兜底闸拦下，别被这句误导）。确认 dist 已同步（C10） |
| `preset_install` 报 `action:"error"` + `bundled template not found next to the plugin` | 部署副本里没有 `assets/presets/`（`pnpm add file:` 的拷贝发生在模板加入包之前，或发布时漏了 `files`）：把 `assets/presets/heartbeat/` 补进插件的 `assets/`，或重装插件 |
| `preset_install` 报 `skipped-no-root` / `agent-preset/not-found` | 用户预设根不在 roster（`$DSH_HOME` 被改过？）或 id 不在 `[a-z0-9][a-z0-9-]*`；`skipped-custom-id` = `agentPreset` 不是 `heartbeat`（插件不替你造自定义预设，请自行放好同名目录） |
| `spoke_failed: unparseable decision output`（附 `SyntaxError: Unexpected non-whitespace character after JSON at position N`） | 模型输出里的 reasoning 块混进了正文（C14）；确认 `assistantText()` 排除了 reasoning 块、`parseJsonBlock()` 取第一个可解析对象 |
| 有 `spoke` 但没有 `delivered`，话只说在引擎室 | 投递目标当时没有活 agent → 看 `deliver_target_live/resumed/resume_failed`；全部拉不起来会留 `spoke_fallback`；再查 `bindings.json` 里目标的 `deliver` 是否为 true |
| 表达轮 `beat_error: Error: expression: whenIdle timeout` | 目标会话当时在跑别的轮次；表达轮等待上限 10 分钟，超时只记 `spoke_deferred`（那句话留到下一跳），不再让整跳失败 |
| **侧栏某个会话行消失了**（会话内容还在，刷新就回来） | 心跳刚往那个"当时没打开"的会话投递过：审计会有 `deliver_target_resumed` + `delivered` + `deliver_target_released`。释放 agent → 宿主 `session/disposed` → `api-session/removed` → 前端删行（§12 第 9 条）。**不是会话损坏，刷新页面即回**；若伴随会话内容异常，才去查 §13 的会话修复工具 |
| 升级 0.1.5 后某个旧会话打不开，报 `session header version must be 3` 或 `…v0-to-v1 refuses this format v0 Session: … unexpected member "tier"` | 前者 = 该会话还没被迁移（正常情况宿主首次访问时自动迁移）；后者 = v0 产物里有翻译器不认的成员（C20）：`node scripts/repair-v0-members.mjs`（预检）→ `… fix`（备份+修复，§13.1）。修复失败的事件不要手改文件，把输出发给维护者 |
| 升级 0.1.5 后审计 `turn_extraction_empty` 的 `turnError` 字段消失 | 失败尝试的事件形态变了（C19：`assistant/chunk` → `assistant/attempt`）；v1.2 起 `terminalTurnError()` 两种都扫，出现此症状说明 dist 未同步（C10） |
| 升级 0.1.5 后设置卡片所有 RPC 分区报 `加载失败: … HTTP 405`（心跳本身照常跑） | RPC 通道没注册成功（C21）：0.1.5 严格解析下自定义通道 `rpc.handle` 内部读不到 webServer，**自定义通道方案整体退役**，v1.2 起改走 `/api` 精确路由。审计出现 `rpc_registered route=/api/heartbeat` 才算注册成功；没有即确认 dist 已同步（C10）并重启 |

### 7.3 诊断 CLI 速查

```
node dist/cli/index.js status            # 工作区 + 策略摘要（含今日 cap/冷却/静默窗概要）
node dist/cli/index.js seeds stats|list [--archived] | gc
node dist/cli/index.js ledger list --pending
node dist/cli/index.js browse status|dry # 闲逛裁决链路
node dist/cli/index.js profile verify    # journal 重放比对（只报不修）
node dist/cli/index.js profile rebuild --check
node dist/cli/index.js profile export    # 解密导出 Markdown 供人审
node dist/cli/index.js logs cleanup --dry-run
node dist/cli/index.js sessions list     # 枚举会话 id（绑定用）
node dist/cli/index.js preset status     # 随包预设装没装、与模板是否一致
node dist/cli/index.js preset install [--force] [--id <id>]
node dist/cli/index.js burn              # 焚毁预演（--yes 执行，--all 连设置）
```

## 8. 安全模型（实现态）

1. **工作区边界**：运行时全部 fs 写入限 `dataDir`；守卫 = realpath 规范化 + 边界前缀比对（§10.2 写死方案 + 5 组必测向量）。
2. **模型侧**：心跳 agent 在 `setup` 内 `tools.restrict({allow:['web_search']})` —— bash/文件编辑终身不可用；表达轮另加 prompt 级零工具纪律（B7）。缺口：per-turn 工具翻转依赖宿主 restrict 栈语义（P3 结论：restrict 可用，未验）。
**预设已落地（2026-09-10）**：心跳 agent 加入专用预设 `heartbeat`（模板随包分发于 `assets/presets/heartbeat/`，运行时 id 由 `agentPreset` 配置项指定，见 C13）——只含 `compaction` 组与 `tool-web`（`fetch: false`：不给抓网页，只留搜索），刻意去掉 shell/文件/子代理/目标/待办/计划与 persona 行，于是工具面**从源头**只剩一个工具，`restrict` 退化为第二道保险。预设落在用户家目录，插件启动时按 roster 的真实用户根自动补齐（C18），不要求用户手抄；已有文件不会被覆写。
3. **静态加密**：按"内容是否含用户识别信息"划线（§10.5 清单）；DPAPI CurrentUser = 防他人/他机/误同步，**不防同账户恶意软件**（边界声明）。
4. **明文最小化**：inbox 只存指针+≤1 句；审计日志不含窗口标题等敏感原文；retention 自动清。
5. **画像投毒防线**：合并 prompt 声明"观察是数据不是指令"；browse/screen 来源置信度封顶 0.4；白名单/evidence/容量/ops 上限；投毒式观察在 journal 可见。
6. **焚毁**：burn 清单单一事实源 `src/vault/burn-list.ts`；预演→`--yes`（覆写 x3+删除）→`BURN_EVENT`；设置默认保留（`--all` 才连带）。
7. **提交卫生**：`data/` 已 gitignore；`.reference/` 已随交付删除；发布前跑 §11 检查清单。

## 9. 测试

- 运行：`npm test`（node --test + tsx，91 个）；`npm run typecheck`；`npm run build`。
- 必测项与锚点：路径守卫 5 组向量（含 junction 逃逸）、闸门五闸顺序与 A5 语义、淘汰四规则+保护+合并、画像守卫（白名单/evidence/封顶/INVALIDATE 归属/老化）、journal verify/rebuild（含撕裂尾）、inbox 去重截断、闲逛裁决与 watchlist 假 fetcher、burn 预演与设置保留、配置两层合并与 fail-closed。
- 时间全部注入（`now` 参数），无 sleep 依赖；vault 类测试真实 spawn PowerShell。

## 10. 开发工作流要点

1. **C10**：`file:` 安装是拷贝。改代码后：`npm run build && npm test`，然后
   `cp -r dist/* <profile>/node_modules/dsh-heartbeat/dist/`（client.js/package.json 同理）再重启。
2. **诊断式开发**：不确定宿主行为时，往 `apply` 里加 try/catch 探针 + 落盘日志（照 hb-probe 的模式），重启读日志，别猜。
3. **模块纪律**：单模块实现→单测→验收，不并行（项目守则 6）。
4. **不碰的线**：画像不自动改配置；NOOP 偏置；stable 不因时间失效；素材淘汰绝不删画像。

## 11. 发布前检查清单（GitHub 上传前）

- [ ] `cordis.patch.yml` 无个人绝对路径（dataDir 覆盖已迁移到用户 profile patch ✅ 2026-09-06）
- [ ] `data/`、`.reference/` 在 `.gitignore` 且目录不存在于提交
- [ ] 全库搜索无个人称呼/机器路径（开发机绝对路径、私人称呼等；设计文档如公开需先脱敏或排除）
- [ ] `npm run build && npm test` 全绿；`dist` 为最新
- [ ] README 安装命令与实际 exports/files 一致
- [ ] `assets/presets/heartbeat/` 模板与用户家目录副本一致（`node dist/cli/index.js preset status` 应报 `matches the bundled template`）

## 12. 已知限制与 v1.1 方向

1. 表达轮工具为"预设收窄（只有 web_search + compaction）+ prompt 纪律 + agent 级 restrict 白名单"三重；per-turn 翻转仍未做（宿主 restrict 栈语义未验），当前也不需要；
2. 绑定管理已上 UI（§14 M6 RPC：会话绑定分区，list/add/remove）；~~CLI 兜底也可用~~（保留 CLI 供脚本场景）；
3. `logs/envpulse.jsonl` 原始脉冲流 ✅ 已落地（2026-09-06：collectPulse 每拍追加 `{event:'pulse',...}`，维护相按 envPulseHours 剪枝；纯聚合统计、明文，无窗口标题/进程名）；v1.1 可选：流内加围绕聚合的派生字段；
4. 会话标题未设置（DSH 自动命名；可用 dsh-session-title 服务给心跳会话定名——该服务为 LLM provider 自动命名机制，心跳 agent 会话不适用，未做；卡片读取标题的位置已随 0.1.2 迁移，见 C17）；
5. **预设是外部依赖（已大幅缓解）**：`<dshHome>/.agent-presets/<agentPreset>/` 不在插件包内（家目录属用户），删掉后心跳 agent 会退回裸 agent——表现为闲逛相永远空手而归、`tool_policy` 行没有 `preset=mounted`。v1.1 起插件会**在启动时自动补齐**该目录（C18；只补缺失，不动已有文件），所以这条从"必须手抄的安装步骤"降级为"删了会在下次启动自己回来"；仍未做的：把用户改过的旧模板自动升到新模板（会覆盖用户意图，故意不做，需要时用 `preset install --force`）；
6. 自研时间注入（P1 ①）未启用——官方 time-context 仍在服务日常会话；启用时必须停用官方（B9 护栏）；
7. journal 快照基点（按年分片）v1.5；`profile.mjs sync`（comm→长期记忆单向同步）默认不做；
8. DSH 升级：按 §3 契约表逐条复查（C2/C4/C5/C8/C9 历史上最易变）。2026-09-06 已核对 0.1.2-rc.1 兼容矩阵：12/14 第三方插件 peer 内置兼容；heartbeat peer 由精确 `0.1.1-rc.2` 放宽为 `^0.1.1-rc.2`（本次提交）；exa 官方插件需随升 0.1.2-rc.1。**2026-09-10 实际升级后补记**：本次真实踩中五处（`Session.events` 移除 / `agentOptions` 默认丢失 / 裸 agent 无预设 / client 注册 id 必须等于包名 / 会话标题迁到 per-record），全部沉淀为 C12–C17。教训：升级后先看两类审计行——`tool_policy`（工具面是否仍完整）与 `beat_error`（是否有结构性抛错），它们比"看 UI 有没有动静"更快定位。**2026-09-11 针对 0.1.5-rc.2 的核对**（npm 包逐包源码对比，实机验证待宿主升级后补记）：C1–C18 全部存活（含 v1.1 的模型路由/预设/client id 三修）；新变化两处——`assistant/chunk` → `assistant/attempt`（C19，仅影响诊断辅助路径）与持久层重构 + 会话格式 v3 自动迁移（C20，动用户数据，升级前必备份 `~/.dsh/sessions`）；peer 放宽为 `^0.1.1-rc.2 || ^0.1.5-rc.2`。
9. **投递后释放 agent 会让侧栏那一行暂时消失（已知副作用，2026-09-10 评估后决定保留）**：投递进"当时没有活 agent"的会话时，插件 resume 一个 agent、投完 `dispose()`（审计 `deliver_target_released`）→ 宿主 `session/disposed` → `ctx.emit("api-session/removed", session.id)`（`@deepseek-ai/dsh-api-session-controller/lib/index.js:2617-2618`）→ 前端 `ctx.remote.$on("api-session/removed", …) → sessions.handleSessionRemoved(sessionId)`（同包 `lib/client.js:2728-2730`）→ **侧栏移除该行；会话本体在持久化里，刷新页面即回**（前端重连后重新 list）。只影响当时没打开的会话（打开着的走 `deliver_target_live`，不碰）。曾评估的三个替代方案：①不释放、插件持有 handle（社区 `GengDaPeng/dsh-agent-message` 的做法）——但宿主 `createOrAdopt` 的 `const live = this.ctx.agents.get(sessionId); … if (live !== void 0) return live;`（`.../lib/index.js:406-408`）会**收养**这个 agent，而插件 resume 时给的 `setup` 复刻不了宿主 `composeAgent`（`.../lib/index.js:350-363` = `installSelection(agentCtx)` + `presets.mount(agentCtx, resolvedId)`）→ 那个真实会话会跑在缺预设/缺模型选择投影的半成品 agent 上（先例：2026-09-10 12:51 `deliver_target_live` 即一次收养，当场死于 `{{model}}`）；②只在目标会话已 live 时投递——心跳说话机会显著变少；③延迟释放——`removed` 只是晚到，不解决问题。用户拍板："都不能根治，就保持现状吧"，代价 = 需要时刷新一次页面。

## 13. 会话修复工具（scripts/repair-session.mjs）

故障特征：会话加载报 `SessionPersistenceCorruptionError: session event at seq N lacks an identified message`。
根因（r5 已修）：投递/注入曾使用手写消息对象（缺 message id）写入会话事件流；现所有消息一律经宿主
`createUserMessage` 严格工厂（orchestrator.hostUserMessage），工厂不可用即放弃投递并留痕。

修复流程：
1. **先关闭 DSH**（避免 flush 覆盖修复结果）；
2. `node scripts/repair-session.mjs inspect "C:/Users/<user>/.dsh/sessions/<slug>/<sessionId>"` —— 只读扫描；
3. `node scripts/repair-session.mjs fix <session-dir>` —— 自动备份 `.bak-<ts>` 后补 id（crypto.randomUUID）；
4. 复验 inspect 应为 0；重启 DSH 重开会话。

技术备忘：会话存储为**多帧 zstd**（宿主每次 flush 追加一帧）——`zstdDecompressSync` 只解第一帧，
必须按 magic（28 B5 2F FD）切帧逐帧解压再拼接（脚本已实现，含假切分自动合并）。损坏特征扫描必须
用精确签名（plugin 来源 + 顶层缺 id）——宿主自己的 assistant 推理事件（`message.reasoning`）天然没有
顶层 id，宽松匹配会误报上千条。

### 13.1 v0 成员修复工具（scripts/repair-v0-members.mjs，2026-09-12 新增）

**故障特征（0.1.5-rc.2 升级现场）**：升级宿主后旧会话打不开，报
`failed to observe session "<id>": …dsh-session-format-v0-to-v1 refuses this format v0 Session: compaction/summary <seq> data has unexpected member "tier"`。
根因：0.1.2 时代的 compaction 在 `compaction/summary` 事件里写过 v0→v1 翻译器白名单外的成员
（`tier`/`topic`/`directMessageIds`/`effectiveMessageIds`/`kernelBlockId`）；另有一种 r5 旧投递残留
（`agent/inbox/spliced` 的 inserted 消息缺 `id`）。扫描全部会话定位违规事件、剥多余成员/补 id、
帧保持式回写（首帧不变量与无关帧字节原样）、逐文件备份 `.bak-pre-v0fix-<ts>`、修完用宿主同款
翻译器复核。翻译器直接解析自全局 dsh 安装（`<npm-global>/node_modules/@deepseek-ai/dsh/node_modules/`），
零额外安装。**预检模式默认只读**；只碰 `header.version === 0` 的 v0 产物，已迁移的 v1+ 代文件不碰。
2026-09-12 实战战绩：5 会话 65 事件，修复后全部会话正常打开并完成 v3 迁移。

## 14. M6 拓展：RPC 数据通道与设置页卡片

**通道**：宿主 `src/rpc.ts` 经 `ctx.inject(['connection'], ...)` 注册 `/heartbeat` 通道（connection 为晚挂载服务，必须声明式等待——直接属性访问会报 without inject）；浏览器 `ctx.get('connection').rpc.call('/heartbeat', endpoint, payload)` 调用，返回 `{ok,value}|{ok:false,error}`。

**端点**：`status`（状态卡片）/ `sessions.list`（持久化会话+title+live+绑定标记）/ `bindings.get|add|remove`（正身 add 拒绝、remove 触发 home_reset）/ `seeds.list|archive|restore|delete` / `profile.digest` / `profile.export` / `ledger.open`（宿主拉起编辑器）。全部处理器 try/catch，异常返回结构化错误。

**会话名**：宿主读**每会话一条**的投影缓存 `~/.dsh/storages/session_projcache/sessions/<sessionId>.json`，取 `rows.title.val`（0.1.2 起的布局，见 C17）；非 `session-` 前缀的记录（子代理会话）跳过；旧的单文件聚合 `session_projcache.json` 只作兼容回退。client 端不自行解析。

**安全**：通道 authority 'trusted-host'；全部端点经路径守卫 + 既有模块执行；浏览器端无状态、无文件访问。

**client 卡片**：七个分区（状态默认展开/会话绑定/素材池/**兴趣范围**/画像只读/账本/节律配置），`<details>` 折叠；状态 30s 轮询；素材池删除与兴趣删除二次确认；所有 RPC 异常按分区独立显示。**会话绑定分区**每行两个独立开关（`☑投递 ☐观察`，可同时开、可逐个切换）+ 解绑；未绑定行提供「绑定投递 / 绑定观察 / 投递+观察」三个入口（旧版只有一个按钮、绑了投递就再也点不到观察，2026-09-10 修）。**兴趣范围分区**（v1.4.0）：兴趣列表逐条删除（二次确认）+ 输入框回车添加 + 浏览时段（`<input type=time>` 起止、加/移除行、保存全量写回，C22）。

## 15. 变更日志

> 版本口径：v1.6 是**当前版本**（DSH ≥ 0.1.2-rc.1；状态栏/时间注入/视觉识别在 0.1.5-rc.2 上验收，0.1.2 上状态栏走 Track B、视觉静默降级）。旧宿主（≤ 0.1.1-rc.2）请用 v1.0。

### v1.6.0 · 2026-09-19（素材闭环 + 视觉识别 + 0.1.5 settings 适配）

需求侧见《心跳素材闭环 · 改造说明书》（SPEC，2026-09-18 定稿，D22 后续）。闭环 = 截图→视觉识别→引擎室总结→投递→聊天→observe 沉淀→consolidation 生成聊天种子→素材池→反刍投递：

- **素材池品类化（spec ⑤④）**：`Seed.category: topic|chat`（与 source 解耦；loadPool 宽松容错，旧行默认 topic）；分池上限 话题 16 / 聊天 14（品类满只在自己池内按现有 evictionScore 淘汰）；聊天种子 used 上限 **1**（话题仍按 policy 2）。
- **反刍候选组包代码化（spec ③）**：`assembleCandidates` 话题随机 4 + 聊天按 lastEvidenceAt 最新取 2 + 双向互补，封顶 6 条给反刍 agent 挑 ≤3；候选全空直接 silent（省一次模型调用）。
- **consolidation 产聊天种子（spec ⑧）**：引擎室从观察对话自主挑"值得聊的话题"输出 `CHAT_SEED` op（在画像管线前分流，不污染 ProfileOp/journal），单次 ≤3 条写入素材池 category=chat、按 topic 自动合并；审计 `consolidation` 加 `chatSeeds` 计数。规则同步进引擎室人设卡。
- **补货闲逛（spec ⑥⑦）**：话题种子 ≤4 触发，绕过浏览窗口与 4h 间隔（独立触发、可与正常闲逛同跳叠加），保留 focus 3 天冷却，每本地日至多 2 次（browse.json `refillCount`）；闲逛搜索次数 3→**3~9**。
- **视觉识别 + "我在干嘛"（spec ①②，C23）**：截图改全屏原图（修"降采样被误判全屏游戏"）；每跳经 ModLens CLI（`-p` 钉死 provider）识别画面，成功时反刍提示词带画面描述+任务栏标题、引擎室输出 `doing` 一句随每次投递携带；**识别失败则画面、标题、doing 三者全无**（隐私红线）。
- **0.1.5 settings 适配（C8，重要修复）**：dsh-settings 0.1.5 删除自由函数 `installSettingsSection` → 宿主 `settings` 服务的 `installSection` 方法 + 模块 inject 声明 `'settings'`（新旧 API 特性探测并存）；并把该包挪回 dependencies（v1.5.1 误挪 peer 导致 profile 实体包被清 → **节律配置"保存不生效 + 重启回默认"**）。
- **UI**：状态卡新增插件版本行；`status` 端点带 `version`。
- 测试 163 条全绿（新增 24：品类/上限/组包/聊天种子/补货/视觉桥/doing 隐私语义）。

### v1.5.0 · 2026-09-16（反刍/投递改版 + 表达提取健壮化）

反刍与投递的决策权从引擎室移交给目标会话的 agent（voiceAgent），引擎室只备料 + 跑闸门（D23 保持 `{speak,text,seed_ids}` JSON 结构不变）：

- **⑤a 引擎室反刍备料**：`buildRuminationPrompt` 从 activeSeeds 挑 ≤3 条，各压缩成一句（不带理由不排序），输出机器 JSON `{speak,text,seed_ids}`；无素材 → silent `no material`。
- **⑤b 素材包三段式投递**：`buildMaterialPrompt` 拼成 ①声明『这是心跳插件素材投递…』＋②3 条素材＋③（3 条里 ≥2 条 used≥1 时）『也可以说一句真心话』，注入投递目标会话的 voiceAgent，由它判断说不说/说哪条/说真心话。处境不进包；敏感度靠阅后即焚。
- **归账 attributionIds**（§4.1）：seed_ids 优先 + ≥8 字符包含匹配兜底；retireAfterUsed=2 且 lastEvidenceAt≤lastUsedAt 才归档消费。
- **表达提取健壮化**：`agentTurn` 取文本倒序扫最后一个非空 assistant 文本，`assistantText` 拼接所有 text 段；目标 agent 回合以工具调用收尾时末行是 `</tool_calls>`（纯 ASCII），旧逻辑取最后一行被 non-Chinese 闸误拦。已修：过滤 `/^<\/?tool_calls?>$/i` 标签行 + 取最后一个含中文的行（`cnLine`），non-Chinese 闸放宽为**整段无中文才拒**。
- 新增 `src/core/material.ts`（buildRuminationPrompt / buildMaterialPrompt / attributionIds / wantHonestOption）+ tests/material.test.ts（9 条，全绿）。

### v1.4.0 · 2026-09-13（兴趣范围 / 浏览时段卡片管理）

需求侧见 设计要求.md r8（D22、§9 第 10 条）。闲逛搜索的焦点清单（原 `config/interests.json` 手编 14 条）与浏览时段窗口搬到 UI 卡片：

- **权威文件不变，编辑入口上移**：`browse.ts loadInterests` 语义不动（用户层整体取代出厂层）；新增 `src/browse/interests-edit.ts` 独占编辑逻辑——**首次成功变更把出厂文件完整复制进用户层**（D22 首编继承），之后卡片即唯一入口，出厂兴趣与排程零丢失；读取与校验失败只读、不建层（看一眼卡片不会接管出厂配置）。
- **校验**：兴趣 trim+折叠空白 / ≤60 字 / 大小写不敏感去重 / ≤32 条；窗口 HH:MM / 同日起始<结束 / 1–6 个 / 两两不重叠（裁判取第一个命中窗口）。`_comment` 等手工注释键保存时保留。
- **RPC**：`interests.list / add / remove / setWindows` 四端点（走 C21 /api 路由）；成功编辑记审计 `interests_updated`。
- **UI**：卡片新增「兴趣范围」分区（列表逐条删除二次确认 + 输入框添加 + 时段 `type=time` 起止编辑、加行/移除行、全量保存）；时段草稿只在首次加载填充，保存失败不清空用户输入。
- 测试 8 条（tests/interests-edit.test.ts）：首编继承 / 去重与长度 / 上限 32 / 删除与 not-found 不建层 / 窗口校验矩阵 / `_schedule` 兄弟键保留。

### v1.3.1 · 2026-09-13（评审三项修正）

- **能力探测改增量尾扫**（评审 #1）：缓存键从"日志长度"（每步增长→每步失效→每步全量回扫）改为扫描水位线，新事件用 `snapshotEvents(fromSeq)` 只读尾部；长会话每步的成本从 O(全部事件) 降为 O(新增事件)；
- **轮次起源探测健壮化**（评审 #2）：不再依赖"末事件必须是 `agent/inbox/spliced`"（其他插件在轮次间写事件会静默失效），改为回扫比较"最近一次 splice vs 最近一次 turn/end"——对任意交错事件稳定。已知语义：投递 followup 也算 inbox 起源（同样受节流，先例可接受）；
- **Track A section 只渲染 scene**（评审 #3）：note 是引擎室自由文本，若每跳变化会把宿主"逐字节相同零提交"的红利吐回去——note 只进 UI 与 Track B 状态行，section 走常量映射（渲染纯性红线补注）。

### v1.3.0 · 2026-09-13（M7 状态栏与自研时间注入）

需求侧见 设计要求.md r7（§17，D19–D21）。实现要点：

- **状态数据源**（statusbar/store）：引擎室每跳派生场景（`quiet-hours > just-spoke > wandering > busy > present > away`，信号 = 静默窗/本跳开口/本跳闲逛/envpulse presence）写 `data/settings/status.json`（明文，D21 零时间词）；`StatusReader` mtime 缓存供注入轨热路径。
- **自研时间注入**（statusbar/time-inject，D20）：pre-step 门控（step===1 且用户发起）+ 25 min 默认节流（`timeInjectMin`，UI 可调，0=关闭）+ 精确时间/elapsed；节流状态 `data/time-inject-state.json` 按会话持久。**官方 time-context 停用**（用户 patch 移除 insert，B9 由 D20 取代）。
- **两轨状态注入**（statusbar/track，D19）：`in-history` 模型（读 `request/context` 的 `systemPromptUpdate`，缓存按事件数重判）走 `heartbeat:status` 系统 section（order 5000，空文本自动丢弃）；其余模型在 pre-step 时间消息尾追加状态行。**轨道钉在轮次起点**（step===1 重钉，两轨读同一钉；评审 #5），渲染纯性红线（评审 #2：宿主对逐字节相同文本零提交，渲染层禁高频字段）。
- **自愈保守化**：引擎室 resume 失败仅在确认"会话不存在"时才重建，其余瞬态错误（启动竞态 `SessionAlreadyOwnedError` 等）退避重试——2026-09-13 竞态曾把引擎室甩到空白会话，已修。
- **UI**：节律配置加"时间注入间隔（分钟，0=关闭）"与"状态栏"开关；状态分区加"心跳此刻：…"与时间注入行；RPC `status` 端点扩 `statusbar` 块。

### v1.2.1 · 2026-09-12（卡片 RPC 405 修复）

0.1.5 的 cordis 严格服务解析下**自定义 `rpc.handle` 通道整体不可用**（Service 把 this.ctx 钉在提供方上下文，内部 `owner.webServer.register` 必然无许可，调用方无法自救，C21）。RPC 迁移为 `/api` 精确 Fetch 路由（`connection.fetch.register`，两代宿主通用），客户端改 `rpc.call('/api', 'heartbeat', {endpoint, …})`；新增 `rpc_registered` 审计行。

### v1.2.0 · 2026-09-11（适配 DSH 0.1.5-rc.2）

C19（`assistant/chunk` → `assistant/attempt` 诊断兼容）+ C20（持久层重构/会话格式 v3 迁移）+ peer 放宽 `^0.1.1-rc.2 || ^0.1.5-rc.2`；新增 `scripts/repair-v0-members.mjs`（迁移被拒修复，实战 5 会话 65 事件）。

### v1.1 · 2026-09-10（DSH 0.1.1-rc.2 → 0.1.2-rc.1 适配）

**兼容性（宿主 0.1.1-rc.2 → 0.1.2-rc.1）**

| 宿主变化 | 症状（审计/UI 上看到的） | 处理 |
|---|---|---|
| `Session.events` 移除 | 每跳 `beat_error` / `consolidation_failed`：`TypeError: Cannot read properties of undefined (reading 'length')`；数据面照写，只是每跳都死 | `sessionEvents()` / `sessionEventCount()`：优先 `snapshotEvents()`，缺失才回退 `events`（C5/C14） |
| `agents.create/resume` 不再代填部署默认模型 | `turn_extraction_empty turnError=… prompt variable "{{model}}" has no value for this assembly (section "deployment:persona")`，所有轮次（含决策）在起点抛 | `defaultAgentOptions(ctx)` 读 `agentDefaultModel.currentSelection()` 显式传 `agentOptions`（C12） |
| 未加入预设的 agent = 空全局层 | `tool_policy` 报 `names unknown global tool "web_search"`；闲逛相 0.4s 返回 `{"items":[]}` | `setup` 里 `agentPresets.mount(agentCtx, agentPreset)`；随包提供 `assets/presets/heartbeat/`，**启动时自动装到用户预设根**（C13/C18，§8 第 2 条） |
| client 模块注册 id 必须严格等于包名 | 设置页心跳区块**整块消失**，host 侧毫无异常 | `client.js` 注册 id 与 `cordis.patch.yml` insert `name` 统一为 `@kanadego/dsh-heartbeat`（C15） |
| 会话标题迁到 per-record 投影缓存 | 卡片把会话显示成 `session-c9ba6998…` 而不是会话名 | 读 `session_projcache/sessions/<id>.json` 的 `rows.title.val`，旧聚合仅作回退（C17、§14） |

**功能改进**
- **开口倾向**：决策相从"沉默是常态"改为"分寸优先"——默认倾向开口，只在"素材都用过、确实没新话可说 / 距上次开口太近 / 他显然在忙 / 已到深夜"时才沉默；提示词带上"今天已开口 N 次（上限 M）、上次开口是 X 分钟前"，当天一次都没说过时明确要求挑一句说（素材来源仍是真实来处，闸门与审计不变）。
- **投递文本收敛**：正文改为一句话的舞台提示，不再向会话里投"心跳投递/引擎室"这类机器细节（来源仍在 `source` 元数据里，轨迹视图标 `plugin: heartbeat`）——9/6 实测这类脚手架会被投递目标自己读一遍并分推理去解读。
- **投递目标自动拉活**：目标会话在本进程没有活 agent（重启后未被打开）时按需 `agents.resume`，不再默默回落到引擎室（失败留 `spoke_fallback`）。
- **会话绑定双开**：见 §14 末段。
- **审计细化**：新增 `deliver_target_live` / `deliver_target_resumed` / `deliver_target_resume_failed` / `deliver_target_released` / `spoke_fallback` / `spoke_deferred` / `preset_install`；`turn_extraction_empty` 增 `turnError`；`tool_policy` 增加 `preset=` 与改名后的 `visibleGlobal=`（§7.1/§7.2 已同步）。
- **表达轮超时语义**：等待投递目标空闲从沿用通用上限改为 10 分钟，超时记 `spoke_deferred` 并把这句话留给下一跳，不再整跳 `beat_error`。
- **预设自动安装**（C18）：安装从"add 插件 + 手工复制两个文件到家目录"变成**一条 `dsh plugin add`**——启动时按 roster 的真实用户预设根补齐模板，**已有 composition 永不覆写**（手改过的自定义预设安全），审计打 `preset_install`；新增 CLI `preset status` / `preset install [--force]` 供人工检查与修复。

**Bug 修复**
- reasoning 块被当作正文拼接 → JSON 解析崩（`SyntaxError: Unexpected non-whitespace character after JSON at position N`）：`assistantText()` 排除 reasoning 块，`parseJsonBlock()` 枚举括号候选取第一个可解析对象，`profile/consolidate.ts` 的 `parseOps()` 同步容错化（C14）。
- 工具策略自愈逻辑从报错文本里用 `/search/i` 猜工具名，猜中 ACP 的 `search_context`（搜对话块）并**成功生效**，把 agent 掩蔽到只剩一个无用工具：该回退已删除，`restrict` 失败只如实记录。
- `tools.schemas()` 不带 scope 得到的是全局视图，不能作为预设是否挂上的判据（判据是 `restrict=ok`）——审计字段随之更名。
- **投递目标的 resume 没带模型路由**：用户的投递会话里自己冒出 `prompt variable "{{model}}" has no value for this assembly (section "deployment:persona")`，而插件只是记了一句 `spoke_failed: non-Chinese output discarded`（空文本被兜底闸拦下）——现象在用户的会话里，根因在插件：`acquireTargetAgent` 漏传 `agentOptions`（审计 `deliver_target_resumed model="(none)"`），宿主又把这个没有模型路由的 agent 当成该会话的 live agent 复用（C12）。修法：照抄宿主 `agentOptions()`，投递结束再 `handle.dispose()`（`deliver_target_released`）。