dsh-nautilus

简体中文 | English

简介

Nautilus 是一个「只看不改」的会话观测插件：挂在 DeepSeek Harness（下称 dsh）上，把每一轮对话的读数 （token / 缓存 / 耗时 / tps）连同质量判断记成可回看的数字与台账，并集中呈现在一个叫 「Nautilus 工作台」 的面板里。

• 它解决什么问题：长对话里「哪几轮真正往前走了、代价是多少」平时只留模糊印象。这个插件把它变成可复查的记录—— 逐轮读数、模型自评、你的人工判读并排放在同一行，还能回头给历史上的会话补打分。
• 它不做什么：不改宿主源码、不改宿主行为、不写你的数据；不读也不写任何 Obsidian vault。 观测数据只落在你自己的 ~/.dsh/nautilus/（SQLite）。定位是观测，不干预——结论由人下，插件只提供证据。

安装

装完必须重启宿主：桌面端（dsh-desktop）没有热更新，改完不重启就等于没改（实测事实，见 桌面宿主适配）。

方式 A：web profile（dsh web）

# git 形式：装到 profile 目录（推荐用于长期使用）
dsh plugin --profile <profile-name> add github:chemmy-11/dsh-nautilus

# 本地检出形式：直接指向本仓库（推荐用于开发）
cd <本仓库>
npm run build                                        # link: 之前必须先构建
dsh plugin --profile <profile-name> add link:<本仓库绝对路径>

git 装配：本仓库不提交构建产物 lib/，安装时会就地构建（prepare / prepack → scripts/prepare.mjs）。 pnpm ≥10 默认拒绝执行依赖的构建脚本，所以必须在 profile 的 pnpm-workspace.yaml 里放行：

allowBuilds:
  '@dsh-external/dsh-nautilus': true

• 为什么必须放行：放行 = 授权这个依赖在安装时执行构建代码（等同信任本仓库的构建脚本）； 不放行的后果不是报错，而是静默装出一个没有 lib/ 的坏包（pnpm 11.24 实测：不报错、不警告，症状是插件根本不出现）。
• 生产装配请锁定 commit SHA：github:chemmy-11/dsh-nautilus#<sha>。

link: 装配：profile 直接指向本仓库目录，改完代码重新 npm run build 即可生效（无需重新安装）。 同样因为产物不入库，link: 之前必须先 npm run build，否则装到的是没有产物的空壳。

方式 B：桌面端（dsh-desktop）

桌面宿主用 link: 装配本仓库：

cd <本仓库>
npm run build
dsh plugin --profile desktop add link:<本仓库绝对路径>

• profile 由 Electron 独占管理：dsh --profile desktop --dump-config 这类 CLI 验证会被拒， 所以「桌面装配是否生效」不能用 CLI 证明——只能在应用内观察。
• 装完必须回读 profile 的 dsh.profile.bundles：组合器只读这个列表，不在列表里的依赖即使装好了也不会挂载 （症状是插件整个缺失：路由 401、工具不存在、面板不出现）。 dsh plugin add 会写进去；任何重装/清理之后的第一次自检就是回读它。
• 改动需重启应用生效：客户端半区由 lib/client.js 在应用启动时加载，npm run build 只更新磁盘上的产物， 不触达已在运行的进程。顺序恒定为：改码 → npm run build → 重启应用 → 在既有页面刷新后观察。
• 请求链路与实测头形（页面源 dsh-app://app、/api/* 由主进程代理转发）见 docs/2-dev/nautilus-dev-07-desktop-host.md。

装完自检

重启宿主后，侧栏应出现「Nautilus 工作台」图标行，点开即工作台（默认落在「总览」）。 看不到 → 见 FAQ（多数是没重启，或 git 装配漏了 allowBuilds）。

快速开始

第一次打开工作台：顶部是一排视图按钮，右上角有刷新与「返回会话」。

视图	一句话
总览	会话读数的汇总与逐会话列表（点开有逐轮抽屉）：token、缓存命中、耗时、tps。
对齐	「对齐 1–5」人工判读与模型自评的双路台账（同一轮并列，Δ = 自评 − 人工）+ 四条边界的分布 + 样本一致性。
会话	往期会话清单（工作区名 · 会话名 / 轮次数 / 读数合计 / 人工覆盖）；点开逐轮明细，每轮可以直接打分。
告警	OS / GPU 层红线告警：越线检测、证据冻结、报告与人工裁决。
曲线	会话读数曲线：时间档位、指标切换、轮次轴、全屏、悬停下钻。
报告	可重复的分析报告：形态分类、特征时间 τ_e、分桶对照。

给某一轮打分

1. 打开 会话 视图 → 点某一行的会话名，展开它的逐轮明细；
2. 每轮最右一列是打分入口，点 「对齐」 展开：选 1–5 档，或选 N/A；
3. 选 4 或 5 必须附引文（你引用 / 追问 / 改道于哪一句）——这是硬性要求，不填提交不了；
4. 点「提交」。

几个词的意思：

• 对齐 1–5：这一轮在「接 → 顺 → 推」的校准回路上推进了对方真正问题的程度—— 1 没接住（绕开对方状态、答非所问）· 2 接住了但没延展（正确、无增量）· 3 接+顺一层（在已有表达上点亮一处）· 4 顺+推（指出他还没命名的结构或方向）· 5 推到了改变下一步动作（他改道 / 引用 / 追问，可回查）。
• N/A：这一轮没有可判断的对象（纯操作性指令轮）→ 豁免，不进分母。
• 四条边界（与档位正交，越界不改变档位但要记录）：不替代 · 不占有 · 不强迫 · 不投射。
• 重新提交即覆盖：同一轮的判读是覆盖语义（服务端 upsert），不会追加一条新记录； 已标注的轮次展开打分件时会预填当前分，改哪档点哪档再提交即可。
• 原文缺失的轮次不能打分：入口会禁用并写明原因（该轮原文不在库里，服务端会拒绝写入）——不给假按钮。

你能做什么

• 逐轮遥测：每轮的 token（输入 / 输出 / 缓存命中）、耗时、tps，自动采集，无需手动记录；
• 自评：模型按「对齐 1–5 + 四条边界」给自己的判断（通过 dsh 工具或 HTTP 通道）；
• 人工判读与一致性：你给人自评打分（或独立打你自己的分），工作台把两路并排、算差值、给覆盖率与一致性指标；
• 往期回顾：会话视图列出历史会话，展开即可对之前的轮次补打分或改分；
• OS / GPU 红线告警：按规则检测越线（含滞回与冷却），冻结证据快照，可选三段式 LLM 报告，并在工作台里人工裁决；
• 可重复分析：形态分类、特征时间、分桶对照——同一份数据可以反复跑出同一份结论。

配置

配置写在 profile 的 cordis.patch.yml 里。所有字段都有默认值，通常不需要配置：

- id: nautilus
  config:
    dataDir: ''            # 空 = $DSH_HOME/nautilus（默认）；多端共享同一份数据时指向同一目录
    readings:
      enabled: true        # 是否采集会话读数
      historyDays: 30      # 读数保留窗口
    selfcheck:
      ingest:
        enabled: false     # 外部 harness 自评通道，默认关闭
        token: ''          # 开启时必须填非空 token（空 token + enabled=true 会在加载时报错）
        maxBodyBytes: 8192
    pulse:
      enabled: true        # OS/GPU 采集子插件
      intervalMs: 5000
      enableCounters: true
      enableGpu: true
      alertEnabled: true   # 红线告警

配置键注意：读数采集项自 AL.4g 起叫 readings（旧键 lField 已改名、不再被读取）； 若你的配置里还写着 lField，请改名，否则该项会静默回落到默认值。

pulse 子插件还有更多字段（采样间隔、保留期、告警规则 alertRules、alertsDir 等，均有默认值）， 见 docs/2-dev/nautilus-dev-03-os-layer.md 与 docs/2-dev/nautilus-dev-06-os-alerting.md。

数据与隐私

• 数据只落在你自己的机器上：~/.dsh/nautilus/nautilus.db（SQLite；pulse 子插件同库不同表）。 dataDir 可改为别的目录（多端共享同一份数据时用）。
• 不读也不写 vault：本插件与 Obsidian vault 零耦合（vault 观测腿已于 2026-09-27 下线）。
• 不改宿主：不修改宿主源码、不改变宿主行为；数据采集走官方 session/event 事件，零侵入。
• 自评 ingest 默认关闭，且开启必须配 token（请求头 x-nautilus-selfcheck-token）；没开通道时该路由恒 403。
• 本地 API 有同源门：所有 /api/nautilus/* 路由只接受本机同源请求，跨站请求一律 403（拒绝时会回显所见标记， 便于定位）——细节见 桌面宿主适配。

FAQ

Q：为什么改完代码要重启宿主？ A：桌面端没有热更新：客户端半区由 lib/client.js 在启动时加载，npm run build 只更新磁盘产物。 顺序永远是 改码 → npm run build → 重启应用 → 刷新既有页面。

Q：桌面端面板空白 / 请求一直 403？ A：这是已修的问题：本插件的同源门曾把 sec-fetch-mode 误当作跨站信号，导致桌面端（dsh-app://app 页面源 + 主进程代理转发）的请求恒 403。升级到最新版本即可；成因与判据见 docs/2-dev/nautilus-dev-07-desktop-host.md。

Q：桌面端请求返回 401（不是 403）？ A：这是另一条路径，两件事别混： （1）0.1.x：同源门误判 → 403（上面那条；响应体回显 seen 所见标记）； （2）0.2.0-rc.1：宿主兼容门按 peer 范围判定本插件不可用 → 整包拒装（insert: nautilus 不进组合）， 症状是本该已注册的 /api/nautilus/* 路径返回 401 裸文本 unauthorized，且工具与采集一起消失。 注意：未知路径（如 /api/nautilus/nope，乃至别的插件的 /api/pet/nope）的 401 只是连接层 /api 前缀兜底， 任何插件都一样，不能用它判断本插件是否注册。 修法 = 升级本插件（peer 已覆盖 0.2.0-rc.1）；判据与证据见 docs/2-dev/nautilus-dev-07-desktop-host.md。

Q：为什么历史会话的工作区显示「未知工作区」？ A：工作区归属从 v10 才开始采集，且不回填历史数据（forward-only，避免用今天的归属去改写过去的记录）。 所以早期会话显示「未知工作区」是设计结果，不是缺陷。

Q：「会话名」是怎么来的？是宿主的真名字吗？ A：不是真名，是派生名：取该会话第一条不以 < 开头且去空白非空的提问的首行前 24 个字； 找不到就退回会话 id 的末 8 位。因为真库里大量提问以 <system-reminder> 之类的块开头，只好这么取—— 所以列表里的名字只用于辨认，不是权威标题。

Q：为什么两个地方的「轮次数」不一样？ A：口径不同。「会话」视图（/m2/sessions）是并集口径——「有读数」或「有原文」都算一轮 （故意把「原文在、读数缺」的轮次也列出来，因为那些轮次照样可以打分）；「总览」的读数是读数口径，只数有读数的轮次。 合计（token / 时长 / tps）始终只累加有读数的轮次，缺读数的位置显示 —（不写 0，0 是真实读数）。

开发

npm run typecheck && npm run build && npm test      # 提交前的本地门禁（三件）
npm run check:deps && npm run check:exports && node .github/scripts/check-meta.mjs

• 工程约定与红线：CONTRIBUTING.md（分支 / 提交信息 / 六件套 / 宿主适配 / profile 卫生）；
• 开发文档索引：docs/2-dev/README.md——含 桌面宿主适配（dev-07）、 工作台 UI（dev-02）、 对齐量表决策 与 UI 线证据归档；
• 提交与评审：issue 先行、PR 一律 squash；lib/ 不入库（构建入口只有 scripts/prepare.mjs）。

兼容性

• 当前主用宿主：dsh 0.2.0-rc.1（桌面端 dsh-desktop 0.2.0-rc.1 实测可用）； 也已实测 0.1.5-rc.2（稳定线）、0.1.6-alpha.2（并存安装 dsh-next）、0.1.7-rc.1 与桌面端 0.1.7-rc.2 （组件版本矩阵见 dev-07）。
• 宿主升级会先过一道兼容门：宿主按 package.json 的 @deepseek-ai/dsh* peer 范围判定插件是否可用， 不覆盖运行版本的 peer 会让插件被整体拒装（症状：路由 401、工具消失、面板不出现，且日志在桌面端被吞掉）。 升级 devDep 后先跑 npm run check:deps（R3 就是这条护栏）；peer 范围现覆盖 0.1.1-rc.2 … 0.2.0-rc.1。
• 依赖面与 peer 范围、宿主升级五步流程见 CONTRIBUTING.md「宿主版本适配」。

许可

BSD-3-Clause（见 package.json 的 license 字段；仓库当前未单独附 LICENSE 文件）。