lifeos 1.0.0

package/assets/skills/read-pdf/scripts/read_pdf.py

@@ -0,0 +1,354 @@
+#!/usr/bin/env python3
+"""读取 PDF 指定页码或章节，并输出结构化 JSON 中间结果。"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+import tempfile
+import unicodedata
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+import fitz
+
+
+MAX_DEFAULT_PAGES = 50
+
+
+@dataclass
+class ChapterMatch:
+    level: int
+    title: str
+    start_page: int
+    end_page: int
+
+
+class ReadPdfError(Exception):
+    """用于向 CLI 返回可读错误信息。"""
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="按页码范围或章节名提取 PDF 内容，并输出 JSON 文件。"
+    )
+    parser.add_argument("pdf_path", help="PDF 路径，支持 Vault 相对路径或绝对路径")
+    parser.add_argument(
+        "target",
+        nargs="?",
+        help="页码范围、单页、逗号列表，或章节名，例如 245-260 / 245 / 245,247-249 / 第3章",
+    )
+    parser.add_argument(
+        "--output",
+        help="输出 JSON 路径；默认写入 /tmp/read-pdf-时间戳.json",
+    )
+    parser.add_argument(
+        "--images-dir",
+        help="页面 PNG 输出目录；默认写入临时目录",
+    )
+    parser.add_argument(
+        "--dpi",
+        type=int,
+        default=300,
+        help="页面渲染 DPI，默认 300",
+    )
+    parser.add_argument(
+        "--skip-render",
+        action="store_true",
+        help="只提取文字，不渲染页面 PNG",
+    )
+    parser.add_argument(
+        "--list-toc",
+        action="store_true",
+        help="列出 PDF TOC 并退出",
+    )
+    parser.add_argument(
+        "--max-pages",
+        type=int,
+        default=MAX_DEFAULT_PAGES,
+        help=f"单次允许处理的最大页数，默认 {MAX_DEFAULT_PAGES}",
+    )
+    parser.add_argument(
+        "--force-large-range",
+        action="store_true",
+        help="允许处理超过 --max-pages 的范围",
+    )
+    return parser.parse_args()
+
+
+def normalize_text(value: str) -> str:
+    normalized = unicodedata.normalize("NFKC", value).strip().lower()
+    normalized = re.sub(r"\s+", "", normalized)
+    return normalized
+
+
+def resolve_pdf_path(raw_path: str, cwd: Path) -> Path:
+    candidate = Path(raw_path)
+    if not candidate.is_absolute():
+        candidate = (cwd / candidate).resolve()
+    if not candidate.exists():
+        raise ReadPdfError(f"找不到 PDF 文件：{raw_path}")
+    if candidate.suffix.lower() != ".pdf":
+        raise ReadPdfError(f"目标文件不是 PDF：{candidate}")
+    return candidate
+
+
+def get_toc_entries(doc: fitz.Document) -> List[Tuple[int, str, int]]:
+    toc = doc.get_toc(simple=True)
+    return [(int(level), str(title), int(page)) for level, title, page in toc]
+
+
+def dump_toc(doc: fitz.Document) -> None:
+    toc = [
+        {"level": level, "title": title, "page": page}
+        for level, title, page in get_toc_entries(doc)
+    ]
+    print(json.dumps(toc, ensure_ascii=False, indent=2))
+
+
+def parse_page_token(token: str, page_count: int) -> List[int]:
+    token = token.strip()
+    if not token:
+        return []
+    if "-" in token:
+        start_str, end_str = token.split("-", 1)
+        if not start_str.isdigit() or not end_str.isdigit():
+            raise ReadPdfError(f"非法页码范围：{token}")
+        start = int(start_str)
+        end = int(end_str)
+        if start > end:
+            raise ReadPdfError(f"页码范围起点大于终点：{token}")
+        return validate_pages(list(range(start, end + 1)), page_count)
+    if not token.isdigit():
+        raise ReadPdfError(f"非法页码：{token}")
+    return validate_pages([int(token)], page_count)
+
+
+def validate_pages(pages: Sequence[int], page_count: int) -> List[int]:
+    invalid_pages = [page for page in pages if page < 1 or page > page_count]
+    if invalid_pages:
+        raise ReadPdfError(
+            f"页码超出范围：{invalid_pages}。PDF 总页数为 {page_count}。"
+        )
+    return list(pages)
+
+
+def parse_page_spec(spec: str, page_count: int) -> Optional[List[int]]:
+    compact = spec.replace(" ", "")
+    if not compact or not re.fullmatch(r"[\d,\-]+", compact):
+        return None
+    pages: List[int] = []
+    for token in compact.split(","):
+        pages.extend(parse_page_token(token, page_count))
+    return sorted(set(pages))
+
+
+def resolve_chapter(doc: fitz.Document, query: str) -> ChapterMatch:
+    toc_entries = get_toc_entries(doc)
+    if not toc_entries:
+        raise ReadPdfError("PDF 没有目录信息，无法按章节匹配。可改用页码范围。")
+
+    normalized_query = normalize_text(query)
+    exact_matches: List[Tuple[int, str, int, int]] = []
+    fuzzy_matches: List[Tuple[int, str, int, int]] = []
+
+    for index, (level, title, start_page) in enumerate(toc_entries):
+        normalized_title = normalize_text(title)
+        if not normalized_title:
+            continue
+        end_page = doc.page_count
+        for next_level, _next_title, next_page in toc_entries[index + 1 :]:
+            if next_level <= level:
+                end_page = next_page - 1
+                break
+        entry = (level, title, start_page, end_page)
+        if normalized_title == normalized_query:
+            exact_matches.append(entry)
+        elif normalized_query in normalized_title or normalized_title in normalized_query:
+            fuzzy_matches.append(entry)
+
+    matches = exact_matches or fuzzy_matches
+    if not matches:
+        preview = [
+            {"level": level, "title": title, "page": page}
+            for level, title, page in toc_entries[:20]
+        ]
+        raise ReadPdfError(
+            "未找到匹配章节。你可以先用 --list-toc 查看目录，或参考这些条目：\n"
+            + json.dumps(preview, ensure_ascii=False, indent=2)
+        )
+    if len(matches) > 1:
+        candidates = [
+            {"level": level, "title": title, "start_page": start_page, "end_page": end_page}
+            for level, title, start_page, end_page in matches[:10]
+        ]
+        raise ReadPdfError(
+            "匹配到多个章节，请改用更精确的章节名：\n"
+            + json.dumps(candidates, ensure_ascii=False, indent=2)
+        )
+
+    level, title, start_page, end_page = matches[0]
+    return ChapterMatch(level=level, title=title, start_page=start_page, end_page=end_page)
+
+
+def render_pages(
+    doc: fitz.Document,
+    pages: Sequence[int],
+    dpi: int,
+    images_dir: Optional[Path],
+) -> Tuple[Path, List[Dict[str, Any]]]:
+    target_dir = images_dir
+    if target_dir is None:
+        target_dir = Path(tempfile.mkdtemp(prefix="read-pdf-pages-"))
+    else:
+        target_dir.mkdir(parents=True, exist_ok=True)
+
+    images: List[Dict[str, Any]] = []
+    for page_number in pages:
+        page = doc[page_number - 1]
+        pix = page.get_pixmap(dpi=dpi)
+        image_path = target_dir / f"page_{page_number}.png"
+        pix.save(str(image_path))
+        images.append({"page": page_number, "path": str(image_path)})
+    return target_dir, images
+
+
+def extract_text(doc: fitz.Document, pages: Sequence[int]) -> Tuple[Dict[str, str], List[int]]:
+    full_text: Dict[str, str] = {}
+    missing_text_pages: List[int] = []
+    for page_number in pages:
+        text = doc[page_number - 1].get_text("text")
+        full_text[str(page_number)] = text
+        if not text.strip():
+            missing_text_pages.append(page_number)
+    return full_text, missing_text_pages
+
+
+def build_output_path(raw_output: Optional[str]) -> Path:
+    if raw_output:
+        output_path = Path(raw_output)
+        if not output_path.is_absolute():
+            output_path = (Path.cwd() / output_path).resolve()
+    else:
+        timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+        output_path = Path(f"/tmp/read-pdf-{timestamp}.json")
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    return output_path
+
+
+def build_result(
+    pdf_input: str,
+    resolved_pdf_path: Path,
+    pages: Sequence[int],
+    full_text: Dict[str, str],
+    images: Sequence[Dict[str, Any]],
+    missing_text_pages: Sequence[int],
+    target: str,
+    doc: fitz.Document,
+    chapter_match: Optional[ChapterMatch],
+) -> Dict[str, Any]:
+    result: Dict[str, Any] = {
+        "source": pdf_input,
+        "resolved_path": str(resolved_pdf_path),
+        "target": target,
+        "page_count": doc.page_count,
+        "pages": list(pages),
+        "full_text": full_text,
+        "images": list(images),
+        "charts": [],
+        "formulas": [],
+        "tables": [],
+        "text_layer_missing_pages": list(missing_text_pages),
+        "generated_at": datetime.now().isoformat(timespec="seconds"),
+    }
+    if chapter_match:
+        result["mode"] = "chapter"
+        result["chapter"] = {
+            "level": chapter_match.level,
+            "title": chapter_match.title,
+            "start_page": chapter_match.start_page,
+            "end_page": chapter_match.end_page,
+        }
+    else:
+        result["mode"] = "pages"
+    return result
+
+
+def ensure_page_limit(pages: Sequence[int], max_pages: int, force_large_range: bool) -> None:
+    if len(pages) <= max_pages or force_large_range:
+        return
+    raise ReadPdfError(
+        f"本次命中 {len(pages)} 页，超过限制 {max_pages} 页。"
+        "建议拆分批次，或显式传入 --force-large-range。"
+    )
+
+
+def main() -> int:
+    args = parse_args()
+    if not args.target and not args.list_toc:
+        print("错误：缺少 target。请提供页码范围、单页、逗号列表，或章节名。", file=sys.stderr)
+        return 2
+
+    try:
+        resolved_pdf_path = resolve_pdf_path(args.pdf_path, Path.cwd())
+        with fitz.open(str(resolved_pdf_path)) as doc:
+            if args.list_toc:
+                dump_toc(doc)
+                return 0
+
+            page_spec = parse_page_spec(args.target, doc.page_count)
+            chapter_match: Optional[ChapterMatch] = None
+            if page_spec is None:
+                chapter_match = resolve_chapter(doc, args.target)
+                pages = list(range(chapter_match.start_page, chapter_match.end_page + 1))
+            else:
+                pages = page_spec
+
+            ensure_page_limit(pages, args.max_pages, args.force_large_range)
+            full_text, missing_text_pages = extract_text(doc, pages)
+
+            images: List[Dict[str, Any]] = []
+            if not args.skip_render:
+                images_dir = Path(args.images_dir).resolve() if args.images_dir else None
+                _, images = render_pages(doc, pages, args.dpi, images_dir)
+
+            result = build_result(
+                pdf_input=args.pdf_path,
+                resolved_pdf_path=resolved_pdf_path,
+                pages=pages,
+                full_text=full_text,
+                images=images,
+                missing_text_pages=missing_text_pages,
+                target=args.target,
+                doc=doc,
+                chapter_match=chapter_match,
+            )
+
+        output_path = build_output_path(args.output)
+        output_path.write_text(
+            json.dumps(result, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+
+        print(f"已输出 JSON：{output_path}")
+        print(
+            "摘要："
+            f"共处理 {len(result['pages'])} 页，"
+            f"渲染 {len(result['images'])} 张图片，"
+            f"缺少文字层页数 {len(result['text_layer_missing_pages'])}。"
+        )
+        return 0
+    except ReadPdfError as exc:
+        print(f"错误：{exc}", file=sys.stderr)
+        return 2
+    except Exception as exc:  # pragma: no cover
+        print(f"未预期错误：{exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/skills/research/SKILL.en.md

@@ -0,0 +1,107 @@
+---
+name: research
+description: "Conduct deep research on a specified topic or draft, producing structured research reports to {research directory}/. Uses dual-Agent workflow: the Planning Agent scans local drafts, matches expert personas, and creates a `type: plan, status: active` research plan; the Execution Agent combines local drafts with WebSearch external sources to write the report and updates the plan to `status: done`. Supports topic mode (direct topic) and file mode (draft as anchor). Use this skill when the user wants to deeply understand a topic, needs systematic research, wants to expand a draft into a full report, or says '/research'."
+version: 1.0.0
+dependencies:
+  templates: []
+  prompts:
+    - path: "{system directory}/Prompts/"
+      scan: true
+      when: "Planning Agent matches expert persona by domain"
+  schemas:
+    - path: "{system directory}/{schema subdirectory}/Frontmatter_Schema.md"
+  agents:
+    - path: references/planning-agent-prompt.md
+      role: planning
+    - path: references/execution-agent-prompt.md
+      role: execution
+---
+> [!config]
+> Path references in this skill use logical names (e.g., `{research directory}`).
+> The Orchestrator resolves actual paths from `lifeos.yaml` and injects them into the context.
+> Path mappings:
+> - `{drafts directory}` → directories.drafts
+> - `{diary directory}` → directories.diary
+> - `{research directory}` → directories.research
+> - `{plans directory}` → directories.plans
+> - `{system directory}` → directories.system
+> - `{templates subdirectory}` → subdirectories.system.templates
+> - `{schema subdirectory}` → subdirectories.system.schema
+> - `{archived plans subdirectory}` → subdirectories.system.archive.plans
+
+You are LifeOS's deep research orchestrator, responsible for coordinating the Planning Agent and Execution Agent to complete systematic research. You ensure research has a clear scope, appropriate expert persona, fully leverages local drafts as first-hand sources, and combines external search to produce high-quality reports.
+
+# Phase 0: Memory Pre-check (Required)
+
+Follow `_shared/dual-agent-orchestrator.en.md` Phase 0, with entity type `filters.type = "research"`.
+
+# Workflow Overview
+
+| Phase   | Actor              | Responsibility                                           |
+| ------- | ------------------ | -------------------------------------------------------- |
+| Phase 1 | Planning Agent     | Scan local drafts, formulate research strategy, generate plan file |
+| Phase 2 | Orchestrator (you) | Ask user clarification questions, wait for confirmation  |
+| Phase 3 | Execution Agent    | Execute research per the plan, write report, and update the plan to `status: done` |
+
+# Your Responsibilities as Orchestrator
+
+Follow the standard orchestration flow in `_shared/dual-agent-orchestrator.en.md`. The following are additional responsibilities specific to the research skill:
+
+- During Phase 2 (user review), you directly ask the user clarification questions in the conversation, write answers into the plan file, then prompt the user to review and confirm
+
+# Input Context
+
+| Trigger mode | Example                                    | Description                                  |
+| ------------ | ------------------------------------------ | -------------------------------------------- |
+| Topic mode   | `/research React Server Components`        | Topic-centric research, drafts as local supplement |
+| File mode    | `/research {drafts directory}/AI_Agent_Thoughts.md` | Specified draft as core anchor, expanding outward |
+
+# Phase 1: Launch Planning Agent
+
+Follow `_shared/dual-agent-orchestrator.en.md` Phase 1. Replace the placeholder `[user's input]` with the user's actual input.
+
+After the Planning Agent returns, **directly** ask the user in the conversation:
+
+```
+I've created a research plan for "[Topic]" at: `[plan file path]`
+
+Please answer the following questions, and I'll write them into the plan before starting execution:
+
+1. What is your current familiarity with this topic? (Beginner / Intermediate / Advanced)
+2. Do you prefer theoretical understanding or example-driven practice?
+```
+
+After receiving answers:
+
+1. Write the answers into the "Clarification Question Answers" section of the plan file
+2. If the Domain in the plan is TBD, additionally ask about the domain
+3. Prompt the user to review the plan, wait for confirmation
+
+# Phase 2: Launch Execution Agent (After User Confirmation)
+
+Follow `_shared/dual-agent-orchestrator.en.md` Phase 3.
+
+# Edge Cases
+
+| Situation               | Handling                                                    |
+| ----------------------- | ----------------------------------------------------------- |
+| Topic too broad         | Planning Agent splits into subtopics and marks priority     |
+| Existing related research | Update the existing report, do not create a duplicate file |
+| Specified draft doesn't exist | Prompt user to confirm path, or switch to TOPIC MODE  |
+| No related drafts       | Proceed normally; "Core Insights from Drafts" section notes "No local drafts" |
+| WebSearch returns nothing | Rely on local drafts, note limitations in the report      |
+| WebFetch fails          | Mark in "References" as "(link inaccessible, for reference only)" |
+
+# Follow-up Handling
+
+When the user requests additions/modifications: edit the existing research report file directly, do not create duplicate files.
+
+After execution, the plan file remains in `{plans directory}/` with status `done`, waiting for `/archive` to move it into `{archived plans subdirectory}`.
+
+# Memory System Integration
+
+> Common protocols (file change notification, skill completion, session wrap-up) are documented in `_shared/memory-protocol.md`. Only skill-specific queries and behaviors are listed below.
+
+### Pre-query
+
+See Phase 0 for query code.

package/assets/skills/research/SKILL.zh.md

@@ -0,0 +1,107 @@
+---
+name: research
+description: 对指定主题或草稿进行深度研究，产出结构化研究报告到 {研究目录}/。使用双 Agent 工作流：规划 Agent 扫描本地草稿、匹配专家人格、生成 `type: plan, status: active` 的研究计划；执行 Agent 结合本地草稿与 WebSearch 外部资料撰写报告，并将计划更新为 `status: done`。支持主题模式（直接给主题）和文件模式（以草稿为锚点展开）。当用户想深入了解某个主题、需要系统性调研、想把草稿扩展为完整报告、或说"/research"时使用此技能。
+version: 1.0.0
+dependencies:
+  templates: []
+  prompts:
+    - path: "{系统目录}/提示词/"
+      scan: true
+      when: "Planning Agent 按 domain 匹配专家人格"
+  schemas:
+    - path: "{系统目录}/{规范子目录}/Frontmatter_Schema.md"
+  agents:
+    - path: references/planning-agent-prompt.md
+      role: planning
+    - path: references/execution-agent-prompt.md
+      role: execution
+---
+> [!config]
+> 本技能中的路径引用使用逻辑名（如 `{研究目录}`）。
+> Orchestrator 从 `lifeos.yaml` 解析实际路径后注入上下文。
+> 路径映射：
+> - `{草稿目录}` → directories.drafts
+> - `{日记目录}` → directories.diary
+> - `{研究目录}` → directories.research
+> - `{计划目录}` → directories.plans
+> - `{系统目录}` → directories.system
+> - `{模板子目录}` → subdirectories.system.templates
+> - `{规范子目录}` → subdirectories.system.schema
+> - `{归档计划子目录}` → subdirectories.system.archive.plans
+
+你是 LifeOS 的深度研究编排者，负责协调规划 Agent 和执行 Agent 完成系统性研究。你确保研究有明确的范围、合适的专家人格、充分利用本地草稿作为第一手资料，并结合外部搜索产出高质量报告。
+
+# 阶段0：记忆前置检查（必须）
+
+按 `_shared/dual-agent-orchestrator.zh.md` 阶段0 执行，实体类型 `filters.type = “research”`。
+
+# 工作流概述
+
+| 阶段    | 执行者             | 职责                                     |
+| ------- | ------------------ | ---------------------------------------- |
+| Phase 1 | Planning Agent     | 扫描本地草稿、制定研究策略、生成计划文件 |
+| Phase 2 | Orchestrator（你） | 向用户提出澄清问题、等待确认             |
+| Phase 3 | Execution Agent    | 按计划执行研究、撰写报告，并将计划更新为 `status: done` |
+
+# 你作为 Orchestrator 的职责
+
+按 `_shared/dual-agent-orchestrator.zh.md` 的标准编排流程执行，以下为研究技能的额外职责：
+
+- 阶段2（用户审核）中，你在对话中直接向用户提出澄清问题，收到回答后写入计划文件，再提示用户审核确认
+
+# 输入上下文
+
+| 触发方式 | 示例                                 | 说明                             |
+| -------- | ------------------------------------ | -------------------------------- |
+| 主题模式 | `/research React Server Components`  | 以主题为核心展开，草稿为本地补充 |
+| 文件模式 | `/research {草稿目录}/AI_Agent_思考.md` | 以指定草稿为核心锚点，向外延伸   |
+
+# 阶段1：启动 Planning Agent
+
+按 `_shared/dual-agent-orchestrator.zh.md` 阶段1 执行。占位符 `[user's input]` 替换为用户实际输入。
+
+Planning Agent 返回后，在**对话中直接**向用户提问：
+
+```
+我已为「[主题]」制定了研究计划，路径：`[plan file path]`
+
+请回答以下问题，我将写入计划后开始执行：
+
+1. 你目前对该主题的了解程度？（初级 / 中级 / 高级）
+2. 你更偏向理论理解，还是示例驱动的实践？
+```
+
+收到回答后：
+
+1. 将答案写入计划文件的「澄清问题回答」区块
+2. 若计划中 Domain 为 TBD，额外追问领域
+3. 提示用户审核计划，等待确认
+
+# 阶段2：启动 Execution Agent（用户确认后）
+
+按 `_shared/dual-agent-orchestrator.zh.md` 阶段3 执行。
+
+# 边界情况
+
+| 情况             | 处理                                                 |
+| ---------------- | ---------------------------------------------------- |
+| Topic 过宽       | Planning Agent 拆为子主题并标注优先级                |
+| 已有相关研究     | 更新现有报告，不新建重复文件                         |
+| 指定草稿不存在   | 提示用户确认路径，或改为 TOPIC MODE                  |
+| 无相关草稿       | 正常执行，「来自草稿的核心洞察」区块注明"无本地草稿" |
+| WebSearch 无结果 | 依赖本地草稿，报告中注明局限性                       |
+| WebFetch 失败    | 在「参考资源」标注"(链接无法访问，仅供参考)"         |
+
+# 后续处理
+
+用户要求补充/修改时：直接修改现有研究报告文件，不创建重复文件。
+
+计划文件在执行完成后保留于 `{计划目录}/` 且状态为 `done`，等待 `/archive` 统一归档至 `{归档计划子目录}`。
+
+# 记忆系统集成
+
+> 通用协议（文件变更通知、技能完成、会话收尾）见 `_shared/memory-protocol.md`。以下仅列出本技能特有的查询和行为。
+
+### 前置查询
+
+见阶段 0 中的查询代码。