支持增量编译wiki

skills/SKILL.md

@@ -12,29 +12,95 @@
 
 ---
 
+## 1.5 大文档处理要求
+
+对于篇幅较长的 raw 文档（如学术论文、长篇技术文章），**必须完整阅读和分析**，不得仅基于开头部分生成简短摘要。
+
+### 具体要求：
+
+1. **完整内容获取**：
+   - 使用 Grep 搜索章节标题（如 `^#{1,3} `）了解文档结构
+   - 分段读取完整内容，确保覆盖所有主要章节
+   - 特别关注：摘要、引言、方法、实验、讨论、结论、附录等核心章节
+
+2. **深度分析维度**：
+   - **核心论点**：提取文章的主要主张和关键发现
+   - **方法细节**：理解技术方案的实现细节和设计决策
+   - **实验结果**：完整记录所有实验数据、表格、图表信息
+   - **案例研究**：保留具体的定性示例和应用场景
+   - **相关工作**：建立与其他研究的联系和对比
+
+3. **输出内容标准**：
+   - wiki 页面长度应与原文档的重要性和复杂度相匹配
+   - 学术论文应包含：摘要、核心方法、完整实验结果、详细讨论
+   - 技术文章应包含：问题背景、完整解决方案、实际应用案例
+   - 保留所有定量数据（表格、指标、分数等）
+
+4. **例外情况**：
+   - 仅在以下情况下可生成较短摘要：
+     - 文档是纯新闻报道或简短公告
+     - 文档主要是代码或配置（无大量叙事内容）
+     - 用户明确要求仅生成摘要
+
+---
+
 ## 2. 标准文件系统架构
 严格遵循 I/O 分离原则，确保知识库的纯净度与可迁移性：
 
 ```text
 📁 wikillm
 ├── 📁 raw/               # 【输入层】原始素材（只读）
+│   └── 📁 images/        # 原始图片文件（png, jpg, webp, gif, svg 等）
 └── 📁 wiki/              # 【输出层】编译器生成的知识产物
     ├── 📁 concepts/      # 核心概念、原理分析
     ├── 📁 practices/     # 部署指南、最佳实践
     ├── 📁 visual/        # Marp 幻灯片、Matplotlib 趋势图
     ├── 📁 queries/       # 高价值 Q&A 的沉淀归档
+    ├── 📁 assets/        # 图像和资源文件（从 raw/images/ 同步而来）
     ├── INDEX.md          # 动态索引与学习路径
-    └── Glossary.md       # 统一术语表与双链枢纽
+    ├── Glossary.md       # 统一术语表与双链枢纽
+    └── sources.md        # 来源文档索引（原始 URL 列表）
 ```
 
 ---
 
 ## 3. 核心工作流 (The "Compilation" Loop)
 
+### 阶段 0：增量检查 (Incremental Check)
+* **任务**：检查 `raw/` 目录下哪些文件需要编译。
+* **读取状态**：读取 `wiki/compile-results.tsv`，获取已编译文件的哈希记录。
+* **扫描文件**：遍历 `raw/` 目录，计算每个文件的 SHA-256 哈希。
+* **识别变更**：对比哈希值，识别：
+  - **新增文件**：在 `compile-results.tsv` 中不存在的文件
+  - **修改文件**：哈希值与记录不同的文件
+  - **未修改文件**：哈希值相同的文件（跳过编译）
+* **记录日志**：将检查过程写入 `wiki/compile.log`。
+
+### 阶段 0.5：资源同步 (Asset Sync)
+* **任务**：将 `raw/images/` 下的所有图片资源同步到 `wiki/assets/`。
+* **同步范围**：所有图像文件，包括但不限于：
+  - `png`, `jpg`, `jpeg`, `gif`, `webp`, `svg`
+* **同步方式**：
+  - 使用 `cp -r raw/images/* wiki/assets/` 进行完整同步
+  - `raw/images/` 是权威来源，同名文件直接覆盖
+  - 保留原始文件名（包括空格和特殊字符）
+* **验证**：确保 `wiki/assets/` 包含 `raw/images/` 中的所有文件
+* **时机**：每次编译前必须执行此步骤
+
 ### 阶段 1：多模态解构 (Ingest & Analyze)
-* **任务**：解析 `raw/` 目录下的新增内容。
+* **任务**：解析 `raw/` 目录下的新增或修改内容。
+* **大文档完整阅读**：对于篇幅较长的文档（学术论文、长篇技术文章），必须完整阅读和分析：
+  - 首先用 Grep 搜索章节标题（如 `^#{1,3} `）了解文档结构
+  - 分段读取完整内容，确保覆盖所有主要章节
+  - 特别关注：摘要、引言、方法、实验、讨论、结论、附录等核心章节
 * **视觉解析**：对图片进行深度 OCR 与逻辑识别。将架构图转化为文字描述及 **Mermaid** 代码块，存入对应 Wiki 页面。
-* **元数据提取**：为每篇文档生成 YAML Frontmatter（包含：`tags`, `source`, `confidence_score`, `last_updated`）。
+* **元数据提取**：为每篇文档生成 YAML Frontmatter（包含：`tags`, `source`, `raw_sources`, `confidence_score`, `last_updated`）。
+  - `raw_sources` 字段：记录源文件路径和哈希值，格式如下：
+    ```yaml
+    raw_sources:
+      - path: raw/anthropic-harness-design.md
+        hash: "sha256:abc123..."
+    ```
 
 ### 阶段 2：增量编译 (Incremental Writing)
 * **非线性重构**：不进行 1:1 翻译，而是基于源文档的“核心贡献”进行重写。
@@ -67,10 +133,16 @@
 * **动态索引**：根据新增内容，自动更新 `INDEX.md` 中的”最新研究”与”学习路径”部分。
 
 ### 阶段 4：健康检查与维护 (Linting)
-* **一致性检查**：扫描 `wiki/`，发现术语冲突（如 A 文档叫“智能体”，B 文档叫“代理”）时，自动统一。
+* **一致性检查**：扫描 `wiki/`，发现术语冲突（如 A 文档叫”智能体”，B 文档叫”代理”）时，自动统一。
 * **孤岛扫描**：识别没有任何链接指向的页面，强制将其挂载到导航树中。
 * **补丁发布**：当 `raw/` 有新版本（如论文更新）时，在对应 Wiki 页面顶部发布 `[Update Patch]` 摘要。
 
+### 阶段 5：来源索引更新 (Sources Update)
+* **任务**：更新 `wiki/sources.md`，记录本次编译涉及的来源文档。
+* **格式规范**：使用简单无序列表，每项格式为 `- [标题](URL)`
+* **增量更新**：添加本次新增的来源，保持已有来源不变
+* **分类组织**：按”学术论文”、”概念文章”、”实践指南”等类别合理分组
+
 ---
 
 ## 4. 输出质量标准 (The Gold Standard)
@@ -102,6 +174,7 @@
 ## 6. 执行清单 (Checklist)
 
 * [ ] **Raw Check**: `raw/` 目录中是否包含待处理的新素材（图片/文档）？
+* [ ] **Asset Sync**: `raw/images/` 下的所有图片是否已同步到 `wiki/assets/`？
 * [ ] **Glossary Lock**: 是否已锁定全局术语表，确保翻译不漂移？
 * [ ] **Multimodal Sync**: 图片是否已转化为可编辑的文字解析/Mermaid？
 * [ ] **文件名规范**: 所有 wiki 页面文件是否使用 kebab-case（连字符分隔）命名？
@@ -112,7 +185,67 @@
 
 ---
 
-## 7. 最佳实践提示
-* **手离开键盘**：不要手动修改 `wiki/` 目录下的内容，所有的修改应通过“向 LLM 发出 Lint 任务”或“添加 raw 素材后重新编译”来完成。
-* **搜索即创作**：把每一次对知识库的提问看作是一次“知识合成”，务必将高质量的回答存回库中。
-* **结构化思考**：在生成任何长篇文档前，先让 LLM 在内存中构建该主题的“概念地图”。
+## 7. 增量编译工作流
+
+### 编译状态文件
+
+项目使用三个核心文件来追踪编译状态：
+
+1. **`wiki/compile-results.tsv`** - 结构化的编译结果（TSV 格式）
+   - 字段：`raw_path`、`hash`、`last_modified`、`wiki_paths`、`compile_time`、`status`
+   - 记录每个 raw 文件的编译状态和生成的 wiki 文档
+
+2. **`wiki/compile.log`** - 详细的编译日志
+   - 记录每次编译的输入、输出、决策过程
+   - 用于调试、审查和回溯
+
+3. **`wiki/sources.md`** - 来源文档索引
+   - 记录所有原始来源的标题和 URL
+   - 格式：`- [标题](URL)` 的无序列表
+   - 按"学术论文"、"概念文章"、"实践指南"等分类组织
+   - 每次增量编译后更新
+
+### Wiki 文档元数据
+
+每个 wiki 文档的 YAML frontmatter 都包含 `raw_sources` 字段：
+```yaml
+---
+title: 文档标题
+source: [来源名称]
+raw_sources:
+  - path: raw/source-file.md
+    hash: “sha256:abc123...”
+---
+```
+
+### 常用命令
+
+```bash
+# 查看所有已编译文件
+cat wiki/compile-results.tsv
+
+# 查找特定文件的编译状态
+grep “raw/xxx.md” wiki/compile-results.tsv
+
+# 查看最近的编译日志
+tail -100 wiki/compile.log
+
+# 查看上次编译摘要
+grep “=== 编译完成 ===” -A 5 wiki/compile.log
+```
+
+### 增量编译检查清单
+
+* [ ] **扫描检查**：运行扫描，检查 `raw/` 目录中是否有新增或修改的文件
+* [ ] **哈希对比**：与 `compile-results.tsv` 中的记录对比，确认变更
+* [ ] **日志记录**：将检查过程写入 `compile.log`
+* [ ] **只编译变更**：仅处理新增或修改的文件
+* [ ] **更新 frontmatter**：确保新编译的 wiki 文档包含 `raw_sources`
+* [ ] **更新状态文件**：追加/更新 `compile-results.tsv` 中的记录
+* [ ] **更新来源索引**：更新 `sources.md`，添加本次新增的来源
+
+## 8. 最佳实践提示
+* **手离开键盘**：不要手动修改 `wiki/` 目录下的内容，所有的修改应通过”向 LLM 发出 Lint 任务”或”添加 raw 素材后重新编译”来完成。
+* **搜索即创作**：把每一次对知识库的提问看作是一次”知识合成”，务必将高质量的回答存回库中。
+* **结构化思考**：在生成任何长篇文档前，先让 LLM 在内存中构建该主题的”概念地图”。
+* **利用编译日志**：遇到问题时，先查看 `wiki/compile.log` 了解之前的编译过程。