# Incident report（脱敏版，可直接公开）

> 本文只描述**机制**，不含任何作者环境信息。占位符规则见文末。
> 用途：`dsh-agent-guard` 仓库的 `docs/` 公开文档，说明"这个插件为什么存在"。

## 摘要

在一次**完全正常的目录整理**之后，一个 agent 会话把"界面显示异常"逐步升级为"应用私有存储被改写"，最终导致应用崩溃，需借助 `<third-party-tool>` 抢救恢复。事后用一手证据核查发现：**被误判为"丢失的数据"从未丢失，而是应用有意不展示的内部记录**——即"设计"被误读成了"缺陷"。

本项目的全部设计约束都来自这次事故。

## 环境（占位）

- 宿主：`<os>`，DSH `<dsh-version>`，`<home>` 下使用默认 DSH 数据目录
- 工作区：`<workspace-a>`、`<workspace-b>`（此前位于盘符根目录，后被整理进同一子目录）
- 会话：`<session-id>` 若干；另有 `<third-party-tool>` 参与诊断与恢复

## 时间线（机制视角）

1. **整理**：把若干工作区目录从盘符根目录移动到同一父目录下。这是普通文件操作，应用未给出任何提示。
2. **失效**：应用的工作区身份以**绝对路径**为准，会话存储目录名是**路径的编码键**。移动后，注册表路径不再存在 → 界面少显示会话。
3. **误判**：agent 未读取一手证据（会话文件首帧身份头），仅依据"磁盘目录数 ≠ 注册表登记数"的差值，推断"索引缺失、丢失了 N 个对话"。
4. **错误修复 1**：agent 在旧路径上创建**目录联接**指向新位置 → 注册路径与"解析后的真实路径"分裂 → **分组变空、会话被归入「未分组」**。
5. **错误修复 2**：agent 编写并交付一个"重命名会话目录 + 重写注册表"的**可双击脚本**。
6. **崩溃**：脚本在应用未完全停止（或刚重启）时生效，注册表与磁盘状态错位 → 应用崩溃。
7. **抢救**：`<third-party-tool>` 解压全部会话文件的首帧身份头，证明"缺失的对话"实为 `origin: "subagent"`、`delegationDepth ≥ 1` 的**子代理内部记录**——应用**有意不登记**它们。
8. **恢复**：把工作区目录**物理搬回**注册表记录的位置、删除全部联接（不使用任何存储改写），状态自洽恢复；应用随后自行重写了注册表。

## 根因（四条，缺一不可）

| 编号 | 根因 | 性质 |
|---|---|---|
| R1 | **路径即身份**：工作区身份、会话存储键、会话文件头的 `cwd` 三处均以路径为准 | 宿主设计特性 |
| R2 | **用汇总数字代替一手证据**：以"数量不一致"推断"数据缺失" | agent 方法论错误 |
| R3 | **影响预算失衡**：问题影响面是"界面显示"，改动影响面是"全部会话存储 + 注册表" | agent 判断错误 |
| R4 | **把不确定性转成用户的一次双击**：安全闸门只依赖单一弱代理（探测端口） | agent 工程错误 |

## 哪些信号本应阻止它（→ 本项目规则）

| 本应出现的信号 | 对应的插件能力 |
|---|---|
| "数量不一致不等于数据缺失" | `protected-inspect`：读一手身份头，标注 `countsAsConversation: false` |
| "这是应用私有存储，不是工作区" | 受保护路径分类 + 默认拒绝 |
| "一次重命名多个受保护目录 = 高危" | `rename-many` 规则直接拒绝 |
| "应用可能没停" | 多重判据（进程 + 端口 + 文件占用 + 写入活动），判不出按"未停止" |
| "别把破坏性操作交给用户双击" | 禁止产出引用受保护路径的一键脚本；生成即告警 |
| "修复带来新症状 = 修法错了" | 同路径连续改动且校验变化 → 强制暂停 |
| "先有回滚点" | 每轮自动快照（注册表 + 目录布局清单） |

## 恢复方式（可公开复述的安全做法）

1. **停止**一切改写动作；
2. **只读取证**：读一手身份头与目录布局，确认"缺失"是否真实存在；
3. **备份**关键状态（注册表、目录布局清单）；
4. **物理搬回**目录（不使用联接、不改写应用存储）；
5. **校验**：注册表路径存在、目录布局与身份头一致、应用可正常启动；
6. 若权限受限（Windows 文件权限），按平台工具**带备份地**修复，并保留回滚命令。

## 可迁移的通用结论

1. 任何"路径即身份"的系统，移动/重命名目录 = 换身份；**能由应用完成的移动，不要用文件管理器做**。
2. 诊断要从**一手记录**出发（文件头、日志行），不要从汇总计数出发。
3. 改动的影响面**不得大于**问题的影响面。
4. 破坏性操作**不得**做成"一键交给用户"的形态。
5. 修复引入新症状时，先怀疑修复本身。
6. 应用私有的数据目录：**只读、不手改**；确需变更时，先停应用、先备份、后验证。

## 占位符规则（本报告的脱敏方式）

| 真实值类型 | 替换为 |
|---|---|
| 具体路径（盘符、目录名、用户名） | `<home>` / `<workspace-a>` / `<workspace-b>` |
| 机器名 | `<host>`（本报告未使用） |
| 会话 id / 记录 id | `<session-id>` / `<record-id>` |
| 第三方工具名 | `<third-party-tool>`（未获同意不点名） |
| 版本号 | `<dsh-version>` / `<os>` |
| 会话标题、工作区名 | **一律不出现** |