ima-python-sdk 0.1.0__py3-none-any.whl

ima_sdk/notes.py

@@ -0,0 +1,343 @@
+"""笔记管理器。
+
+封装 IMA 笔记相关的所有 API 操作，包括搜索、列表、创建、追加和读取。
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional, Tuple
+
+from .client import ImaClient
+from . import logger
+from .types import (
+    ContentFormat,
+    DocBasic,
+    NoteBookInfo,
+    NoteFolderItem,
+    SearchedDoc,
+    SearchType,
+    SortType,
+)
+
+# 笔记 API 基础路径
+_BASE = "openapi/note/v1"
+
+
+def _ensure_utf8(text: str) -> str:
+    """确保文本为合法 UTF-8 编码。
+
+    对无法编码的字符进行替换处理。
+    """
+    return text.encode("utf-8", errors="replace").decode("utf-8")
+
+
+class NotesManager:
+    """笔记管理器。
+
+    用法::
+
+        from ima_sdk import ImaClient, NotesManager
+
+        client = ImaClient()
+        notes = NotesManager(client)
+
+        # 搜索笔记
+        results = notes.search("会议记录")
+
+        # 创建笔记
+        doc_id = notes.create("# 会议纪要\\n\\n今日要点...")
+    """
+
+    def __init__(self, client: ImaClient):
+        self._client = client
+
+    # ── 搜索笔记 ──────────────────────────────────────────────────────────────
+
+    def search(
+        self,
+        query: str,
+        *,
+        search_type: int = SearchType.TITLE,
+        sort_type: int = SortType.MODIFY_TIME,
+        start: int = 0,
+        end: int = 20,
+    ) -> Tuple[List[SearchedDoc], int, bool]:
+        """搜索笔记。
+
+        Args:
+            query: 搜索关键词
+            search_type: 检索方式，0=标题（默认），1=正文
+            sort_type: 排序方式，0=更新时间, 1=创建时间, 2=标题, 3=大小
+            start: 翻页起始位置
+            end: 翻页结束位置
+
+        Returns:
+            (搜索结果列表, 总命中数, 是否最后一页) 的元组
+        """
+        # 构建 query_info
+        logger.log_step("搜索笔记", f"query={query!r} search_type={search_type} sort_type={sort_type}")
+        query_info = {}
+        if search_type == SearchType.TITLE:
+            query_info["title"] = query
+        else:
+            query_info["content"] = query
+
+        data = self._client.post(
+            f"{_BASE}/search_note_book",
+            {
+                "search_type": search_type,
+                "sort_type": sort_type,
+                "query_info": query_info,
+                "start": start,
+                "end": end,
+            },
+        )
+        docs = [SearchedDoc.from_dict(d) for d in data.get("docs", [])]
+        total = data.get("total_hit_num", 0)
+        is_end = data.get("is_end", True)
+        logger.log(f"  命中 {total} 条，本页 {len(docs)} 条，is_end={is_end}")
+        return docs, total, is_end
+
+    def search_all(
+        self,
+        query: str,
+        *,
+        search_type: int = SearchType.TITLE,
+        sort_type: int = SortType.MODIFY_TIME,
+        page_size: int = 20,
+    ) -> List[SearchedDoc]:
+        """搜索笔记并自动翻页获取全部结果。
+
+        Args:
+            query: 搜索关键词
+            search_type: 检索方式
+            sort_type: 排序方式
+            page_size: 每页数量
+
+        Returns:
+            所有搜索结果列表
+        """
+        logger.log_step("搜索全部笔记", f"query={query!r} page_size={page_size}")
+        all_docs: List[SearchedDoc] = []
+        start = 0
+        while True:
+            docs, _, is_end = self.search(
+                query,
+                search_type=search_type,
+                sort_type=sort_type,
+                start=start,
+                end=start + page_size,
+            )
+            all_docs.extend(docs)
+            if is_end or not docs:
+                break
+            start += page_size
+        logger.log(f"  共获取 {len(all_docs)} 条笔记")
+        return all_docs
+
+    # ── 列出笔记本 ────────────────────────────────────────────────────────────
+
+    def list_folders(
+        self, *, limit: int = 50
+    ) -> List[NoteFolderItem]:
+        """列出所有笔记本（单页）。
+
+        Args:
+            limit: 数量限制
+
+        Returns:
+            笔记本列表
+        """
+        logger.log_step("列出笔记本", f"limit={limit}")
+        data = self._client.post(
+            f"{_BASE}/list_note_folder_by_cursor",
+            {"cursor": "0", "limit": limit},
+        )
+        result = [
+            NoteFolderItem.from_dict(f) for f in data.get("note_book_folders", [])
+        ]
+        logger.log(f"  获取 {len(result)} 个笔记本")
+        return result
+
+    def list_all_folders(self, *, limit: int = 50) -> List[NoteFolderItem]:
+        """列出所有笔记本（自动翻页）。
+
+        Args:
+            limit: 每页数量
+
+        Returns:
+            所有笔记本列表
+        """
+        logger.log_step("列出全部笔记本", f"limit={limit}")
+        all_folders: List[NoteFolderItem] = []
+        cursor = "0"
+        while True:
+            data = self._client.post(
+                f"{_BASE}/list_note_folder_by_cursor",
+                {"cursor": cursor, "limit": limit},
+            )
+            folders = [
+                NoteFolderItem.from_dict(f)
+                for f in data.get("note_book_folders", [])
+            ]
+            all_folders.extend(folders)
+            if data.get("is_end", True):
+                break
+            next_cursor = data.get("next_cursor", "")
+            if not next_cursor:
+                break
+            cursor = next_cursor
+        logger.log(f"  共获取 {len(all_folders)} 个笔记本")
+        return all_folders
+
+    # ── 列出笔记 ──────────────────────────────────────────────────────────────
+
+    def list_notes(
+        self,
+        *,
+        folder_id: Optional[str] = None,
+        limit: int = 50,
+    ) -> Tuple[List[NoteBookInfo], bool, str]:
+        """列出笔记本下的笔记（单页）。
+
+        Args:
+            folder_id: 笔记本 ID（省略则列出根目录）
+            limit: 数量限制
+
+        Returns:
+            (笔记列表, 是否最后一页, 下一页游标) 的元组
+        """
+        logger.log_step("列出笔记", f"folder_id={folder_id} limit={limit}")
+        body: dict = {"cursor": "", "limit": limit}
+        if folder_id:
+            body["folder_id"] = folder_id
+        data = self._client.post(f"{_BASE}/list_note_by_folder_id", body)
+        notes = [NoteBookInfo.from_dict(n) for n in data.get("note_book_list", [])]
+        is_end = data.get("is_end", True)
+        next_cursor = data.get("next_cursor", "")
+        logger.log(f"  获取 {len(notes)} 条笔记，is_end={is_end}")
+        return notes, is_end, next_cursor
+
+    def list_all_notes(
+        self,
+        *,
+        folder_id: Optional[str] = None,
+        limit: int = 50,
+    ) -> List[NoteBookInfo]:
+        """列出笔记本下的所有笔记（自动翻页）。
+
+        Args:
+            folder_id: 笔记本 ID
+            limit: 每页数量
+
+        Returns:
+            所有笔记列表
+        """
+        logger.log_step("列出全部笔记", f"folder_id={folder_id}")
+        all_notes: List[NoteBookInfo] = []
+        cursor = ""
+        while True:
+            body: dict = {"cursor": cursor, "limit": limit}
+            if folder_id:
+                body["folder_id"] = folder_id
+            data = self._client.post(f"{_BASE}/list_note_by_folder_id", body)
+            notes = [
+                NoteBookInfo.from_dict(n) for n in data.get("note_book_list", [])
+            ]
+            all_notes.extend(notes)
+            if data.get("is_end", True):
+                break
+            next_cursor = data.get("next_cursor", "")
+            if not next_cursor:
+                break
+            cursor = next_cursor
+        logger.log(f"  共获取 {len(all_notes)} 条笔记")
+        return all_notes
+
+    # ── 创建笔记 ──────────────────────────────────────────────────────────────
+
+    def create(
+        self,
+        content: str,
+        *,
+        folder_id: Optional[str] = None,
+    ) -> str:
+        """创建新笔记（Markdown 格式）。
+
+        Args:
+            content: 笔记正文内容（Markdown 格式）
+            folder_id: 关联的笔记本 ID
+
+        Returns:
+            新建笔记的 doc_id
+        """
+        content = _ensure_utf8(content)
+        logger.log_step("创建笔记", f"content_len={len(content)} folder_id={folder_id}")
+        body: dict = {
+            "content_format": ContentFormat.MARKDOWN,
+            "content": content,
+        }
+        if folder_id:
+            body["folder_id"] = folder_id
+        data = self._client.post(f"{_BASE}/import_doc", body)
+        doc_id = data.get("doc_id", "")
+        logger.log(f"  创建成功 doc_id={doc_id}")
+        return doc_id
+
+    # ── 追加内容到笔记 ────────────────────────────────────────────────────────
+
+    def append(self, doc_id: str, content: str) -> str:
+        """在笔记末尾追加内容。
+
+        注意：追加操作不可撤销。
+
+        Args:
+            doc_id: 目标笔记 ID
+            content: 要追加的内容（Markdown 格式）
+
+        Returns:
+            目标笔记的 doc_id
+        """
+        content = _ensure_utf8(content)
+        logger.log_step("追加笔记内容", f"doc_id={doc_id} content_len={len(content)}")
+        data = self._client.post(
+            f"{_BASE}/append_doc",
+            {
+                "doc_id": doc_id,
+                "content_format": ContentFormat.MARKDOWN,
+                "content": content,
+            },
+        )
+        result_id = data.get("doc_id", "")
+        logger.log(f"  追加成功 doc_id={result_id}")
+        return result_id
+
+    # ── 获取笔记内容 ──────────────────────────────────────────────────────────
+
+    def get_content(
+        self,
+        doc_id: str,
+        *,
+        target_format: int = ContentFormat.PLAINTEXT,
+    ) -> str:
+        """获取笔记内容。
+
+        Args:
+            doc_id: 目标笔记 ID
+            target_format: 目标格式，0=纯文本（推荐），2=JSON
+                           注意：1=Markdown 不支持
+
+        Returns:
+            笔记内容文本
+        """
+        logger.log_step("读取笔记内容", f"doc_id={doc_id} format={target_format}")
+        data = self._client.post(
+            f"{_BASE}/get_doc_content",
+            {
+                "doc_id": doc_id,
+                "target_content_format": target_format,
+            },
+        )
+        content = data.get("content", "")
+        logger.log(f"  内容长度: {len(content)} 字符")
+        return content