# _logs 目录文档归档整理方案

日期：2026-01-01

---

## 一、当前目录概况

| 类型 | 数量 | 说明 |
|------|------|------|
| 根目录文档 | 25 | 主要方案和报告 |
| 子目录 | 7 | 按主题分类 |
| 总文档数 | ~60 | 含子目录文档 |

---

## 二、文档分类分析

### 2.1 按状态分类

| 状态 | 文档 | 处理建议 |
|------|------|----------|
| **已实现** | 迭代日志.md、CLI分析报告、postprocess插件计划、mark2pdf_cli重构计划、image_clearing_plan、plan_createpdf_open选项、standalone_mode_plan、hardcoded_working_path调研 | 保留核心，归档细节 |
| **当前有效** | 项目说明文档-202512、mark2pdf_cli使用说明、工作区使用指南、单元测试有效性核查报告/计划、代码库核查报告 | **保留**，可能需更新 |
| **讨论/待定** | 讨论方案/下所有、最终思考/下所有 | 视情保留或归档 |
| **历史记录** | 已完成方案记录/下所有、codex调研/下所有 | **归档** |
| **过时** | batch模式相关(已合并)、NextJS集成分析(未实施--此项不删除，放入待办！！) | **归档或删除** |

### 2.2 按内容类型分类

| 类型 | 文档列表 | 建议 |
|------|----------|------|
| **用户文档** | 工作区使用指南、mark2pdf_cli使用说明 | 迁移到项目 README 或独立 docs/ |
| **开发日志** | 迭代日志.md | 保留在 _logs |
| **技术方案** | 各类 plan/方案 | 已实现的归档 |
| **审查报告** | 代码库核查报告、单元测试核查、nb模板审查 | 保留最新版 |
| **调研讨论** | codex调研、typst讨论、讨论方案 | 归档 |

---

## 三、建议目录结构

```
_logs/
├── 迭代日志.md                  # 【保留】核心开发日志
├── README.md                    # 【新增】日志目录索引

├── docs/                        # 【新建】用户文档
│   ├── CLI使用说明.md
│   ├── 工作区使用指南.md
│   └── 项目说明文档.md

├── reports/                     # 【新建】审查报告
│   ├── 代码库核查报告-20251231.md
│   ├── 单元测试核查报告-20260101.md
│   └── nb模板审查报告.md

├── archive/                     # 【新建】历史归档（不要按月归档，直接归档）
│   ├── 已完成方案/        # 合并原"已完成方案记录"
│   ├── codex调研/
│   ├── CLI重构系列/       # 合并多个CLI相关方案
│   └── 功能实现记录/      # batch模式、image_clearing等
│   └── 讨论方案/              # 保留尚未实施的讨论

├── typst/                       # 【保留】Typst模板相关
│   └── (原typst讨论内容)

└── research/                    # 【新建】调研文档
    ├── 双语翻译调研/
    ├── 多封面研究/
    └── 外部脚本调用/
```

---

## 四、具体操作清单

### 4.1 立即删除（冗余/过时）

| 文件 | 原因 |
|------|------|
| `.DS_Store` | 系统文件 |
| `已完成方案记录/markdown2pdf重构-20251223` | 空目录 |

### 4.2 合并整理

| 原文件 | 合并去向 | 原因 |
|--------|----------|------|
| `CLI分析报告_postprocess与合并建议.md` + `mark2pdf_cli重构计划.md` | `archive/CLI重构系列/` | 已实现，合并归档 |
| `batch模式实现方案.md` + `batch模式-images路径修复方案.md` | `archive/功能实现记录/` | 已实现 |
| `core_directory_重构方案.md` | `archive/功能实现记录/` | 已完成 |

### 4.3 迁移为用户文档

| 原文件 | 目标 | 备注 |
|--------|------|------|
| `mark2pdf_cli使用说明.md` | `docs/CLI使用说明.md` | 需更新至最新命令 |
| `工作区使用指南.md` | `docs/工作区使用指南.md` | 需更新 |
| `项目说明文档-202512.md` | `docs/项目说明文档.md` | 需更新 |

### 4.4 保留在根目录

| 文件 | 原因 |
|------|------|
| `迭代日志.md` | 核心日志，频繁更新 |

### 4.5 归档到 archive/

| 目录 | 归档内容 |
|------|----------|
| `archive/codex调研/` | 原 `codex调研/` 全部 |
| `archive/已完成方案/` | 原 `已完成方案记录/独立工作区-20251222/` |
| `archive/讨论方案/` | 原 `讨论方案/` 中尚未实施的内容 |
| `archive/最终思考/` | 原 `最终思考/` |
| `archive/功能实现记录/` | image_clearing_plan、postprocess_plugin_plan 等已实现方案 |

---

## 五、需要更新的文档

### 5.1 内容已过时

| 文件 | 问题 | 建议 |
|------|------|------|
| `工作区使用指南.md` | 仍提 `imageclearing`，实际已改为 `mdimage` | 更新命令名称 |
| `mark2pdf_cli使用说明.md` | 基本准确，可作为 docs 基础 | 校验后迁移 |
| `项目说明文档-202512.md` | 模块结构描述已变化 | 需更新 src 目录结构 |  <--  重写此文档。
| `代码库核查报告.md` | 基于旧版本，部分问题已修复 | 标注已修复项 |

### 5.2 待办事项（放入 backlog）

| 文件 | 说明 |
|------|------|
| `NextJS集成分析.md` | 尚未实施，作为未来可能的集成方案保留 |

### 5.3 代码与文档对照核实

| 文档断言 | 代码实际 | 状态 |
|----------|----------|------|
| 迭代日志提到的 `mdimage` 命令组 | `src/mark2pdf/commands/mdimage.py` ✅ | 一致 |
| `standalone` 模式 | `src/mark2pdf/config.py` 有 `standalone` 字段 ✅ | 一致 |
| `postprocess` 插件 | `src/postprocess/` 包存在 ✅ | 一致 |
| batch 模式 | `src/mark2pdf/conversion.py` 有 `run_batch_conversion` ✅ | 一致 |
| `--removelink` 参数 | CLI 已声明，传递逻辑已实现 ✅ | 一致 |

---

## 六、执行优先级

### 高优先级（建议立即执行）

1. 创建 `docs/` 目录，迁移用户文档
2. 创建 `archive/` 目录，归档已完成方案
3. 删除空目录和 `.DS_Store`

### 中优先级

4. 更新 `工作区使用指南.md` 命令名称
5. 创建 `_logs/README.md` 索引文件
6. 整理 `typst讨论/` 为 `typst/`

### 低优先级

7. 合并零散的方案文档
8. 标注历史报告中已修复的问题

---

## 七、文档索引模板

建议在 `_logs/README.md` 中维护索引：

```markdown
# _logs 目录索引

## 核心文档
- [迭代日志](./迭代日志.md) - 开发变更记录

## 用户文档 (docs/)
- [CLI使用说明](./docs/CLI使用说明.md)
- [工作区使用指南](./docs/工作区使用指南.md)

## 审查报告 (reports/)
- [代码库核查报告](./reports/代码库核查报告-20251231.md)
- [单元测试核查报告](./reports/单元测试核查报告-20260101.md)

## 历史归档 (archive/)
- CLI重构、功能实现、codex调研
- 讨论方案: 双语翻译、多封面等未实施方案
```

---

## 八、总结

| 项目 | 数量 |
|------|------|
| 保留在根目录 | 1 (迭代日志) |
| 迁移为用户文档 | 3 |
| 归档 | ~40 |
| 删除 | 2 |
| 需更新内容 | 4 |
