# 文档生命周期和处理策略

## 文档生命周期

```
用户放入 sources/（支持子目录）
       │
       ▼
   检查文件（跳过空文件、检测冲突）
       │
       ▼
   解析文件内容（失败则保留在 sources/）
       │
       ├──▶ 写入 parsed/<文件名>.md（含头部元信息）
       │
       ├──▶ 移动原始文件到 archive/<文件名_YYYYMMDDHHmm>.<ext>
       │
       ├──▶ 更新 manifest.json
       │
       └──▶ 增量更新 project.md（追加文件索引和更新记录）
```

## 归档命名规则

所有进入 archive 的文件都必须带时间戳后缀，格式为 `<文件名_YYYYMMDDHHmm>.<扩展名>`，即使只有一个版本。

示例：
- `需求文档.docx` → `archive/需求文档_202602181600.docx`
- `技术方案.pdf`（第二次入库）→ `archive/技术方案_202602181725.pdf`

## 同名文件更新

同名同扩展名的文件再次入库时：
- `parsed/` 中的 markdown 文件被覆盖为最新版本
- `archive/` 中保留所有历史版本（每个版本独立的时间戳文件）
- `manifest.json` 中该文件条目的 `versions` 数组追加新版本记录

## 同名不同扩展名冲突检测

因为 parsed 产物以文件名（不含扩展名）+ `.md` 命名，同名不同扩展名的文件会产生冲突。

### 检测规则

1. **sources/ 内部检测**：扫描 sources/ 中所有文件（含子目录），如果存在同名但不同扩展名的文件（如 `技术方案.pdf` 和 `技术方案.docx`），拒绝处理并提示用户重命名
2. **与已入库文件检测**：将 sources/ 中文件的名称（不含扩展名）与 manifest.json 中已有记录对比，如果名称相同但扩展名不同，拒绝处理并提示用户重命名

### 处理方式

冲突文件不予处理，保留在 sources/ 中，提示用户重命名后重新执行 ingest。非冲突文件正常处理。

## 文件类型解析策略

| 文件类型 | 解析方式 |
|----------|----------|
| `.docx`, `.pdf`, `.pptx`, `.xlsx` | 使用名为 **lyxy-reader-office** 的 skill 解析 |
| 其他所有文件（`.md`, `.txt`, `.csv`, `.json`, `.xml`, `.yaml`, `.yml`, `.log`, `.html` 等） | 直接读取文件内容 |

### Office 文档解析

解析 office 文档时，必须查找当前环境中名为 **lyxy-reader-office** 的 skill，阅读其 SKILL.md 获取具体的执行方式和命令。

**如果环境中不存在 lyxy-reader-office skill，且没有其他可替代的文档解析 skill，则提示用户无法处理 office 文档，中止整个 ingest 流程。**

### sources/ 扫描规则

扫描 sources/ 时**递归检查所有子目录**中的文件。parsed 产物的路径仍为 `parsed/<文件名>.md`（扁平化存放），不保留 sources 中的子目录结构。

### 空文件处理

sources/ 中 0 字节的空文件应**跳过处理**，不解析、不归档、不更新 manifest。处理完成后向用户列出被跳过的空文件列表，提示用户检查。

### 解析失败处理

如果某个文件解析失败（如文档损坏、解析器报错），该文件**保留在 sources/ 中不移动**，报告错误信息，继续处理其他文件。

## 更新策略

**增量追加**（默认，由 ingest 触发）：
- 新文件：在文件索引表追加新行，在更新记录追加条目
- 已有文件更新：覆盖文件索引表中对应行的最新归档路径和摘要
- 概述和关键信息部分**不**自动更新

**全量重写**（由 rebuild 触发）：
- 读取所有 parsed/*.md 文件
- 重新生成概述、关键信息、文件索引
- 保留历史更新记录，追加本次 rebuild 条目