# 产物与文件

[← 回到 README](../README.md)

## 转换结果放在哪

默认写在**源文件旁边** —— 也就是工作区里，和原文件同一个目录。配 `tmpDir` 可以改到别处；
留空表示用默认行为。

返回给模型的只有路径、体积、行数和结构索引，所以模型拿到的是一个可以按需读取的本地文件，
而不是被注入上下文的全文。

## 产物里有什么

文件是标准 Markdown。**第一行是插件写的元信息注释**，记录这次转换是谁做的：

```
<!-- dsh-office-markdown converter=python-module fidelity=high at=<时间> srcbytes=<字节数> srchash=<哈希> -->
```

这行的用途有两个：命中缓存时插件从它读回当时**真实**用的转换器与保真度；
以及让你事后能判断某份产物是哪一级转换器的结果。

## 缓存与失效

`reuseFresh`（默认开）决定源文件没变时是否复用已有产物。判断依据是源文件的哈希，
记录在产物第一行里 —— 源文件一改，缓存就失效，下次转换会重写产物。

用 `force` 参数可以强制重新转换，忽略已有结果。

## 会留下哪些文件

| 文件 | 位置 | 说明 |
| --- | --- | --- |
| `<源文件名>.md` | 源文件旁边（或 `tmpDir`） | 转换产物，属于你的文件 |
| 环境记录 | DSH 数据目录，`*.env.json` | 插件登记过的 Python 包清单，用于卸载时精确清理 |
| 清理日志 | DSH 数据目录，`*-removal.log` | 看门狗执行清理后留下的一行摘要 |
| 单实例锁 | 由看门狗在清理期间临时创建 | 保证同时只有一个看门狗在跑，用完即删 |

**插件不修改源文件**，也不在插件目录里写任何东西。

## 陈旧产物

同一个源文件反复改动时，可能留下多份历史产物。清理方式有两种：

- 用工具的 `action: "clean"` —— 默认**先干跑**，列出将删除哪些文件，确认后再传 `dryRun: false`。
- 把配置项 `pruneStaleArtifacts` 设为 `true` —— 每次转换后顺手清理。

**不要让模型用命令行自己删文件**。走 `action: "clean"` 才能保证只删插件自己产出的东西、
并且删对了配套的元信息。

## 关于体积

换算成多少 token、产物有多大这类数字，本文档不列 —— 它们高度依赖具体文件，
没有可复现的测量过程。真要对比，拿你自己的文件跑一遍，看返回的体积和最直接的体感即可。

---

> 本文档主要由 AI 生成，行为说明对照过 `lib/index.js` 与 `lib/paths.js`。
> 说明与免责见 [README 的「关于本文档」](../README.md#关于本文档)。