前言¶
在 DSH 里跑长任务时，常见问题是：主会话把工作区选错、方案没真正落盘，或者工具连续失败、TODO 清单多轮不动却无人提醒。单靠主脑自己纠偏，往往需要人盯着日志。dsh-observer（npm 包名 @corvus-dsh/dsh-observer）是 corvus-dsh 维护的星火 OS 组件之一，定位为副脑：与主会话指针共转、不会被切片；负责孵化主脑、只读监听事件流，并在停滞或失败时投递有限次的纠偏提示，在合适时机后台调用记忆提炼。写路径自 v1.9.0 起经 dsh-paradise 统一完成，缺层时会拒绝孵化并给出明确错误，而不是静默跳过。
这是什么¶
一句话：dsh-observer 是挂在主会话旁的伴生会话插件，通过 DSH 插件机制接入宿主，依赖同系的 dsh-paradise 作为彼岸层协议（孵化与读写的关键路径）。
维护者与源码：corvus-dsh/dsh-observer（MIT）。目录页：skillhub.cn 条目。
核心能力（以 README 与 package 描述为准）¶
孵化主脑¶
孵化流程对应彼岸层 API：paradise.session.create(items) 创建会话内容，paradise.session.trigger 点火；回滚为 paradise.deleteSession。创建时支持 items?（顺序写入宿主上内容须在创建时放置）与 inheritFrom?（继承主脑的 provider/model/preset 等运行时旋钮）。工作区 cwd 须为绝对路径且可解析，否则拒绝创建（CWD_REQUIRED 等），避免「选择工作区」孤儿页。
v1.3.0 起采用与 dsh-graft-slice 同系的冷 tape 物理注入，而非仅靠 sessionController.create() 再 append()（后者在本宿主上因 step-scoped 消息等问题走不通）。
v1.7.0 起：监理（supervisor）¶
孵化之后副脑不休眠，只读监听主脑事件流：
| 触发 | 条件 | 动作 |
|---|---|---|
| 连续失败 | 同一工具连续 3 次失败 | 一条 steer 纠偏，建议 memory_search 或换方案 |
| 停滞 | 连续 5 个 turn/end 且 TODO 无推进 |
一条 steer，建议先如实更新清单 |
三道限流：冷却 5 分钟、日志距离 ≥12 个事件、每个主脑最多 4 次。纠偏经 sessionController.prompt(..., { mode: 'steer' }) 投递，不走易被 step 校验拒绝的 developer/message 写日志路径。
清单完成、空闲约 90 秒、或主脑被切片时，后台可执行 memory_harvest（切片场景绕过冷却，但每个主脑只提炼一次）；决策逻辑在 src/core/monitor.ts，投递在 src/core/supervisor.ts。
读取与可观测¶
磁盘类读取经 paradise-bridge 懒加载 dsh-paradise 读取器；彼岸层不可用时读路径具名降级（pathSource: 'paradise-unavailable'），回执字段保持与既有约定一致。observer_status 可暴露 paradise: { resolved, available, via, reason, ... } 等状态。
与生态内其它包的关系¶
README 说明四包同装：dsh-paradise 为内核，dsh-memory、dsh-graft-slice、dsh-observer 依赖其协议；必须先装内核再装业务插件。graft-slice 的写入路径由彼岸层负责，本仓作为下游观察者，不接管 graft-slice 的写路径。
环境要求¶
| 项 | 版本 |
|---|---|
| Node | ≥ 22.5.0（node:sqlite） |
| DSH | ≥ 0.2.1-rc.5 |
| 外部 npm 依赖 | 无（运行时仅用 Node 内置模块） |
package.json 中 peerDependencies 含 @corvus-dsh/dsh-paradise；v1.9.0 起写路径缺彼岸层会返回 PARADISE_WRITE_UNAVAILABLE 并带 stage，属于硬依赖语义。npm 上裸名 dsh-observer 被第三方占用，安装请始终使用作用域包 @corvus-dsh/dsh-observer。
安装与启用¶
两条安装路线二选一，不要混装同一插件的不同来源。
路线 A：npm registry（beta）¶
dsh plugin add @corvus-dsh/dsh-paradise@beta
dsh plugin add @corvus-dsh/dsh-memory@beta
dsh plugin add @corvus-dsh/dsh-graft-slice@beta
dsh plugin add @corvus-dsh/dsh-observer@beta
查看 registry 上 beta 当前版本：
npm view @corvus-dsh/dsh-paradise@beta version
路线 B：GitHub 直装¶
dsh plugin add github:corvus-dsh/dsh-paradise
dsh plugin add github:corvus-dsh/dsh-memory
dsh plugin add github:corvus-dsh/dsh-graft-slice
dsh plugin add github:corvus-dsh/dsh-observer
路线 A 拿的是已发布固化产物，便于 pinning 版本（例如 @corvus-dsh/dsh-paradise@0.9.1-beta.1）；路线 B 对应仓库当前 HEAD，适合跟进最新提交。顺序上先 dsh-paradise，后其余三个。
装完确认：
dsh plugin list
期望四行均为 active；若 fiberPhase 为 null 或异常，可查宿主日志，常见原因之一为 Node 低于 22.5。
卸载（按需逆序移除）：
dsh plugin remove dsh-observer
dsh plugin remove dsh-graft-slice
dsh plugin remove dsh-memory
dsh plugin remove dsh-paradise
README 另说明：若只需独立宿主与 Web UI、不经 DSH 装插件，可克隆 dsh-paradise 仓库运行 node dist/harness-server.js（与本篇插件安装路径无关，详见仓库内《星火 OS 独立运行指南》）。
典型用法说明¶
公开 README 未给出单独的「一键 CLI 演示脚本」，业务入口通过 DSH 插件工具与宿主会话交互体现，主要包括：
- 在主会话侧完成调研与卡片确认后，由 observer 经彼岸层 create + trigger 孵化主脑，并强制继承
cwd与运行时旋钮。 - 主脑运行期间，监理逻辑自动根据事件流判断是否 steer；无需在文档中手写轮询。
- 通过宿主暴露的
observer_status等接口查看 paradise 解析与监理相关状态（字段以当前 manifest / 实现为准）。
向已存在会话追加内容（inject 仅覆盖创建时放置）在层内仍可能报 NOT_WIRED，属于 README 所列已知边界。
适用场景与注意¶
适合：已在 DSH 中使用星火 OS 四件套、希望主会话有伴生副脑负责孵化主脑、自动发现卡死/清单停滞并有限纠偏、在节点完成或切片后做 memory_harvest 的团队或个人开发者。
注意：
- 插件以当前 DSH 进程权限运行；安装前请自行审阅源码与 MIT 许可证，并从官方 README 核对安装命令，勿使用非
@corvus-dsh/*的同名裸包。 - 社区目录 skillhub.cn 为独立站点，与 DeepSeek / 幻方无官方从属关系。
- 仓库测试说明当前为 204/204 通过；
package.json版本为0.9.2-beta.1，属 beta 通道，部署时建议 pin 具体版本便于复现。
结尾¶
dsh-observer 把「副脑共转、不被切片」和「孵化后监理 + 记忆提炼」收进同一插件，并把读写诚实地绑在 dsh-paradise 上：读不到、写不了都会具名报错，而不是伪装成功。进一步了解请访问 目录页 与 GitHub 仓库。
