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

ima_python_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: ima-python-sdk
+Version: 0.1.0
+Summary: 非官方的 IMA OpenAPI Python SDK，提供知识库和笔记管理功能
+Author: elxy
+License: MIT
+Project-URL: Homepage, https://github.com/elxy/ima-python-sdk
+Project-URL: Repository, https://github.com/elxy/ima-python-sdk
+Project-URL: Issues, https://github.com/elxy/ima-python-sdk/issues
+Keywords: ima,knowledge-base,notes,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ima-python-sdk
+
+非官方的 IMA OpenAPI Python SDK，提供知识库和笔记管理功能。
+
+> 本项目参考 [ima-skills](https://clawhub.ai/iampennyli/ima-skills) 中的 API 文档和脚本实现，与 IMA 官方无关。
+
+## 安装
+
+```bash
+pip install ima-python-sdk
+```
+
+## 配置
+
+SDK 需要 `client_id` 和 `api_key` 两个凭证，按以下优先级自动发现：
+
+1. **构造参数** — `ImaClient(client_id="...", api_key="...")`
+2. **环境变量** — `IMA_OPENAPI_CLIENTID` / `IMA_OPENAPI_APIKEY`
+3. **配置文件** — `~/.config/ima/client_id` / `~/.config/ima/api_key`
+
+## CLI 使用
+
+`--kb_id` 可通过环境变量 `IMA_KB_ID` 设置，避免每次手动指定。
+
+```bash
+# 知识库
+ima-sdk kb addable
+ima-sdk kb upload report.pdf --kb_id xxx                   # 上传到根目录
+ima-sdk kb upload report.pdf 论文/机器学习 --kb_id xxx      # 上传到指定目录
+ima-sdk kb import-url https://example.com --kb_id xxx
+
+# 笔记
+ima-sdk note search "会议记录"
+ima-sdk note create "# 标题"
+ima-sdk note read <doc_id> --raw
+```
+
+## SDK 使用
+
+```python
+from ima_sdk import ImaClient, KnowledgeBaseManager, NotesManager
+
+client = ImaClient()  # 自动读取环境变量或配置文件
+kb = KnowledgeBaseManager(client)
+notes = NotesManager(client)
+
+# 知识库操作
+kb.upload_file("/path/to/report.pdf", knowledge_base_id="xxx")
+kb.import_urls(["https://example.com"], knowledge_base_id="xxx")
+results = kb.search_knowledge("关键词", knowledge_base_id="xxx")
+
+# 笔记操作
+doc_id = notes.create("# 标题\n\n正文内容")
+docs, total, is_end = notes.search("会议记录")
+content = notes.get_content(doc_id)
+```
+
+## 特性
+
+- **零第三方依赖** — 仅使用 Python 标准库（urllib, hmac, hashlib, dataclasses）
+- **凭证自动发现** — 构造参数 > 环境变量 > 配置文件，三级优先
+- **自动翻页** — 列表接口支持 `fetch_all=True`
+- **完整上传流程** — `upload_file()` 一个方法完成预检、重名检查、创建媒体、COS 上传、添加知识
+- **UTF-8 安全** — 笔记写入前自动校验编码
+
+## License
+
+MIT

ima_python_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+ima_python_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=Mi2ivYnXBdi7QDrfLPnxgyujUcGuHNEGBV-1b4kYVhc,1061
+ima_sdk/__init__.py,sha256=oJTlVRs08wdQkye-IQzZaJesNA1Uf3XOm7Fp6RiJu-k,1956
+ima_sdk/cli.py,sha256=m3yOfH8bFf9ZQJwZ1772fmHFXHVu1_Ie1pCUgpynDfs,15708
+ima_sdk/client.py,sha256=Tx21aJSWDRkzpOkxHPKTFS_L1MF-511k8MYHH-Hnnu4,9717
+ima_sdk/cos_uploader.py,sha256=BEINVD4N8PbE_nHe0XocLtQFPLt-46T-qm1l9RJD0UI,4813
+ima_sdk/file_checker.py,sha256=LWO-yeOIFFGXvvqqvF2CWDyzp9n9nsxlHtK5KDsw0yI,8266
+ima_sdk/knowledge_base.py,sha256=8n-cr-J2lQaDm8Lqmww_CrUsYh9Imw_vLBbOsSho7ek,20965
+ima_sdk/logger.py,sha256=FEYNSM96G-b2wRJkGHcnoOArUD22Fm4wrstfuYYrIbY,2395
+ima_sdk/notes.py,sha256=GoRyn1qXs3AL9zu6oSRCuYXepVxNtVfOCG7hH8wfNfM,11323
+ima_sdk/types.py,sha256=oHYCsEo1YK_6fTxZC4lpPC4U_XZh6W5QuSTVy_XK3is,11346
+ima_python_sdk-0.1.0.dist-info/METADATA,sha256=GwP77JyDpPlRwTCda0e7Rk8RopSwoczXYfLIESNa8Aw,3117
+ima_python_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ima_python_sdk-0.1.0.dist-info/entry_points.txt,sha256=dugqsz4PVgamfgxXz9TdDoZEfgQMkNKAkNRKRCgHy6s,45
+ima_python_sdk-0.1.0.dist-info/top_level.txt,sha256=sZundEb6Z_upgSYPSF_XyJLnHM9k45r9lgzdfLfoPLw,8
+ima_python_sdk-0.1.0.dist-info/RECORD,,

ima_python_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ima_python_sdk-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ima-sdk = ima_sdk.cli:main

ima_python_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 elxy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ima_python_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ima_sdk

ima_sdk/__init__.py

@@ -0,0 +1,90 @@
+"""IMA Python SDK — 知识库和笔记操作。
+
+用法::
+
+    from ima_sdk import ImaClient, KnowledgeBaseManager, NotesManager
+
+    client = ImaClient()
+    kb = KnowledgeBaseManager(client)
+    notes = NotesManager(client)
+
+    # 搜索知识库
+    results = kb.search_knowledge_base("我的资料")
+
+    # 上传文件到知识库
+    kb.upload_file("/path/to/report.pdf", knowledge_base_id="xxx")
+
+    # 创建笔记
+    doc_id = notes.create("# 标题\\n\\n正文内容")
+
+    # 搜索笔记
+    docs, total, is_end = notes.search("会议记录")
+"""
+
+__version__ = "0.1.0"
+
+from .client import ImaApiError, ImaClient
+from .cos_uploader import cos_upload
+from .file_checker import check_file
+from .knowledge_base import KnowledgeBaseManager
+from .notes import NotesManager
+from .types import (
+    AddableKnowledgeBaseInfo,
+    CheckRepeatedNameResult,
+    ContentFormat,
+    CosCredential,
+    CreateMediaResult,
+    DocBasic,
+    FileCheckResult,
+    FileInfo,
+    FolderType,
+    ImportURLResult,
+    KBFolderInfo,
+    KnowledgeBaseInfo,
+    KnowledgeInfo,
+    KnowledgeListResult,
+    MediaType,
+    NoteBookInfo,
+    NoteFolderItem,
+    SearchedDoc,
+    SearchedKnowledgeBaseInfo,
+    SearchedKnowledgeInfo,
+    SearchType,
+    SortType,
+)
+
+__all__ = [
+    # 核心
+    "ImaClient",
+    "ImaApiError",
+    # 管理器
+    "KnowledgeBaseManager",
+    "NotesManager",
+    # 工具函数
+    "check_file",
+    "cos_upload",
+    # 类型
+    "KnowledgeBaseInfo",
+    "KnowledgeInfo",
+    "KBFolderInfo",
+    "AddableKnowledgeBaseInfo",
+    "SearchedKnowledgeBaseInfo",
+    "SearchedKnowledgeInfo",
+    "ImportURLResult",
+    "CosCredential",
+    "FileInfo",
+    "CreateMediaResult",
+    "CheckRepeatedNameResult",
+    "KnowledgeListResult",
+    "FileCheckResult",
+    "DocBasic",
+    "NoteFolderItem",
+    "NoteBookInfo",
+    "SearchedDoc",
+    # 枚举
+    "MediaType",
+    "ContentFormat",
+    "SearchType",
+    "SortType",
+    "FolderType",
+]

ima_sdk/cli.py

@@ -0,0 +1,447 @@
+"""IMA SDK 命令行工具。
+
+使用 argparse 子命令模式提供知识库和笔记的命令行操作。
+
+用法::
+
+    # 知识库操作
+    ima-sdk kb search-base <query>
+    ima-sdk kb info <kb_id>
+    ima-sdk kb list <kb_id>
+    ima-sdk kb search <query> --kb_id <kb_id>
+    ima-sdk kb upload <file_path> [dest_dir] --kb_id <kb_id>
+    ima-sdk kb upload <file_path> [dest_dir]          # kb_id 从 IMA_KB_ID 环境变量读取
+    ima-sdk kb import-url <url> --kb_id <kb_id>
+    ima-sdk kb addable
+
+    # 笔记操作
+    ima-sdk note search <query>
+    ima-sdk note folders
+    ima-sdk note list [--folder_id <id>]
+    ima-sdk note create <content_or_file>
+    ima-sdk note append <doc_id> <content_or_file>
+    ima-sdk note read <doc_id>
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import Any
+
+
+def _json_output(obj: Any) -> str:
+    """将对象序列化为可读的 JSON 字符串。"""
+    if hasattr(obj, "__dataclass_fields__"):
+        from dataclasses import asdict
+
+        return json.dumps(asdict(obj), ensure_ascii=False, indent=2)
+    if isinstance(obj, list):
+        from dataclasses import asdict
+
+        items = []
+        for item in obj:
+            if hasattr(item, "__dataclass_fields__"):
+                items.append(asdict(item))
+            elif isinstance(item, dict):
+                items.append(item)
+            else:
+                items.append(str(item))
+        return json.dumps(items, ensure_ascii=False, indent=2)
+    if isinstance(obj, dict):
+        from dataclasses import asdict
+
+        result = {}
+        for k, v in obj.items():
+            if hasattr(v, "__dataclass_fields__"):
+                result[k] = asdict(v)
+            else:
+                result[k] = v
+        return json.dumps(result, ensure_ascii=False, indent=2)
+    return json.dumps(obj, ensure_ascii=False, indent=2)
+
+
+def _read_content(value: str) -> str:
+    """读取内容：如果 value 是存在的文件路径则读取文件，否则作为直接内容。"""
+    if os.path.isfile(value):
+        with open(value, "r", encoding="utf-8") as f:
+            return f.read()
+    return value
+
+
+def _get_client(*, curl_mode: bool = False):
+    """创建 ImaClient 实例。"""
+    from .client import ImaClient
+
+    return ImaClient(curl_mode=curl_mode)
+
+
+def _require_kb_id(args: argparse.Namespace) -> str:
+    """校验 kb_id 存在，缺失时报错退出。"""
+    if not args.kb_id:
+        print(
+            "错误: 必须通过 --kb_id 或环境变量 IMA_KB_ID 指定知识库 ID",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    return args.kb_id
+
+
+# ── 知识库子命令 ──────────────────────────────────────────────────────────────
+
+
+def _kb_search_base(args: argparse.Namespace) -> None:
+    from .knowledge_base import KnowledgeBaseManager
+
+    kb = KnowledgeBaseManager(_get_client(curl_mode=args.curl))
+    results = kb.search_knowledge_base(args.query, fetch_all=args.all)
+    print(_json_output(results))
+
+
+def _kb_info(args: argparse.Namespace) -> None:
+    from .knowledge_base import KnowledgeBaseManager
+
+    kb = KnowledgeBaseManager(_get_client(curl_mode=args.curl))
+    results = kb.get_knowledge_base(args.ids)
+    print(_json_output(results))
+
+
+def _kb_list(args: argparse.Namespace) -> None:
+    from .knowledge_base import KnowledgeBaseManager
+
+    _require_kb_id(args)
+    kb = KnowledgeBaseManager(_get_client(curl_mode=args.curl))
+    if args.all:
+        knowledge, folders = kb.get_all_knowledge(
+            args.kb_id, folder_id=args.folder_id
+        )
+        print(
+            _json_output({"knowledge": knowledge, "folders": folders})
+        )
+    else:
+        result = kb.get_knowledge_list(
+            args.kb_id, folder_id=args.folder_id, limit=args.limit
+        )
+        print(_json_output(result))
+
+
+def _kb_search(args: argparse.Namespace) -> None:
+    from .knowledge_base import KnowledgeBaseManager
+
+    _require_kb_id(args)
+    kb = KnowledgeBaseManager(_get_client(curl_mode=args.curl))
+    results = kb.search_knowledge(
+        args.query, args.kb_id, fetch_all=args.all
+    )
+    print(_json_output(results))
+
+
+def _kb_upload(args: argparse.Namespace) -> None:
+    from .knowledge_base import KnowledgeBaseManager
+
+    _require_kb_id(args)
+    kb = KnowledgeBaseManager(_get_client(curl_mode=args.curl))
+
+    # dest_dir 和 --folder_id 互斥，dest_dir 需要逐级解析
+    folder_id = args.folder_id
+    if args.dest_dir:
+        if folder_id:
+            print("错误: --folder_id 和 dest_dir 不能同时指定", file=sys.stderr)
+            sys.exit(1)
+        folder_id = kb.resolve_folder_path(args.kb_id, args.dest_dir)
+
+    if args.dry_run:
+        result = kb.dry_run_upload(
+            args.file_path,
+            args.kb_id,
+            folder_id=folder_id,
+        )
+        print(_json_output(result))
+    else:
+        media_id = kb.upload_file(
+            args.file_path,
+            args.kb_id,
+            folder_id=folder_id,
+            skip_duplicate_check=args.skip_dup,
+        )
+        print(json.dumps({"media_id": media_id}, ensure_ascii=False))
+
+
+def _kb_import_url(args: argparse.Namespace) -> None:
+    from .knowledge_base import KnowledgeBaseManager
+
+    _require_kb_id(args)
+    kb = KnowledgeBaseManager(_get_client(curl_mode=args.curl))
+    results = kb.import_urls(
+        args.urls, args.kb_id, folder_id=args.folder_id
+    )
+    print(_json_output(results))
+
+
+def _kb_addable(args: argparse.Namespace) -> None:
+    from .knowledge_base import KnowledgeBaseManager
+
+    kb = KnowledgeBaseManager(_get_client(curl_mode=args.curl))
+    results = kb.get_addable_list(fetch_all=args.all)
+    print(_json_output(results))
+
+
+# ── 笔记子命令 ────────────────────────────────────────────────────────────────
+
+
+def _note_search(args: argparse.Namespace) -> None:
+    from .notes import NotesManager
+
+    notes = NotesManager(_get_client(curl_mode=args.curl))
+    if args.all:
+        results = notes.search_all(
+            args.query, search_type=args.search_type, sort_type=args.sort_type
+        )
+        print(_json_output(results))
+    else:
+        docs, total, is_end = notes.search(
+            args.query,
+            search_type=args.search_type,
+            sort_type=args.sort_type,
+            start=args.start,
+            end=args.end,
+        )
+        print(
+            _json_output(
+                {"docs": docs, "total_hit_num": total, "is_end": is_end}
+            )
+        )
+
+
+def _note_folders(args: argparse.Namespace) -> None:
+    from .notes import NotesManager
+
+    notes = NotesManager(_get_client(curl_mode=args.curl))
+    if args.all:
+        results = notes.list_all_folders()
+    else:
+        results = notes.list_folders(limit=args.limit)
+    print(_json_output(results))
+
+
+def _note_list(args: argparse.Namespace) -> None:
+    from .notes import NotesManager
+
+    notes = NotesManager(_get_client(curl_mode=args.curl))
+    if args.all:
+        results = notes.list_all_notes(folder_id=args.folder_id)
+        print(_json_output(results))
+    else:
+        note_list, is_end, next_cursor = notes.list_notes(
+            folder_id=args.folder_id, limit=args.limit
+        )
+        print(
+            _json_output(
+                {
+                    "notes": note_list,
+                    "is_end": is_end,
+                    "next_cursor": next_cursor,
+                }
+            )
+        )
+
+
+def _note_create(args: argparse.Namespace) -> None:
+    from .notes import NotesManager
+
+    notes = NotesManager(_get_client(curl_mode=args.curl))
+    content = _read_content(args.content)
+    doc_id = notes.create(content, folder_id=args.folder_id)
+    print(json.dumps({"doc_id": doc_id}, ensure_ascii=False))
+
+
+def _note_append(args: argparse.Namespace) -> None:
+    from .notes import NotesManager
+
+    notes = NotesManager(_get_client(curl_mode=args.curl))
+    content = _read_content(args.content)
+    doc_id = notes.append(args.doc_id, content)
+    print(json.dumps({"doc_id": doc_id}, ensure_ascii=False))
+
+
+def _note_read(args: argparse.Namespace) -> None:
+    from .notes import NotesManager
+
+    notes = NotesManager(_get_client(curl_mode=args.curl))
+    content = notes.get_content(args.doc_id, target_format=args.format)
+    if args.raw:
+        print(content)
+    else:
+        print(json.dumps({"content": content}, ensure_ascii=False, indent=2))
+
+
+# ── 主解析器 ──────────────────────────────────────────────────────────────────
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """构建命令行解析器。"""
+    parser = argparse.ArgumentParser(
+        prog="ima-sdk",
+        description="IMA 知识库和笔记命令行工具",
+    )
+    parser.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="启用详细日志输出（输出到 stderr）",
+    )
+    parser.add_argument(
+        "--curl",
+        action="store_true",
+        help="输出等价的 curl 命令到 stderr，方便调试",
+    )
+    subparsers = parser.add_subparsers(dest="module", help="功能模块")
+
+    # ── kb 模块 ───────────────────────────────────────────────────────────
+
+    kb_parser = subparsers.add_parser("kb", help="知识库操作")
+    kb_sub = kb_parser.add_subparsers(dest="command", help="知识库命令")
+
+    # kb search-base
+    p = kb_sub.add_parser("search-base", help="搜索知识库列表")
+    p.add_argument("query", help="搜索关键词")
+    p.add_argument("--all", action="store_true", help="获取全部结果（自动翻页）")
+    p.set_defaults(func=_kb_search_base)
+
+    # kb info
+    p = kb_sub.add_parser("info", help="获取知识库信息")
+    p.add_argument("ids", nargs="+", help="知识库 ID（支持多个）")
+    p.set_defaults(func=_kb_info)
+
+    # kb list
+    p = kb_sub.add_parser("list", help="浏览知识库内容")
+    p.add_argument("kb_id", nargs="?", default=os.environ.get("IMA_KB_ID"), help="知识库 ID（默认读取环境变量 IMA_KB_ID）")
+    p.add_argument("--folder_id", help="文件夹 ID")
+    p.add_argument("--limit", type=int, default=50, help="每页数量（默认 50）")
+    p.add_argument("--all", action="store_true", help="获取全部（自动翻页）")
+    p.set_defaults(func=_kb_list)
+
+    # kb search
+    p = kb_sub.add_parser("search", help="搜索知识库内容")
+    p.add_argument("query", help="搜索关键词")
+    p.add_argument("--kb_id", default=os.environ.get("IMA_KB_ID"), help="知识库 ID（默认读取环境变量 IMA_KB_ID）")
+    p.add_argument("--all", action="store_true", help="获取全部结果")
+    p.set_defaults(func=_kb_search)
+
+    # kb upload
+    p = kb_sub.add_parser("upload", help="上传文件到知识库")
+    p.add_argument("file_path", help="文件路径")
+    p.add_argument("dest_dir", nargs="?", default="", help="目标目录路径，如 '论文/机器学习'（默认根目录）")
+    p.add_argument("--kb_id", default=os.environ.get("IMA_KB_ID"), help="知识库 ID（默认读取环境变量 IMA_KB_ID）")
+    p.add_argument("--folder_id", help="文件夹 ID（与 dest_dir 互斥）")
+    p.add_argument("--skip_dup", action="store_true", help="跳过重名检查")
+    p.add_argument("--dry_run", action="store_true", help="只做预检和重名检查，不实际上传")
+    p.set_defaults(func=_kb_upload)
+
+    # kb import-url
+    p = kb_sub.add_parser("import-url", help="导入网页到知识库")
+    p.add_argument("urls", nargs="+", help="URL 列表（1-10 个）")
+    p.add_argument("--kb_id", default=os.environ.get("IMA_KB_ID"), help="知识库 ID（默认读取环境变量 IMA_KB_ID）")
+    p.add_argument("--folder_id", help="文件夹 ID")
+    p.set_defaults(func=_kb_import_url)
+
+    # kb addable
+    p = kb_sub.add_parser("addable", help="列出可添加的知识库")
+    p.add_argument("--all", action="store_true", help="获取全部结果")
+    p.set_defaults(func=_kb_addable)
+
+    # ── note 模块 ─────────────────────────────────────────────────────────
+
+    note_parser = subparsers.add_parser("note", help="笔记操作")
+    note_sub = note_parser.add_subparsers(dest="command", help="笔记命令")
+
+    # note search
+    p = note_sub.add_parser("search", help="搜索笔记")
+    p.add_argument("query", help="搜索关键词")
+    p.add_argument(
+        "--search_type", type=int, default=0, help="检索方式: 0=标题, 1=正文"
+    )
+    p.add_argument(
+        "--sort_type",
+        type=int,
+        default=0,
+        help="排序: 0=更新时间, 1=创建时间, 2=标题, 3=大小",
+    )
+    p.add_argument("--start", type=int, default=0, help="翻页起始位置")
+    p.add_argument("--end", type=int, default=20, help="翻页结束位置")
+    p.add_argument("--all", action="store_true", help="获取全部结果")
+    p.set_defaults(func=_note_search)
+
+    # note folders
+    p = note_sub.add_parser("folders", help="列出笔记本")
+    p.add_argument("--limit", type=int, default=50, help="数量限制")
+    p.add_argument("--all", action="store_true", help="获取全部")
+    p.set_defaults(func=_note_folders)
+
+    # note list
+    p = note_sub.add_parser("list", help="列出笔记")
+    p.add_argument("--folder_id", help="笔记本 ID")
+    p.add_argument("--limit", type=int, default=50, help="数量限制")
+    p.add_argument("--all", action="store_true", help="获取全部")
+    p.set_defaults(func=_note_list)
+
+    # note create
+    p = note_sub.add_parser("create", help="创建笔记")
+    p.add_argument("content", help="笔记内容（Markdown）或文件路径")
+    p.add_argument("--folder_id", help="笔记本 ID")
+    p.set_defaults(func=_note_create)
+
+    # note append
+    p = note_sub.add_parser("append", help="追加内容到笔记")
+    p.add_argument("doc_id", help="目标笔记 ID")
+    p.add_argument("content", help="追加内容（Markdown）或文件路径")
+    p.set_defaults(func=_note_append)
+
+    # note read
+    p = note_sub.add_parser("read", help="读取笔记内容")
+    p.add_argument("doc_id", help="笔记 ID")
+    p.add_argument(
+        "--format", type=int, default=0, help="目标格式: 0=纯文本, 2=JSON"
+    )
+    p.add_argument("--raw", action="store_true", help="直接输出内容（不包裹 JSON）")
+    p.set_defaults(func=_note_read)
+
+    return parser
+
+
+def main() -> None:
+    """命令行入口函数。"""
+    parser = build_parser()
+    args = parser.parse_args()
+
+    # 处理 verbose 开关
+    if args.verbose:
+        from . import logger
+        logger.enable()
+
+    if not args.module:
+        parser.print_help()
+        sys.exit(1)
+
+    if not args.command:
+        # 打印子模块帮助
+        if args.module == "kb":
+            parser.parse_args(["kb", "-h"])
+        elif args.module == "note":
+            parser.parse_args(["note", "-h"])
+        sys.exit(1)
+
+    if not hasattr(args, "func"):
+        parser.print_help()
+        sys.exit(1)
+
+    try:
+        args.func(args)
+    except Exception as e:
+        print(f"错误: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()