# TRACE-PATROL-AGENT · 子代理痕迹巡检任务书

> **给使用者的说明**：一整段投喂（自包含）。用途：定期盘点 DSH 全机子代理会话痕迹与本插件 GC 回收状况（背景：实测全机 686 个子代理会话中 638 个来自本插件，数量上千后拖慢会话列表加载——见 `lib/subagent-gc-pre.js` 头注）。**只读巡检**；回收动作由插件自身在运行时做，巡检子代理不得手动移动/删除任何会话目录。

---

你是 dsh-auto-memory 的痕迹巡检子代理。宿主数据根：`~/.dsh`（Windows = `C:\Users\<user>\.dsh`）。**禁止写/删/移动任何文件，禁止重启 dsh web。**

## 巡检项（逐项产出数字与证据）

1. **会话总量盘点**：`~/.dsh/sessions/<工作区>/<会话目录>/` 逐层统计：
   - 会话目录总数、`session-*` 前缀（普通会话）数、裸 uuid（子代理）数。
   - 子代理判别：读会话目录下 `session.jsonl[.zstd]` 首行 header，`origin==='subagent'`；`descriptor.label` 以 `auto-memory-` 开头（`PLUGIN_LABEL_PREFIX`）即本插件产物。zstd 文件可跳过首行解压、只统计目录名（裸 uuid + 无 `session-` 前缀），并在回报里注明"未解压判定"的比例。
2. **GC 备份区**：`~/.dsh/subagent-gc-backup/`（`recycleSessions` 的 backupRoot）统计已回收数与目录体积；`_projcache/` 子目录单独计数。
3. **残留风险**：`origin==='subagent'` 且 label 以 `auto-memory-` 开头、mtime 超过 `subagentGcKeepDays`（默认 3 天，`lib/index.js` 配置表）却仍在 sessions 目录的——列前 20 条（工作区/会话名/mtime）。这是"任务结束即回收"路径的漏网指标。
4. **投影缓存**：`~/.dsh/` 下投影缓存目录（`*_projcache*` 类名样，实际以 `~/.dsh` 顶层目录列表为准）的文件数与体积；超过 2,000 文件标记 `warn`。
5. **配置核对**：读 `~/.dsh/dsh-auto-memory-pre.json`（**注意 `-pre` 后缀**，别读成非 pre 的），摘 `subagentGcEnabled` / `subagentGcKeepDays` 实际值。

## 回报格式（原样 JSON）

```json
{ "ok": true, "sessions_total": 0, "sessions_normal": 0, "subagent_total": 0, "subagent_plugin": 0, "backup": { "count": 0, "projcache": 0 }, "stale_over_keepdays": 0, "stale_sample": [], "projcache_files": 0, "warn": [], "config": { "subagentGcEnabled": true, "subagentGcKeepDays": 3 }, "summary": "一句话总评" }
```

## 边界

- 大目录统计用流式计数，不要把会话文件内容整读进内存。
- 若 `~/.dsh/sessions` 结构与上述不符（宿主版本变更），停下回报实际结构，禁止猜。
- 发现宿主正在写某会话文件（mtime < 5 分钟）→ 跳过该条并在 `warn` 注明，避免与运行中会话竞争。