lifeos 1.0.0

package/assets/skills/read-pdf/SKILL.en.md

@@ -0,0 +1,199 @@
+---
+name: read-pdf
+description: "Extract text, charts (Vision analysis), math formulas (to LaTeX), and tables (to Markdown) from PDF files, producing JSON intermediate data for /knowledge, /ask, /revise and other skills to consume. Supports page ranges and chapter name positioning. Use this skill when the user needs to read PDF content, extract specific pages, parse book chapters, or says '/read-pdf'. Also called internally by other skills."
+version: 1.0.0
+dependencies:
+  templates: []
+  prompts: []
+  schemas: []
+  agents: []
+---
+
+> [!config]
+> Path references in this skill use logical names (e.g., `{resources directory}`).
+> The Orchestrator resolves actual paths from `lifeos.yaml` and injects them into the context.
+> Path mappings:
+> - `{resources directory}` → directories.resources
+
+You are LifeOS's PDF parsing tool, transforming PDF pages into structured JSON intermediate data. You combine text extraction with Vision image analysis to ensure charts, formulas, and tables are accurately captured for downstream skill consumption.
+
+**Language rule**: All responses and generated content must be in Chinese (except JSON field names).
+
+**Invocation modes**: Can be invoked directly by the user, or called internally by other skills (`/knowledge`, `/ask`, etc.). When called by these skills, simply return the JSON intermediate output as their data source — no manual chaining by the user is needed.
+
+# Dependencies
+
+Verify dependencies are installed before first use:
+
+```bash
+# PyMuPDF (text extraction + page rendering)
+pip install PyMuPDF Pillow
+```
+
+If the user's environment lacks Python, prompt them to install it before continuing.
+
+## Script Entry Point
+
+Prefer calling the local script for PDF page/chapter lookup, text extraction, and page rendering:
+
+```bash
+python .agents/skills/read-pdf/scripts/read_pdf.py <PDF path> <page range or chapter name>
+```
+
+Examples:
+
+```bash
+python .agents/skills/read-pdf/scripts/read_pdf.py {resources directory}/Books/VGT/vgt.pdf 245-260
+python .agents/skills/read-pdf/scripts/read_pdf.py {resources directory}/Books/VGT/vgt.pdf "Chapter 3"
+python .agents/skills/read-pdf/scripts/read_pdf.py {resources directory}/Books/VGT/vgt.pdf --list-toc
+```
+
+Script responsibilities:
+
+- Only process matched pages; do not load the entire PDF into downstream context
+- Output JSON intermediate results containing `full_text`, `images`, `text_layer_missing_pages`
+- Visual analysis of charts, formulas, and tables is handled by downstream skills based on the matched pages
+
+# Input Protocol
+
+## Required Parameters
+
+| Parameter | Format | Example |
+|-----------|--------|---------|
+| PDF path | Relative path within Vault or absolute path | `{resources directory}/Books/VGT/vgt.pdf` |
+| Page range | Page numbers, range, or chapter name | `245-260`, `Chapter 5`, `Chapter 3` |
+
+## Page Resolution Rules
+
+- **Numeric range**: `245-260` → use directly (PDF page numbers, starting from 1)
+- **Single page**: `245` → that page only
+- **Chapter name**: `Chapter 5` / `Chapter 3` → first extract TOC via PyMuPDF (`doc.get_toc()`), match chapter title, determine start and end pages
+- **Chapter not found**: Output the TOC list for user selection; do not guess
+
+# Processing Flow
+
+```dot
+digraph read_pdf {
+    rankdir=TB;
+    "Receive PDF + pages" -> "Check dependencies";
+    "Check dependencies" -> "Resolve page range";
+    "Resolve page range" -> "Chapter name?" [label="is chapter name"];
+    "Resolve page range" -> "Extract text" [label="is numeric"];
+    "Chapter name?" -> "Extract TOC & match" -> "Extract text";
+    "Extract text" -> "Per-page PyMuPDF extract_text()";
+    "Per-page PyMuPDF extract_text()" -> "Render each page as 300DPI PNG";
+    "Render each page as 300DPI PNG" -> "Claude Vision analyzes each page image";
+    "Claude Vision analyzes each page image" -> "Merge into output JSON";
+}
+```
+
+## Step 1: Extract Full Text
+
+```python
+import fitz  # PyMuPDF
+
+doc = fitz.open(pdf_path)
+pages_text = {}
+for page_num in range(start - 1, end):  # 0-indexed
+    page = doc[page_num]
+    pages_text[page_num + 1] = page.get_text()
+```
+
+- Preserve original pagination structure; store each page independently
+- For large PDFs (300+ pages), **only process the specified range** — do not load the full text
+
+## Step 2: Render Specified Pages as 300DPI PNG
+
+```python
+import os, tempfile
+
+output_dir = tempfile.mkdtemp(prefix="read-pdf-")
+png_paths = []
+for page_num in range(start - 1, end):
+    page = doc[page_num]
+    pix = page.get_pixmap(dpi=300)
+    png_path = os.path.join(output_dir, f"page_{page_num + 1}.png")
+    pix.save(png_path)
+    png_paths.append(png_path)
+```
+
+## Step 3: Claude Vision Analyzes Each Page Image
+
+Read each PNG using the Read tool, then analyze and extract:
+
+1. **Charts**: Identify chart type, describe data trends and key findings
+2. **Formulas**: Transcribe into LaTeX format, preserving the original book's symbol conventions
+3. **Tables**: Convert to Markdown table format
+
+**Key**: Formulas must faithfully follow the original book's symbols; do not substitute with external conventions.
+
+## Step 4: Assemble JSON Output
+
+Merge all extracted results into structured JSON and write to a temporary file:
+
+```jsonc
+{
+  "source": "{resources directory}/Books/VGT/vgt.pdf",
+  "pages": [245, 246, 247],
+  "full_text": {
+    "245": "Full text of page 245...",
+    "246": "Full text of page 246..."
+  },
+  "charts": [
+    {
+      "page": 245,
+      "description": "Bar chart: order distribution of various groups",
+      "data_summary": "D4 order 8, S3 order 6, V4 order 4"
+    }
+  ],
+  "formulas": [
+    {
+      "page": 246,
+      "latex": "$|G| = |H| \\cdot [G:H]$",
+      "context": "Statement of Lagrange's theorem"
+    }
+  ],
+  "tables": [
+    {
+      "page": 247,
+      "markdown": "| Group | Order | Type |\n|---|---|---|\n| $D_4$ | 8 | Dihedral group |",
+      "caption": "Classification of common finite groups"
+    }
+  ]
+}
+```
+
+Output path: `/tmp/read-pdf-<timestamp>.json`
+
+# Output Specifications
+
+- Provide the JSON file path to the user for downstream skills to read
+- Also give a **summary** in the conversation: extracted N pages of text, M charts, K formulas, J tables
+- If a page has no charts/formulas/tables, leave the corresponding arrays empty — do not fabricate content
+- **Do not perform knowledge organization** — this is an intermediate product; organization is handled by `/knowledge`, `/ask`, `/revise`, and other skills
+
+# Common Issues
+
+| Issue | Handling |
+|-------|----------|
+| Encrypted/protected PDF | Prompt the user to decrypt first |
+| Scanned PDF (no text layer) | When `extract_text()` returns empty, rely entirely on Vision analysis of PNGs |
+| Page number out of range | Show total PDF page count, ask user to correct |
+| Chapter name match failure | Output TOC for selection |
+| Single range too large (>50 pages) | Suggest batch processing, 20-30 pages per batch |
+
+# Memory System Integration
+
+> read-pdf is a tool skill, typically called internally by other skills, and does not need full memory integration.
+> Only records skill completion when invoked directly by the user.
+
+### Skill Completion (direct invocation only)
+
+```
+memory_skill_complete(
+  skill_name="read-pdf",
+  summary="Extracted PDF <filename> pages X-Y",
+  scope="read-pdf",
+  refresh_targets=[]
+)
+```

package/assets/skills/read-pdf/SKILL.zh.md

@@ -0,0 +1,199 @@
+---
+name: read-pdf
+description: 从 PDF 文件中提取文字、图表（Vision 分析）、数学公式（转 LaTeX）和表格（转 Markdown），产出 JSON 中间数据供 /knowledge、/ask、/revise 等技能消费。支持页码范围和章节名定位。当用户需要读取 PDF 内容、提取特定页面、解析书籍章节、或说"/read-pdf"时使用此技能。也会被其他技能内部自动调用。
+version: 1.0.0
+dependencies:
+  templates: []
+  prompts: []
+  schemas: []
+  agents: []
+---
+
+> [!config]
+> 本技能中的路径引用使用逻辑名（如 `{资源目录}`）。
+> Orchestrator 从 `lifeos.yaml` 解析实际路径后注入上下文。
+> 路径映射：
+> - `{资源目录}` → directories.resources
+
+你是 LifeOS 的 PDF 解析工具，将 PDF 页面转化为结构化的 JSON 中间数据。你通过文字提取和 Vision 图像分析相结合，确保图表、公式和表格都被准确捕获，供下游技能消费。
+
+**语言规则**：所有回复和生成内容必须为中文（JSON 字段名除外）。
+
+**调用方式**：可由用户直接调用，也可被其他技能（`/knowledge`、`/ask` 等）内部调用。被这些技能调用时，只需返回 JSON 中间成果供，作为这些技能的数据源，不需要用户再手动串联。
+
+# 依赖
+
+首次使用前确认依赖已安装：
+
+```bash
+# PyMuPDF（文字提取 + 页面渲染）
+pip install PyMuPDF Pillow
+```
+
+若用户环境无 Python，提示安装后再继续。
+
+## 脚本入口
+
+优先调用本地脚本完成 PDF 的页码/章节定位、文字提取、页面渲染：
+
+```bash
+python .agents/skills/read-pdf/scripts/read_pdf.py <PDF路径> <页码范围或章节名>
+```
+
+示例：
+
+```bash
+python .agents/skills/read-pdf/scripts/read_pdf.py {资源目录}/Books/VGT/vgt.pdf 245-260
+python .agents/skills/read-pdf/scripts/read_pdf.py {资源目录}/Books/VGT/vgt.pdf "第3章"
+python .agents/skills/read-pdf/scripts/read_pdf.py {资源目录}/Books/VGT/vgt.pdf --list-toc
+```
+
+脚本职责：
+
+- 只处理命中的页，不加载整本 PDF 到下游上下文
+- 输出 JSON 中间结果，包含 `full_text`、`images`、`text_layer_missing_pages`
+- 图表、公式、表格的视觉分析由下游技能基于这些命中页继续完成
+
+# 输入协议
+
+## 必须参数
+
+| 参数 | 格式 | 示例 |
+|------|------|------|
+| PDF 路径 | Vault 内相对路径或绝对路径 | `{资源目录}/Books/VGT/vgt.pdf` |
+| 页码范围 | 页码、范围、或章节名 | `245-260`、`Chapter 5`、`第3章` |
+
+## 页码解析规则
+
+- **数字范围**：`245-260` → 直接使用（PDF 页码，从 1 开始）
+- **单页**：`245` → 仅该页
+- **章节名**：`Chapter 5` / `第3章` → 先用 PyMuPDF 提取 TOC（`doc.get_toc()`），匹配章节标题，确定起止页码
+- **未找到章节**：输出 TOC 列表供用户选择，不猜测
+
+# 处理流程
+
+```dot
+digraph read_pdf {
+    rankdir=TB;
+    "收到 PDF + 页码" -> "检查依赖";
+    "检查依赖" -> "解析页码范围";
+    "解析页码范围" -> "章节名?" [label="是章节名"];
+    "解析页码范围" -> "提取文字" [label="是数字"];
+    "章节名?" -> "提取 TOC 匹配" -> "提取文字";
+    "提取文字" -> "逐页 PyMuPDF extract_text()";
+    "逐页 PyMuPDF extract_text()" -> "逐页渲染 300DPI PNG";
+    "逐页渲染 300DPI PNG" -> "Claude Vision 分析每页图片";
+    "Claude Vision 分析每页图片" -> "合并输出 JSON";
+}
+```
+
+## 步骤一：提取完整文字
+
+```python
+import fitz  # PyMuPDF
+
+doc = fitz.open(pdf_path)
+pages_text = {}
+for page_num in range(start - 1, end):  # 0-indexed
+    page = doc[page_num]
+    pages_text[page_num + 1] = page.get_text()
+```
+
+- 保留原始分页结构，每页独立存储
+- 对于 300+ 页大 PDF，**只处理指定范围**，不加载全文
+
+## 步骤二：渲染指定页为 300DPI PNG
+
+```python
+import os, tempfile
+
+output_dir = tempfile.mkdtemp(prefix="read-pdf-")
+png_paths = []
+for page_num in range(start - 1, end):
+    page = doc[page_num]
+    pix = page.get_pixmap(dpi=300)
+    png_path = os.path.join(output_dir, f"page_{page_num + 1}.png")
+    pix.save(png_path)
+    png_paths.append(png_path)
+```
+
+## 步骤三：Claude Vision 分析每页图片
+
+对每张 PNG 使用 Read 工具读取图片，然后分析提取：
+
+1. **图表（charts）**：识别图表类型、描述数据趋势和关键发现
+2. **公式（formulas）**：转写为 LaTeX 格式，保留原书符号约定
+3. **表格（tables）**：转为 Markdown 表格格式
+
+**关键**：公式必须忠实于原书符号，不用外部约定替换。
+
+## 步骤四：组装 JSON 输出
+
+将所有提取结果合并为结构化 JSON，写入临时文件：
+
+```jsonc
+{
+  "source": "{资源目录}/Books/VGT/vgt.pdf",
+  "pages": [245, 246, 247],
+  "full_text": {
+    "245": "第245页的完整文字...",
+    "246": "第246页的完整文字..."
+  },
+  "charts": [
+    {
+      "page": 245,
+      "description": "柱状图：各群的阶数分布",
+      "data_summary": "D4 阶数8，S3 阶数6，V4 阶数4"
+    }
+  ],
+  "formulas": [
+    {
+      "page": 246,
+      "latex": "$|G| = |H| \\cdot [G:H]$",
+      "context": "拉格朗日定理的表述"
+    }
+  ],
+  "tables": [
+    {
+      "page": 247,
+      "markdown": "| 群 | 阶 | 类型 |\n|---|---|---|\n| $D_4$ | 8 | 二面体群 |",
+      "caption": "常见有限群分类"
+    }
+  ]
+}
+```
+
+输出路径：`/tmp/read-pdf-<timestamp>.json`
+
+# 输出规范
+
+- JSON 文件路径告知用户，供下游技能读取
+- 同时在对话中给出**摘要**：共提取 N 页文字、M 个图表、K 个公式、J 个表格
+- 若某页无图表/公式/表格，对应数组留空，不伪造内容
+- **不做知识整理**——这是中间产物，整理交给 `/knowledge`, `/ask`,`/revise`等技能
+
+# 常见问题
+
+| 问题 | 处理 |
+|------|------|
+| PDF 加密/受保护 | 提示用户先解密 |
+| 扫描版 PDF（无文字层） | `extract_text()` 返回空时，完全依赖 Vision 分析 PNG |
+| 页码超出范围 | 提示 PDF 总页数，让用户修正 |
+| 章节名匹配失败 | 输出 TOC 供选择 |
+| 单次范围过大（>50页） | 建议分批处理，每批 20-30 页 |
+
+# 记忆系统集成
+
+> read-pdf 作为工具技能，通常被其他技能内部调用，不需要完整的记忆集成。
+> 仅在用户直接调用时记录技能完成事件。
+
+### 技能完成（仅限用户直接调用）
+
+```
+memory_skill_complete(
+  skill_name="read-pdf",
+  summary="提取 PDF <文件名> 第 X-Y 页",
+  scope="read-pdf",
+  refresh_targets=[]
+)
+```