# RimCrow 日志分析插件 — 安装说明

这是一个 **DSH（DeepSeek Harness）插件**，用来读取和分析 **RimWorld** 游戏日志（需要配合 **RimCrow** 使用）。

**它不代你改模组列表**：启用/禁用一律由你自己在 RimCrow 或游戏里勾选，插件只出清单。会写入的只有快照，且不会悄悄发生 ——
「工作区快照」会按天裁剪旧快照，
但**任何递归删除前都会校验目标确实在快照目录内**，校验不通过就跳过并报告。

---

## 一、前置条件

| 需要什么 | 说明 | 必需吗 |
|---|---|---|
| **DSH**（DeepSeek Harness） | 插件运行在它的插件系统里 | ✅ 必需 |
| **RimWorld** | 游戏本体，1.5 / 1.6 均可 | ✅ 必需 |
| **RimCrow** | 你的日志由它产生；插件从它那里读日志与模组列表 | ✅ 必需 |
| **RimCrow Companion**（辅助模组） | RimCrow 的配套 mod；装了它日志才带完整诊断堆栈 | ⭐ 强烈建议 |
| **Node.js 18+** | 只跑测试脚本时需要；插件本身由 DSH 运行 | 可选 |

> **RimCrow 和 RimWorld 装在不同位置没关系**，插件会自动找。找不到时可以手动指定（见第六节）。

---

## 二、安装

把本文件夹放到**你喜欢的任意位置**（不要放在 DSH 或 RimWorld 的安装目录里，放桌面、文档目录都行），然后用下面两种方式之一安装。

### 方式 A：让 DSH 自己装（推荐）

**把下面这一整段直接发给你的 DSH 对话：**

```text
请安装 RimCrow 日志分析插件。

插件包目录：<把本文件夹的完整路径填在这里>

安装要点：
1. 这是一个 DSH 插件包，package.json 里的 name 是 @local/rimworld-log，
   通过 dsh.bundle.patch 声明的 cordis.patch.yml 挂载。
2. 请用 plugin_manager 工具、action=install_bundle、target 传上面那个绝对路径来安装。
3. 不要手写 profile 的 package.json，也不要手写 cordis.patch.yml，更不要在 profile 目录里跑 pnpm。
4. 这个包没有任何外部依赖（dependencies / peerDependencies 均为空），
   只用 Node 内置模块，所以不需要安装任何东西。
5. 安装后必须重启 DSH 进程才会生效。请重启后确认插件已加载。
6. 装好后请告诉我怎么验证：让 /rimlog 有反应，或直接调用 rimworld_log_scan 工具。
```

### 方式 B：自己动手（了解 DSH 插件机制的话）

用 `plugin_manager` 的 `install_bundle`，`target` 传本文件夹的绝对路径。

**注意**：与本插件相关的三条常见错误做法（都会失败，别试）：

1. ❌ 手写 profile 的 `package.json` 加一行依赖
2. ❌ 手写 `cordis.patch.yml` 增删启用行
3. ❌ 在 profile 目录里跑 `pnpm install`

正确做法只有一条：**用 `plugin_manager` 装**。

---

## 三、安装后必须重启

**这是硬要求**：DSH 的模块导入有缓存，缓存键是「包」而不是「行」。已加载过的包换了内容也不会重新导入。

所以：

- **装完 → 重启 DSH**
- **以后改了插件代码 → 也要重启**

不重启的表现是「看起来装上了，但没反应」。

---

## 四、怎么确认装好了

### 1. 看界面

聊天输入框**下方**会出现一条**日志来源选择条**，有三个可勾选项：

| 来源 | 说明 |
|---|---|
| RimCrow 实时日志 | 结构化 JSON，信息密度最高、最省 Token —— **默认选它** |
| 原生 Player.log | 纯文本，Token 花费高 2–5 倍，用于交叉验证 |
| 上一次的 Player.log | 用于对比「这次新增了什么」 |

### 2. 试一句话

直接问 DSH：

```text
读一下我的 RimWorld 日志，看看有什么问题
```

它会调用 `rimworld_log_scan` 工具。

### 3. 或直接用命令

在 DSH 对话里输入：

```text
/rimlog
```

---

## 五、它会给你什么

### 两个工具

**`rimworld_log_scan`** —— 有 4 种用法：

| action | 作用 |
|---|---|
| `analyze`（默认） | 分析日志：聚类错误/警告、按严重度排序、给出**归属到哪个模组**及证据 |
| `detect` | 环境探测：RimCrow 装在哪、有哪些 profile、日志文件在哪、启用了多少模组、有没有缺失 |
| `grep` | 在原始日志里按子串或正则检索 |
| `mods` | **只起草**「启用/禁用模组」的改动清单，不写入 |

**`rimworld_workspace_archive`** —— 给工作区里**手写的结论**做备份：

| action | 作用 |
|---|---|
| `list`（默认） | 列出已有快照 |
| `snapshot` | 给今天拍一份，然后按天裁剪 |
| `export` | 导出迁移包，**只带最新那一份快照** |

### 快照是怎么留的

工作区里有两类东西：**手写的结论**（`OPEN_ISSUES.md`、`PATCHES.md`、日志归档、各个 `fix-*` 项目这类）和
**可再生成的产物**。规则是**默认全收**——最初想只收「手写的」，结果漏掉了 33 个项目目录，所以改成了反过来做:
只排除 `node_modules`、`bin`、`obj`、`.git` 这类编译与版本控制内部目录，**排除哪些会在报告里写明**。

- **一天一份，按天保留最新 3 份。** 在 1、6、10、15 号各归档一次，结果就是 **6、10、15**；15 号那次就已经把 1 号挤出去了。
- **同一天重复执行只覆盖当天那一份**，不会累积（否则一天跑几次就把旧的那几天冲掉了）。
- **今天的快照永远不删。**
- **不设单文件体积上限。** 曾经有过一个 4 MB 上限，实测它排除的全是反编译出来的 `.cs`——最难再生成的一类，所以去掉了。实测一份约 49 MB。
- **导出迁移包时只携带最新那一份。** 更早的留在快照目录里 —— 包里塞着过期副本，是两台机器对「哪份结论是当前的」产生分歧的根源。

快照默认放在**工作区同级的 `snapshots/`**（例如工作区是 `G:\…\mod工作区`，快照就在 `G:\…\snapshots`）。
工作区自动探测；探测不到存在的工作区时 `snapshot` 会**拒绝执行**，而不是生成一份空快照报成功。

### 两个命令

| 命令 | 作用 |
|---|---|
| `/rimlog` | 手动触发一次日志分析（结果作为一条消息交给当前会话） |
| `/rimmods` | 出「启用/禁用」清单。**插件不写入**，勾选由你自己做 |

### 默认是增量分析

第一次分析读全量；之后**只分析新增的日志**（游标会落盘）。想整份重扫用 `/rimlog --full`。

---

## 六、RimCrow 装在非默认位置怎么办

插件按这个顺序找 RimCrow：

1. **工具参数** `rimcrowHome`（最高优先，适合临时指定）
2. **环境变量** `RIMCROW_HOME`
3. **自动探测**常见安装位置

所以自定义安装的话，设一个环境变量最省事：

```powershell
$env:RIMCROW_HOME = 'D:\你的\RimCrow'
```

或者在插件的 `config` 里填 `rimcrowHome`。

---

## 七、可选的配置项

在 DSH 的插件设置里可以填两个值：

| 配置项 | 作用 | 默认 |
|---|---|---|
| `profileId` | 默认分析哪个 RimCrow profile（你有多个存档配置时有用） | 自动选日志最新的那个 |
| `defaultSources` | 默认勾选哪些日志来源，如 `["realtime"]` | `["realtime"]` |
| `rimcrowHome` | 手动指定 RimCrow 安装目录 | 自动探测 |

---

## 八、常见问题

**`/rimlog` 没反应，或提示找不到 RimCrow**
→ 设 `RIMCROW_HOME` 环境变量，或用工具参数 `rimcrowHome` 指定。

**提示「文件不存在（该来源在当前 profile 下没有生成）」**
→ 该 profile 下确实没有这个日志。`Player.log` 通常在 RimWorld 的用户数据目录里（`%USERPROFILE%\AppData\LocalLow\Ludeon Studios\...`），插件会自动回落到那里；**游戏从没跑过就不会有**。

**分析结果比 RimCrow 内置 AI 少**
→ 默认是增量分析（只看新增）。用 `/rimlog --full` 整份重扫。

**某个问题簇写着「归属 mod: 未能确定」**
→ 堆栈里只有引擎帧、没有模组线索。可以让 DSH 直接读原始日志行继续定位（`action: "grep"`）。

**`/rimmods --apply` 报错说「返回内容不是合法 JSON」**
→ 这是插件的返回值序列化缺陷（已修）。**写入其实成功了**，只是返回值报错。重启 DSH 后不再出现。可以用 `action: "detect"` 核对启用列表确认改动是否生效。

---

## 九、卸载

用 DSH 的插件管理移除，然后删掉本文件夹。

**会留下什么**：只有 `~/.dsh/rimworld-log/` 里的两个游标文件（记录「上次分析到哪」）。想彻底清干净就把它删掉。

---

## 十、已知限制（如实告知）

| 限制 | 说明 |
|---|---|
| **改代码必须重启 DSH** | 模块缓存键是「包」，不是「行」。热改无效 |
| **`Player.log` 里往往没有报错** | 如果你装了 RimCrow Companion，它会把 Unity 的日志回调拦截走，报错都进了 RimCrow 实时日志。所以**优先读实时日志** |
| **归属是「推断」不是「断言」** | 插件给出归属时同时给出**依据**（路径 / 消息内标注 / 命名空间）和**置信度**。想确认就顺着依据自己核一遍 |
| **插件写入 `ModsConfig.xml` 会被拒绝** | 一律拒绝：启用/禁用由你自己操作。想要放行需在机器上显式设 `RIMLOG_ALLOW_MOD_WRITES=1`（默认不设） |
| **只支持 Windows** | 检测游戏是否运行用的是 `tasklist`，路径处理也按 Windows 写 |

---

## 十一、这个包里的其他东西

除了运行必需的 12 个文件，本包还带了：

- **测试脚本**（根目录 11 个 `.mjs`）：用于验证插件没坏
- **`tools/`**（15 个）：排查具体日志问题时用的调查工具，都是只读的

它们**不影响插件运行**，删掉也能正常用。用途见 `插件清单.md`。