# 变更记录

本文件记录面向使用者的变更。格式参照 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。

## [Unreleased]

尚未发布的内容会先写在这里。

### 文档

- `docs/DESIGN.md` 重写为「功能与设计文档」：新增完整功能概述与总体架构章节，方案章节保留全部内部 ADR（决策 1–26），数据模型 / API / 测试 / 验收清单归并到独立章节，删除实现过程中的调试编年史与内部消息引用。

## [1.0.0]

首个版本。

### 新增

**监控**

- 右侧边栏 Tab（经 `dsh-better-sidebar`），与主区页面共用同一份状态；可一边对话一边看设备。
- 最多 **10 台**设备，SSH 密码 / 私钥 / 键盘交互三种认证。
- **11 项**可勾选指标：运行时间、系统负载、CPU、内存、磁盘、温度、高占用进程、网络吞吐、
  磁盘 IO、进程数、TCP 连接数。**勾选项决定下发哪些采集命令**，未勾选的指标一条命令都不下发。
- 采集命令全部兼容 busybox（`/proc`、`/sys`、`df -P -k`、`mount`、`systemctl`），
  缺失的项目自动降级为空值而不是伪造读数。
- 默认 **60 秒**刷新（可配置 5–3600 秒），可按设备覆盖，**租约**机制：面板可见才续约，
  隐藏即停止拨号。刷新周期也可按设备覆盖。
- 波形图：四个指标各有独立列，**自动适配可见区间的量程并印出横纵坐标**；
  环形缓冲按刷新周期自动定容（约 3 小时窗口）。
- 阈值告警：CPU / 内存 / 磁盘 / 温度逐项可调，设为 0 即关闭该项。
- 异常记录：掉线 / 恢复 / 重启，独立的 `incidents.log`。
- 原始采集原文（未脱敏）逐设备落盘，滚动 + 上限，可在面板「设置」中整体关闭。

**终端调试**

- 每张卡片一个按钮，在右下角开一个交互式 shell 浮层（**不是模态**，对话区同时可见）。
  「扩大」填满右侧栏，「还原」返回原位。
- **默认关闭**，须先在「设置」里打开。
- **不受 Agent 工具的命令白名单约束**，输入原样发到设备——面板里有明确提示。
- 上限 3 会话/设备、10 会话/进程，空闲超时兜底；回环围栏 + 可选来源允许列表。
- 审计只记会话开关与字节数，**绝不记录击键**。

**Agent 工具**

- `device_list` / `device_status` / `device_collect` / `device_exec` / `device_history`。
- `device_history` 把异常记录与审计记录**合并成一条时间线**（新的在前），
  可按设备与类型过滤——回答「这台设备昨晚稳定吗」，而 `device_status` 只能描述此刻。
- 系统提示中说明每个工具的用途与「过去 / 此刻」的分工。

**安全与审计**

- 设备名单与凭据存于 `$DSH_HOME/dsh-device-monitor.json`（权限 `0600`），
  **不写日志、不下发浏览器、不进 tarball**。
- 审计日志**只记字段名不记值**：`settings.update` 记 `thresholds.cpu` 不记 `90`；
  `device.update` 记 `["host","port"]` 不记主机名与端口。
- `device_exec` 的审计只记 **`commandLength`**，不记命令文本——见下方「安全」。
- 自定义命令**只替换命令体、不打开门控**，审计只记指标名。

**分发**

- `npm pack` 产出的 tarball 自带 `cordis.patch.yml`，并声明 `ssh2` / `ws` 运行时依赖。
- `tools/pack-dist.mjs`（pre-flight + 读打出来的包）与 `tools/verify-dist-installable.mjs`
  （解开到新目录后再验一遍）保证「能跑」与「能装」是两件事。
- 设备名单**不在包里**，换机器重新登记是有意的：密码不该跟着代码走。

### 安全

- 修复：`device_exec` 的审计日志一度写入**完整命令文本**，与「只记字段名」的承诺矛盾。
  在这台机器上 `mysql -p'…'`、`curl -H 'Authorization: …'` 都是寻常命令，所以
  「把值记下来」等于「把凭据记下来」。**修法是整段不记，而不是发明一套「哪部分是安全的」规则**——
  任何靠检查命令内容来决定保留什么的规则本身就可能判断错。历史日志中的旧行不会被追溯删除
  （日志是追加式的取证记录）。
- 修复：终端调试曾因浏览器半用 `window.location` 拼出**无 authority 的 WebSocket URL** 而
  **一个字节都发不出去**（服务端连审计行都没有）。现在从 `__DSH_TRANSPORT__.streamBaseUrl`
  取真实主机，并显式承认 `dsh-app://app` 这个页面来源。
- 修复：编辑页密码框留空时，空串被原样送给 ssh2，导致
  `All configured authentication methods failed`。现在补上该设备已保存的密码。

### 文档

- `docs/DESIGN.md`：完整功能设计、内部 ADR、验收清单、变异表。
- `docs/PITFALLS.md`：十八个值得记住的坑，每条都保留了当时的错误判断与推翻它的证据。
- `docs/TRADEOFFS.md`：哪些行为是刻意这样设计的。
- `docs/CONTRIBUTING.md`：如何改代码、跑测试、加变异体。
- [`SECURITY.md`](SECURITY.md)：凭据存放、命令执行门控、审计范围，以及**不**做的事。

### 已知限制

- **不做 SSH host key 校验**（无 `hostVerifier` / `known_hosts`）。
- **不检查命令内容**：`device_exec` 与面板终端都不做白名单过滤，补偿手段是门控与围栏。
- 波形历史**纯内存**，Host 重启即归零。
- 阈值告警**不落盘**，也不可确认 / 静默，且只对最新一个样本求值。
- 面板不可见时**采集完全停止**（租约设计的直接后果）：夜里掉线不会留下记录。
- 不支持跳板机；无设备分组 / 汇总视图；无名单导出导入。