| name | aolun-prepare-docs |
| description | ⚡入口 skill。将任意输入（文本、文件路径、目录路径）转化为 aolun 分析管线可消费的标准文档结构。
支持快照模式（cp 到任务目录）和引用模式（直接读取源路径），生成索引、结构标注、搜索策略和文件完整性校验。
产出文件供 aolun-fileflow 直接消费，也可独立用于任何需要 Markdown 文档索引的场景。
English: Entry skill. Transforms any input (text, file path, directory path) into a standard document structure consumable by the aolun analysis pipeline.
Supports snapshot mode (copy to task directory) and reference mode (read source paths directly). Generates index, structural annotations, search strategies, and file integrity checksums.
Output files are consumed by aolun-fileflow, or used independently for any scenario requiring Markdown document indexing.
|
文档预处理器
"不打无准备之仗。"
—— 毛泽东
分析和攻击需要弹药。弹药不在场，再好的战术也打不响。
本 skill 的核心职责：把任意形式的输入，转化为后续分析管线可以直接消费的标准文档结构。
做完这一步，fileflow 可以拿前面已备好的弹药直接开干。
核心原则
- 只准备，不分析——本 skill 不做任何文本分析，只做文档准备和索引
- 解耦且异步——产出放到
docs/aolun.skill/ 目录，fileflow 之后消费，没有运行时依赖
- 通用——不只为分析管线服务，任何需要索引 Markdown 文档的场景都能用
Part 1：输入判断
收到输入后，按以下顺序判断形态：
1. 识别输入类型
| 输入形态 | 判断条件 | 存储模式 | 处理方式 |
|---|
| 粘贴文本 | 无路径特征 | 快照 | 原文写入 00-original.md |
| 单文件 .md 快照 | 路径指向一个 .md 文件，用户选快照 | 快照 | cp 为 00-original.md |
| 单文件 .md 引用 | 同上，用户选引用 | 引用 | 不复制，路径记录到 00-prep-meta.md |
| 目录快照 | 路径指向目录，用户选快照 | 快照 | cp -r 为 00-sources/，生成 00-index.md |
| 目录引用 | 同上，用户选引用 | 引用 | 不复制，生成 00-index.md（指向源目录） |
| 非 .md | 其他文件格式 | — | 报错提示，退出流程 |
路径判断规则：
- 以
/ 开头：绝对路径
- 以
~ 开头：家目录路径
- 以
./ 或 ../ 开头：相对路径
- 包含文件扩展名（
.md 等）且无连续段落文本特征：文件路径
- 以路径分隔符结尾：目录标识
2. 快照/引用选择
- 粘贴文本 → 默认快照（不询问）
- 单文件路径 → 询问用户："选择存储模式：[1] 快照（复制到任务目录，分析期间内容不变）[2] 引用（不复制，直接读取源文件，适合活文档）"
- 目录路径 → 同上
- 用户可预设偏好，但本 skill 不存储偏好
3. 异常处理
| 场景 | 处理 |
|---|
| 路径不存在 | 输出"文件/目录不存在：<路径>"，终止 |
| 目录为空或无 .md 文件 | 输出"目录下未找到 Markdown 文件：<路径>"，终止 |
| cp 失败（权限等） | 输出错误信息，终止 |
| 目录 > 50 个 .md 文件 | 警告"检测到 个 Markdown 文件，可能耗时较长。是否继续？[继续] [选择子集]" |
非 Markdown 文件处理规则：
遇到 .pdf、.docx 等非 Markdown 格式时，输出：
"当前仅支持 Markdown 格式（.md）的源文件。请将文件转为 Markdown 后重新提交。常见转换方式：pandoc、手动复制粘贴为 .md。"
然后终止。
Part 2：任务目录创建
1. 提取 brief
从输入文本前50字符生成任务目录的 <brief> 部分：
- 去除标点、括号、引号等特殊字符
- 空格替换为连字符
- 转小写
- 截断到约20字符
路径输入时： 从文件名或目录名提取 brief（去除扩展名，同样清洗规则）。
示例：
- 粘贴文本：
"大语言模型的 Scaling Law 已经触顶了吗？本文认为..." → da-yuyan-moxing-scaling-law
- 文件路径：
/data/game-design/combat-system.md → combat-system
- 目录路径：
/data/game-design/ → game-design
2. 创建任务目录
如果 docs/aolun.skill/ 目录不存在，先创建它。
创建任务子目录：
docs/aolun.skill/<yyyy-mm-dd>-<brief>/
3. 崩溃恢复检测
如果 docs/aolun.skill/<yyyy-mm-dd>-<brief>/00-prep-meta.md 已存在：
- 读取
00-prep-meta.md 的准备时间和输入形态
- 告知用户：
检测到已有的文档准备结果（<输入形态>，<准备时间>）。是否重新准备？[使用已有] [重新准备]
- 使用已有 → 跳到 Part 5（输出摘要）
- 重新准备 → 清空任务目录后重建
Part 3：文档准备
根据 Part 1 判断的输入形态和存储模式，执行对应的准备操作。
粘贴文本（快照）
1. 将原文写入 <任务目录>/00-original.md
- 无 header 注释，第 1 行就是原文第 1 行
2. 统计总行数
3. 计算文件 MD5
单文件 .md（快照）
1. 验证文件存在且为 .md
2. cp <源文件> <任务目录>/00-original.md
- 不添加 header 注释，保持原文行号一致
3. 统计总行数
4. 计算文件 MD5
单文件 .md（引用）
1. 验证文件存在且为 .md
2. 不复制文件
3. 统计总行数（wc -l <源文件>）
4. 计算源文件 MD5
目录（快照）
1. 验证目录存在
2. 过滤 .md 文件（跳过其他格式）
3. 如果 > 50 个 .md 文件，询问用户
4. cp -r <源目录>/ <任务目录>/00-sources/（仅 .md 文件）
5. 生成 00-index.md（见 Part 4）
6. 统计总行数
7. 计算所有 .md 文件的 MD5
目录（引用）
1. 验证目录存在
2. 过滤 .md 文件（跳过其他格式）
3. 如果 > 50 个 .md 文件，询问用户
4. 不复制文件
5. 生成 00-index.md（见 Part 4，路径指向源目录）
6. 统计总行数
7. 计算源目录下所有 .md 文件的 MD5
Part 4：索引生成
单文件模式
单文件模式下 00-index.md 可选生成（默认生成）：
# 原文索引 — <brief>
> 源文件：00-original.md（快照模式）或 <源文件绝对路径>（引用模式）
> 总行数：<N>
## 结构索引
[扫描标题/表格/公式/代码块，标注行号]
- 章节标题：搜索 "^#+ "
- 数学公式块：搜索 "$$" 或 "\\["
- 表格：搜索 "^|" 或 "表\\d"
- 代码块：搜索 "```"
## 搜索策略
<根据原文内容动态生成，见 Part 4.2>
目录模式
目录模式下 00-index.md 必须生成：
# 原文索引 — <brief>
> 源目录：00-sources/（快照模式）或 <源目录绝对路径>（引用模式）
> 文件数：<N> 个 .md 文件
> 总行数：<M>
## 文件清单
| # | 文件路径 | 行数 | 摘要（前50字符） |
|---|---------|------|--------------|
| 1 | 00-sources/index.md | 45 | 入口索引文件 |
| 2 | 00-sources/ch01-intro.md | 320 | 引言，核心声称 |
## 结构索引
[跨所有 .md 文件扫描标题/表格/公式/代码块，标注 文件名:行号]
- 章节标题：搜索 "^#+ "
- 数学公式块：搜索 "$$" 或 "\\["
- 表格：搜索 "^|" 或 "表\\d"
- 代码块：搜索 "```"
## 搜索策略
<根据原文内容动态生成，见 Part 4.2>
00-index.md 生成步骤
使用以下工具组合：
1. bash: ls <源路径或任务目录>/00-sources/*.md（或源目录） → 文件列表
2. bash: wc -l <文件列表> → 行数 + 总行数
3. grep -n '^#+ ' <文件列表> → 章节标题索引
4. grep -n '^\|' <文件列表> → 表格行号（或搜索 '表\d'）
5. grep -n '```' <文件列表> → 代码块行号
6. grep -n '\$\$' <文件列表> → 数学公式块行号
7. 对每个文件 Read 前 3-5 行 → 摘要（前50字符）
引用模式下，所有路径替换为源目录绝对路径。
引用模式 + 外部 index
如果用户的文档系统已有 index 文件，00-index.md 的文件清单部分可以引用外部 index，但结构索引（标题/公式/表格/代码块位置标注）仍由 aolun 生成（格式统一，方便 subagent 搜索）。
00-prep-meta.md 中记录外部索引路径：
- 外部索引：<用户提供路径 或 无>
4.2 搜索策略动态生成
从原文内容自动生成初版搜索策略，写入 00-prep-meta.md：
搜索策略生成规则：
1. 从 00-original.md 或 00-index.md 的结构索引中提取高频术语
- grep 所有标题中的关键词
- 统计出现频率 > 2 的术语
- 取前 10 个作为领域关键词
2. 从标题中提取核心概念
- 一级标题通常是核心声称
- 二级标题通常是子主题
3. 生成领域相关搜索策略（3-5 条）
- 每条策略包含：目标类型 + 搜索关键词
- 示例：核心声称 → 搜索"提出认为表明证明"
4. 附加跨领域通用策略（3 条固定）
- 核心声称定位：搜索 "提出"、"认为"、"表明"、"证明"
- 数据和证据定位：搜索数字、百分比模式、引用来源标记
- 定义关键术语：搜索 "所谓"、"定义为"、"是指"
5. 概念层解剖完成后，aolun-fileflow 用语义线索更新 00-todolist.md 的搜索策略
Part 5：元信息生成
生成 00-prep-meta.md
# 文档准备元信息 — <brief>
> 准备时间：<yyyy-mm-dd HH:MM>
> 输入形态：[粘贴 / 单文件快照 / 单文件引用 / 目录快照 / 目录引用]
> 存储模式：[快照 / 引用]
> 任务目录：docs/aolun.skill/<yyyy-mm-dd>-<brief>/
## 源信息
- 源路径：<绝对路径>（引用模式时有值；快照模式时可为空或记录原始路径用于溯源）
- 总行数：<自动统计>
- 文件数：<N>（目录模式时有值，单文件/粘贴时为 1）
- 外部索引：<用户提供路径 或 无>
## 文件完整性
| 文件 | MD5 | 备注时间 |
|------|-----|---------|
| 00-original.md | <hash> | <时间戳> |
| 或 00-sources/*.md | <各文件hash> | <时间戳> |
（引用模式下，hash 为源文件的 hash，非复制品）
## 搜索策略
<search-domain-specific>
由 Part 4.2 生成的领域相关搜索策略
</search-domain-specific>
<search-general>
- 核心声称定位：搜索 "提出"、"认为"、"表明"、"证明"
- 数据和证据定位：搜索数字模式、百分比、引用来源
- 定义关键术语：搜索 "所谓"、"定义为"、"是指"
</search-general>
输出摘要
完成所有准备后，向用户展示：
✓ 文档准备完成
任务目录：docs/aolun.skill/<yyyy-mm-dd>-<brief>/
输入形态：<粘贴 / 单文件快照 / 单文件引用 / 目录快照 / 目录引用>
存储模式：<快照 / 引用>
文件数：<N>
总行数：<M>
文件清单：
- 00-original.md（或 00-sources/）
- 00-index.md
- 00-prep-meta.md
下一步：将此目录路径提供给 aolun-fileflow，或直接开始分析。
Part 6：引用格式规范与 fileflow 对接
引用格式
本 skill 产出的文档结构服务于后续分析管线。引用格式在分析管线中统一使用：
| 模式 | 引用格式 | 示例 |
|---|
| 单文件 | 第<N>行："直接引用原句" | 第42行："Scaling Law 已经触顶" |
| 目录模式 | 文件名:<N>："直接引用原句" | ch02-method.md:42："Scaling Law 已经触顶" |
| 连续行范围 | 第<N>-<M>行 或 文件名:<N>-<M>："..." | 第42-45行 或 ch02.md:42-45："..." |
格式规范：行号前半角冒号 :，引用内容中文引号 ""，范围半角连字符 -。
与 aolun-fileflow 的关系
本 skill 与 fileflow 完全解耦：
- 本 skill 不知道 fileflow 的存在
- 本 skill 的产出放到
docs/aolun.skill/<date>-<brief>/ 目录
- fileflow 启动时检测到
00-prep-meta.md 已存在，跳过文档准备，直接读取元信息后创建 00-todolist.md
两者共享相同的目录结构和文件格式，但没有运行时依赖。
用户 → aolun-prepare-docs → docs/aolun.skill/<date>-<brief>/
├── 00-original.md 或 00-sources/
├── 00-index.md
└── 00-prep-meta.md
用户 → aolun-fileflow → 检测到 00-prep-meta.md？
├── 是 → 跳过文档准备，读取元信息，创建 00-todolist.md
└── 否 → 执行内联简化文档准备（仅粘贴文本场景）
