read-cli 0.2.0__py3-none-any.whl

read/__init__.py

@@ -0,0 +1,11 @@
+"""
+读咚咚 (Read) - 个人知识数据层
+
+本地、私有、可编程的个人知识基础设施。
+"""
+
+__version__ = "0.1.0"
+
+from read.core.client import Client
+
+__all__ = ["Client", "__version__"]

read/cli.py

@@ -0,0 +1,138 @@
+"""CLI 主入口
+
+职责：
+- 统一的 JSON 输出
+- 统一的错误处理
+- Typer 应用配置
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import traceback
+import typer
+from typing import Any
+
+from dong import json_output, ValidationError, NotFoundError, ConflictError
+from read import __version__
+
+app = typer.Typer(
+    name="read",
+    help="读咚咚 (Read) - 个人知识数据层的命令行接口",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def output(data: Any, success: bool = True) -> None:
+    """输出 JSON 格式"""
+    result: dict[str, Any] = {"success": success}
+    if success:
+        result["data"] = data
+    else:
+        result["error"] = data
+    typer.echo(json.dumps(result, ensure_ascii=False, indent=2))
+
+
+def handle_error(e: Exception) -> None:
+    """处理异常并输出结构化错误"""
+    error_info: dict[str, str] = {
+        "code": type(e).__name__,
+        "message": str(e),
+    }
+
+    if "--debug" in sys.argv:
+        error_info["traceback"] = traceback.format_exc()
+
+    output(error_info, success=False)
+    raise typer.Exit(code=1)
+
+
+@app.callback()
+def version_callback(
+    ctx: typer.Context,
+    version: bool = typer.Option(False, "--version", "-v", help="显示版本号"),
+) -> None:
+    """版本号回调"""
+    if version:
+        typer.echo(f"read {__version__}")
+        raise typer.Exit()
+
+
+@app.command()
+@json_output
+def init():
+    """初始化数据库"""
+    from read.commands.init import cmd_init
+    result = cmd_init()
+    return result
+
+
+@app.command()
+@json_output
+def add(
+    content: str = typer.Argument(None, help="摘录内容"),
+    url: str = typer.Option(None, "--url", "-u", help="链接"),
+    source: str = typer.Option(None, "--source", "-s", help="来源备注"),
+    type: str = typer.Option("quote", "--type", "-t", help="数据类型（quote/article/code）"),
+):
+    """添加摘录或链接"""
+    from read.commands.add import cmd_add
+    result = cmd_add(content=content, url=url, source=source, item_type=type)
+    return result
+
+
+@app.command()
+@json_output
+def ls(
+    limit: int = typer.Option(20, "--limit", "-l", help="返回数量"),
+    offset: int = typer.Option(0, "--offset", "-o", help="偏移量"),
+    type: str = typer.Option(None, "--type", "-t", help="筛选类型（content/link）"),
+    order: str = typer.Option("desc", "--order", help="排序方向（desc/asc）"),
+):
+    """列出所有摘录"""
+    from read.commands.ls import cmd_ls
+    result = cmd_ls(limit=limit, offset=offset, item_type=type, order=order)
+    return result
+
+
+@app.command("get")
+@json_output
+def get_item(
+    item_id: int = typer.Argument(..., help="摘录 ID"),
+    field: str = typer.Option(None, "--field", "-f", help="只返回指定字段"),
+):
+    """获取单条摘录"""
+    from read.commands.get import cmd_get
+    result = cmd_get(item_id=item_id, field=field)
+    return result
+
+
+@app.command()
+@json_output
+def delete(
+    item_ids: list[int] = typer.Argument(..., help="摘录 ID（支持多个）"),
+    force: bool = typer.Option(False, "--force", "-f", help="强制删除，不确认"),
+):
+    """删除摘录"""
+    from read.commands.delete import cmd_delete
+    result = cmd_delete(item_ids=item_ids, force=force)
+    return result
+
+
+@app.command()
+@json_output
+def search(
+    query: str = typer.Argument(..., help="搜索关键词"),
+    field: str = typer.Option(None, "--field", "-f", help="搜索字段（content/url/source）"),
+    limit: int = typer.Option(20, "--limit", "-l", help="返回数量"),
+):
+    """搜索摘录"""
+    from read.commands.search import cmd_search
+    result = cmd_search(query=query, field=field, limit=limit)
+    return result
+
+
+if __name__ == "__main__":
+    app()

read/commands/__init__.py

@@ -0,0 +1,17 @@
+"""CLI 命令实现"""
+
+from read.commands.init import cmd_init
+from read.commands.add import cmd_add
+from read.commands.ls import cmd_ls
+from read.commands.get import cmd_get
+from read.commands.delete import cmd_delete
+from read.commands.search import cmd_search
+
+__all__ = [
+    "cmd_init",
+    "cmd_add",
+    "cmd_ls",
+    "cmd_get",
+    "cmd_delete",
+    "cmd_search",
+]

read/commands/add.py

@@ -0,0 +1,32 @@
+"""add 命令 - 添加摘录"""
+
+from typing import Optional
+
+from read.core.client import Client
+
+
+def cmd_add(
+    content: Optional[str],
+    url: Optional[str],
+    source: Optional[str],
+    item_type: str = "quote",
+) -> dict:
+    """添加摘录
+
+    Args:
+        content: 摘录内容
+        url: 链接
+        source: 来源备注
+        item_type: 数据类型
+
+    Returns:
+        添加结果
+    """
+    client = Client()
+    item = client.add(
+        content=content,
+        url=url,
+        source=source,
+        item_type=item_type,
+    )
+    return item.to_dict()

read/commands/delete.py

@@ -0,0 +1,49 @@
+"""delete 命令 - 删除摘录"""
+
+import typer
+from typing import List
+
+from read.core.client import Client
+
+
+def cmd_delete(item_ids: List[int], force: bool = False) -> dict:
+    """删除摘录
+
+    Args:
+        item_ids: 摘录 ID 列表
+        force: 是否强制删除
+
+    Returns:
+        删除结果
+    """
+    client = Client()
+
+    if not force and len(item_ids) == 1:
+        # 单个删除时确认
+        item = client.get_optional(item_ids[0])
+        if item:
+            confirm = typer.confirm(
+                f"确定要删除这条摘录吗？\n\n  {item.display_text[:50]}"
+            )
+            if not confirm:
+                return {"deleted": False, "message": "取消删除"}
+
+    deleted = []
+    not_found = []
+
+    for item_id in item_ids:
+        if client.delete(item_id):
+            deleted.append(item_id)
+        else:
+            not_found.append(item_id)
+
+    result: dict = {
+        "deleted": deleted,
+        "deleted_count": len(deleted),
+    }
+
+    if not_found:
+        result["not_found"] = not_found
+        result["not_found_count"] = len(not_found)
+
+    return result

read/commands/get.py

@@ -0,0 +1,32 @@
+"""get 命令 - 获取单条摘录"""
+
+from typing import Any, Optional
+
+from read.core.client import Client
+from read.core.client import NotFoundError
+
+
+def cmd_get(item_id: int, field: Optional[str] = None) -> Any:
+    """获取单条摘录
+
+    Args:
+        item_id: 摘录 ID
+        field: 只返回指定字段
+
+    Returns:
+        摘录数据或指定字段值
+    """
+    client = Client()
+
+    try:
+        item = client.get(item_id)
+    except NotFoundError:
+        return {
+            "error": "not_found",
+            "message": f"Item {item_id} not found",
+        }
+
+    if field:
+        return item.to_dict().get(field)
+
+    return item.to_dict()

read/commands/init.py

@@ -0,0 +1,12 @@
+"""init 命令 - 初始化数据库"""
+
+from read.db.schema import init_db
+
+
+def cmd_init() -> dict:
+    """初始化数据库
+
+    Returns:
+        初始化结果
+    """
+    return init_db()

read/commands/ls.py

@@ -0,0 +1,47 @@
+"""ls 命令 - 列出所有摘录"""
+
+from typing import Optional
+
+from read.core.client import Client
+from read.db.utils import count_total
+
+
+def cmd_ls(
+    limit: int = 20,
+    offset: int = 0,
+    item_type: Optional[str] = None,
+    order: str = "desc",
+) -> dict:
+    """列出摘录
+
+    Args:
+        limit: 返回数量
+        offset: 偏移量
+        item_type: 筛选类型
+        order: 排序方向
+
+    Returns:
+        列表结果
+    """
+    client = Client()
+
+    # 类型映射
+    type_map = {
+        "content": "quote",
+        "link": "article",
+        "code": "code",
+    }
+    db_type = type_map.get(item_type, item_type) if item_type else None
+
+    items = client.list(
+        limit=limit,
+        offset=offset,
+        item_type=db_type,
+        order=order,
+    )
+
+    return {
+        "total": count_total(),
+        "count": len(items),
+        "items": [item.to_dict() for item in items],
+    }

read/commands/search.py

@@ -0,0 +1,31 @@
+"""search 命令 - 搜索摘录"""
+
+from typing import Optional
+
+from read.core.client import Client
+
+
+def cmd_search(
+    query: str,
+    field: Optional[str] = None,
+    limit: int = 20,
+) -> dict:
+    """搜索摘录
+
+    Args:
+        query: 搜索关键词
+        field: 搜索字段
+        limit: 返回数量
+
+    Returns:
+        搜索结果
+    """
+    client = Client()
+    items = client.search(query=query, field=field, limit=limit)
+
+    return {
+        "query": query,
+        "field": field,
+        "count": len(items),
+        "items": [item.to_dict() for item in items],
+    }

read/config.py

@@ -0,0 +1,36 @@
+"""配置管理模块
+
+继承 dong.config.Config，管理 read-cli 的用户配置。
+"""
+
+from dong.config import Config
+
+
+class ReadConfig(Config):
+    """读咚咚配置类"""
+
+    @classmethod
+    def get_name(cls) -> str:
+        return "read"
+
+    @classmethod
+    def get_defaults(cls) -> dict:
+        return {
+            "default_status": "reading",
+            "default_limit": 20,
+            "statuses": ["reading", "completed", "abandoned"],
+        }
+
+
+# 便捷函数
+def get_config() -> dict:
+    return ReadConfig.load()
+
+def get_default_status() -> str:
+    return ReadConfig.get("default_status", "reading")
+
+def get_default_limit() -> int:
+    return ReadConfig.get("default_limit", 20)
+
+def get_statuses() -> list:
+    return ReadConfig.get("statuses", ["reading", "completed", "abandoned"])

read/const.py

@@ -0,0 +1,28 @@
+"""常量定义"""
+
+import datetime
+
+VERSION = "0.1.0"
+DB_NAME = "read.db"
+# 数据目录 - 统一放在 ~/.dong/ 下
+from pathlib import Path
+DB_DIR = Path.home() / ".dong" / "read"
+
+# 默认配置
+DEFAULT_LIMIT = 20
+DEFAULT_TYPE = "quote"
+
+# 数据类型
+TYPE_QUOTE = "quote"      # 文字摘录
+TYPE_ARTICLE = "article"  # 文章链接
+TYPE_CODE = "code"        # 代码片段
+
+ALL_TYPES = [TYPE_QUOTE, TYPE_ARTICLE, TYPE_CODE]
+
+# 时间格式
+ISO_FORMAT = "%Y-%m-%dT%H:%M:%S"
+
+
+def get_timestamp() -> str:
+    """获取当前时间戳（ISO 8601 格式）"""
+    return datetime.datetime.now().strftime(ISO_FORMAT)

read/core/__init__.py

@@ -0,0 +1,9 @@
+"""Core Library - 读咚咚的核心资产
+
+这是 read 的核心层，所有客户端（CLI、MCP、SDK）都通过此层访问数据。
+"""
+
+from read.core.client import Client
+from read.core.models import Item
+
+__all__ = ["Client", "Item"]

read/core/client.py

@@ -0,0 +1,217 @@
+"""Python SDK / Core Library
+
+这是读咚咚的核心资产。所有客户端（CLI、MCP、HTTP API）都通过此层访问数据。
+
+设计原则：
+1. 独立性 - 不依赖任何客户端
+2. 完整性 - 包含所有数据操作逻辑
+3. 稳定性 - API 考虑向后兼容
+4. 可测试性 - 可独立单元测试
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from read.core.models import Item
+from read.db.utils import (
+    add_item as db_add_item,
+    count_total as db_count_total,
+    delete_item as db_delete_item,
+    get_item as db_get_item,
+    list_items as db_list_items,
+    search_items as db_search_items,
+)
+
+
+class Client:
+    """读咚咚客户端
+
+    这是 Core Library 的主要入口点，提供给 Agent 和开发者使用。
+
+    Example:
+        >>> from read import Client
+        >>> client = Client()
+        >>> item = client.add("开始，就是最好的时机")
+        >>> print(item.id)
+        1
+        >>> items = client.list(limit=10)
+        >>> results = client.search("AI")
+    """
+
+    def __init__(self, db_path: Optional[Path] = None):
+        """初始化客户端
+
+        Args:
+            db_path: 数据库路径，None 则使用默认路径 (~/.read/read.db)
+        """
+        self._db_path = db_path
+        # 注：v0.1 使用默认连接，db_path 参数为 v0.2 多数据库支持预留
+
+    def add(
+        self,
+        content: Optional[str] = None,
+        url: Optional[str] = None,
+        source: Optional[str] = None,
+        item_type: str = "quote",
+        metadata: Optional[str] = None,
+    ) -> Item:
+        """添加摘录
+
+        Args:
+            content: 摘录内容
+            url: 链接
+            source: 来源备注
+            item_type: 数据类型（quote/article/code）
+            metadata: JSON 扩展字段
+
+        Returns:
+            创建的 Item 对象
+
+        Raises:
+            ValueError: content 和 url 都为空
+        """
+        item_id = db_add_item(
+            content=content,
+            url=url,
+            source=source,
+            item_type=item_type,
+            metadata=metadata,
+        )
+        return self.get(item_id)
+
+    def list(
+        self,
+        limit: int = 20,
+        offset: int = 0,
+        item_type: Optional[str] = None,
+        order: str = "desc",
+    ) -> list[Item]:
+        """列出摘录
+
+        Args:
+            limit: 返回数量限制
+            offset: 偏移量
+            item_type: 筛选类型
+            order: 排序方向（desc/asc）
+
+        Returns:
+            Item 列表
+        """
+        rows = db_list_items(
+            limit=limit,
+            offset=offset,
+            item_type=item_type,
+            order=order,
+        )
+        return [Item.from_dict(row) for row in rows]
+
+    def get(self, item_id: int) -> Item:
+        """获取单条摘录
+
+        Args:
+            item_id: 摘录 ID
+
+        Returns:
+            Item 对象
+
+        Raises:
+            NotFoundError: 摘录不存在
+        """
+        row = db_get_item(item_id)
+        if row is None:
+            raise NotFoundError(f"Item {item_id} not found")
+        return Item.from_dict(row)
+
+    def get_optional(self, item_id: int) -> Optional[Item]:
+        """获取单条摘录（不存在返回 None）
+
+        Args:
+            item_id: 摘录 ID
+
+        Returns:
+            Item 对象或 None
+        """
+        row = db_get_item(item_id)
+        return Item.from_dict(row) if row else None
+
+    def delete(self, item_id: int) -> bool:
+        """删除摘录
+
+        Args:
+            item_id: 摘录 ID
+
+        Returns:
+            是否删除成功
+        """
+        return db_delete_item(item_id)
+
+    def search(
+        self,
+        query: str,
+        field: Optional[str] = None,
+        limit: int = 20,
+    ) -> list[Item]:
+        """搜索摘录
+
+        Args:
+            query: 搜索关键词
+            field: 搜索字段（content/url/source），None 表示全部
+            limit: 返回数量限制
+
+        Returns:
+            匹配的 Item 列表
+        """
+        rows = db_search_items(query=query, field=field, limit=limit)
+        return [Item.from_dict(row) for row in rows]
+
+    def count(self) -> int:
+        """获取摘录总数
+
+        Returns:
+            总数
+        """
+        return db_count_total()
+
+    # 链式调用支持（为 Agent 提供更友好的 API）
+    def search_query(self, query: str) -> "QueryBuilder":
+        """开始搜索查询
+
+        Example:
+            >>> client.search_query("AI").limit(5).execute()
+        """
+        return QueryBuilder(self, query)
+
+
+class QueryBuilder:
+    """查询构建器（链式调用）"""
+
+    def __init__(self, client: Client, query: str):
+        self._client = client
+        self._query = query
+        self._field: Optional[str] = None
+        self._limit = 20
+
+    def by_field(self, field: str) -> "QueryBuilder":
+        """指定搜索字段"""
+        self._field = field
+        return self
+
+    def limit(self, limit: int) -> "QueryBuilder":
+        """设置返回数量"""
+        self._limit = limit
+        return self
+
+    def execute(self) -> list[Item]:
+        """执行查询"""
+        return self._client.search(
+            query=self._query,
+            field=self._field,
+            limit=self._limit,
+        )
+
+
+class NotFoundError(Exception):
+    """摘录不存在异常"""
+    pass