read-cli 0.2.0__py3-none-any.whl

read/core/models.py

@@ -0,0 +1,80 @@
+"""数据模型
+
+Core Library 的数据结构定义。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class Item:
+    """摘录数据模型
+
+    Attributes:
+        id: 主键 ID
+        content: 摘录内容
+        url: 链接
+        source: 来源备注
+        type: 数据类型（quote/article/code）
+        metadata: JSON 扩展字段
+        created_at: 创建时间（ISO 8601）
+        updated_at: 更新时间（ISO 8601）
+    """
+
+    id: int
+    content: Optional[str] = None
+    url: Optional[str] = None
+    source: Optional[str] = None
+    type: str = "quote"
+    metadata: Optional[str] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+    @property
+    def is_quote(self) -> bool:
+        """是否为文字摘录"""
+        return self.type == "quote" and self.content is not None
+
+    @property
+    def is_link(self) -> bool:
+        """是否为链接"""
+        return self.url is not None
+
+    @property
+    def display_text(self) -> str:
+        """显示文本（优先 content，其次 url）"""
+        if self.content:
+            return self.content
+        if self.url:
+            return self.url
+        return "(空)"
+
+    def to_dict(self) -> dict:
+        """转换为字典"""
+        return {
+            "id": self.id,
+            "content": self.content,
+            "url": self.url,
+            "source": self.source,
+            "type": self.type,
+            "metadata": self.metadata,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Item":
+        """从字典创建"""
+        return cls(
+            id=data["id"],
+            content=data.get("content"),
+            url=data.get("url"),
+            source=data.get("source"),
+            type=data.get("type", "quote"),
+            metadata=data.get("metadata"),
+            created_at=data.get("created_at"),
+            updated_at=data.get("updated_at"),
+        )

read/db/__init__.py

@@ -0,0 +1,12 @@
+"""数据库层"""
+
+from .connection import ReadDatabase, get_connection, close_connection, get_cursor, get_db_path
+from .schema import ReadSchemaManager, SCHEMA_VERSION, get_schema_version, set_schema_version, is_initialized, init_database
+from .utils import to_cents, from_cents
+
+__all__ = [
+    "ReadDatabase", "ReadSchemaManager",
+    "get_connection", "close_connection", "get_cursor", "get_db_path",
+    "SCHEMA_VERSION", "get_schema_version", "set_schema_version", "is_initialized", "init_database",
+    "to_cents", "from_cents",
+]

read/db/connection.py

@@ -0,0 +1,37 @@
+"""数据库连接管理模块
+
+继承 dong.db.Database，提供 read-cli 专用数据库访问。
+"""
+
+import sqlite3
+from typing import Iterator
+from contextlib import contextmanager
+
+from dong.db import Database as DongDatabase
+
+
+class ReadDatabase(DongDatabase):
+    """读咚咚数据库类 - 继承自 dong.db.Database
+
+    数据库路径: ~/.read/read.db
+    """
+
+    @classmethod
+    def get_name(cls) -> str:
+        return "read"
+
+
+# 兼容性函数
+def get_connection(db_path=None):
+    return ReadDatabase.get_connection()
+
+def close_connection():
+    ReadDatabase.close_connection()
+
+@contextmanager
+def get_cursor() -> Iterator[sqlite3.Cursor]:
+    with ReadDatabase.get_cursor() as cur:
+        yield cur
+
+def get_db_path():
+    return ReadDatabase.get_db_path()

read/db/schema.py

@@ -0,0 +1,60 @@
+"""数据库 Schema 定义和版本管理
+
+继承 dong.db.SchemaManager，管理 read-cli 的数据库 schema。
+"""
+
+from dong.db import SchemaManager
+from .connection import ReadDatabase
+
+SCHEMA_VERSION = "1.0.0"
+
+
+class ReadSchemaManager(SchemaManager):
+    """读咚咚 Schema 管理器"""
+
+    def __init__(self):
+        super().__init__(
+            db_class=ReadDatabase,
+            current_version=SCHEMA_VERSION
+        )
+
+    def init_schema(self) -> None:
+        self._create_articles_table()
+        self._create_indexes()
+
+    def _create_articles_table(self) -> None:
+        with ReadDatabase.get_cursor() as cur:
+            cur.execute("""
+                CREATE TABLE IF NOT EXISTS articles (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    title TEXT NOT NULL,
+                    author TEXT,
+                    url TEXT,
+                    notes TEXT,
+                    status TEXT DEFAULT 'reading',
+                    rating INTEGER,
+                    created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+                    updated_at TEXT DEFAULT CURRENT_TIMESTAMP
+                )
+            """)
+
+    def _create_indexes(self) -> None:
+        with ReadDatabase.get_cursor() as cur:
+            cur.execute("CREATE INDEX IF NOT EXISTS idx_articles_status ON articles(status)")
+            cur.execute("CREATE INDEX IF NOT EXISTS idx_articles_author ON articles(author)")
+
+
+# 兼容性函数
+def get_schema_version() -> str | None:
+    return ReadSchemaManager().get_stored_version()
+
+def set_schema_version(version: str) -> None:
+    ReadDatabase.set_meta(ReadSchemaManager.VERSION_KEY, version)
+
+def is_initialized() -> bool:
+    return ReadSchemaManager().is_initialized()
+
+def init_database() -> None:
+    schema = ReadSchemaManager()
+    if not schema.is_initialized():
+        schema.initialize()

read/db/utils.py

@@ -0,0 +1,272 @@
+"""CRUD 操作封装
+
+职责：
+- 封装所有数据库操作
+- 提供类型友好的接口
+- 处理业务逻辑验证
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from read.const import DEFAULT_LIMIT, DEFAULT_TYPE, get_timestamp
+
+
+def add_item(
+    content: Optional[str] = None,
+    url: Optional[str] = None,
+    source: Optional[str] = None,
+    item_type: str = DEFAULT_TYPE,
+    metadata: Optional[str] = None,
+) -> int:
+    """添加摘录，返回新 ID
+
+    Args:
+        content: 摘录内容
+        url: 链接
+        source: 来源备注
+        item_type: 数据类型
+        metadata: JSON 扩展字段
+
+    Returns:
+        新插入记录的 ID
+
+    Raises:
+        ValueError: content 和 url 都为空
+    """
+    from read.db.connection import get_cursor
+
+    # 验证
+    if not content and not url:
+        raise ValueError("content 和 url 至少需要一个不为空")
+
+    now = get_timestamp()
+
+    with get_cursor() as cursor:
+        cursor.execute(
+            """
+            INSERT INTO items (content, url, source, type, metadata, created_at, updated_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+            """,
+            (content, url, source, item_type, metadata, now, now),
+        )
+        return cursor.lastrowid
+
+
+def list_items(
+    limit: int = DEFAULT_LIMIT,
+    offset: int = 0,
+    item_type: Optional[str] = None,
+    order: str = "desc",
+) -> list[dict]:
+    """列出摘录
+
+    Args:
+        limit: 返回数量限制
+        offset: 偏移量
+        item_type: 筛选类型
+        order: 排序方向（desc/asc）
+
+    Returns:
+        摘录列表
+    """
+    from read.db.connection import get_cursor
+
+    order_sql = "DESC" if order.lower() == "desc" else "ASC"
+
+    with get_cursor() as cursor:
+        if item_type:
+            cursor.execute(
+                f"""
+                SELECT id, content, url, source, type, metadata, created_at, updated_at
+                FROM items
+                WHERE type = ?
+                ORDER BY created_at {order_sql}
+                LIMIT ? OFFSET ?
+                """,
+                (item_type, limit, offset),
+            )
+        else:
+            cursor.execute(
+                f"""
+                SELECT id, content, url, source, type, metadata, created_at, updated_at
+                FROM items
+                ORDER BY created_at {order_sql}
+                LIMIT ? OFFSET ?
+                """,
+                (limit, offset),
+            )
+
+        rows = cursor.fetchall()
+        return [dict(row) for row in rows]
+
+
+def get_item(item_id: int) -> Optional[dict]:
+    """获取单条摘录
+
+    Args:
+        item_id: 摘录 ID
+
+    Returns:
+        摘录数据，不存在返回 None
+    """
+    from read.db.connection import get_cursor
+
+    with get_cursor() as cursor:
+        cursor.execute(
+            """
+            SELECT id, content, url, source, type, metadata, created_at, updated_at
+            FROM items
+            WHERE id = ?
+            """,
+            (item_id,),
+        )
+        row = cursor.fetchone()
+        return dict(row) if row else None
+
+
+def delete_item(item_id: int) -> bool:
+    """删除摘录
+
+    Args:
+        item_id: 摘录 ID
+
+    Returns:
+        是否删除成功
+    """
+    from read.db.connection import get_cursor
+
+    with get_cursor() as cursor:
+        cursor.execute("DELETE FROM items WHERE id = ?", (item_id,))
+        return cursor.rowcount > 0
+
+
+def search_items(
+    query: str,
+    field: Optional[str] = None,
+    limit: int = DEFAULT_LIMIT,
+) -> list[dict]:
+    """搜索摘录
+
+    Args:
+        query: 搜索关键词
+        field: 搜索字段（content/url/source），None 表示全部
+        limit: 返回数量限制
+
+    Returns:
+        匹配的摘录列表
+    """
+    from read.db.connection import get_cursor
+
+    pattern = f"%{query}%"
+
+    with get_cursor() as cursor:
+        if field == "content":
+            cursor.execute(
+                """
+                SELECT id, content, url, source, type, metadata, created_at, updated_at
+                FROM items
+                WHERE content LIKE ?
+                ORDER BY created_at DESC
+                LIMIT ?
+                """,
+                (pattern, limit),
+            )
+        elif field == "url":
+            cursor.execute(
+                """
+                SELECT id, content, url, source, type, metadata, created_at, updated_at
+                FROM items
+                WHERE url LIKE ?
+                ORDER BY created_at DESC
+                LIMIT ?
+                """,
+                (pattern, limit),
+            )
+        elif field == "source":
+            cursor.execute(
+                """
+                SELECT id, content, url, source, type, metadata, created_at, updated_at
+                FROM items
+                WHERE source LIKE ?
+                ORDER BY created_at DESC
+                LIMIT ?
+                """,
+                (pattern, limit),
+            )
+        else:
+            # 全部字段
+            cursor.execute(
+                """
+                SELECT id, content, url, source, type, metadata, created_at, updated_at
+                FROM items
+                WHERE content LIKE ? OR url LIKE ? OR source LIKE ?
+                ORDER BY created_at DESC
+                LIMIT ?
+                """,
+                (pattern, pattern, pattern, limit),
+            )
+
+        rows = cursor.fetchall()
+        return [dict(row) for row in rows]
+
+
+def count_total() -> int:
+    """获取摘录总数"""
+    from read.db.connection import get_cursor
+
+    with get_cursor() as cursor:
+        cursor.execute("SELECT COUNT(*) as count FROM items")
+        row = cursor.fetchone()
+        return row["count"] if row else 0
+
+
+def update_item(
+    item_id: int,
+    content: Optional[str] = None,
+    url: Optional[str] = None,
+    source: Optional[str] = None,
+    metadata: Optional[str] = None,
+) -> bool:
+    """更新摘录（预留，v0.1 暂不通过 CLI 暴露）
+
+    Args:
+        item_id: 摘录 ID
+        content: 新内容
+        url: 新链接
+        source: 新来源
+        metadata: 新元数据
+
+    Returns:
+        是否更新成功
+    """
+    from read.db.connection import get_cursor
+
+    updates = []
+    params = []
+
+    if content is not None:
+        updates.append("content = ?")
+        params.append(content)
+    if url is not None:
+        updates.append("url = ?")
+        params.append(url)
+    if source is not None:
+        updates.append("source = ?")
+        params.append(source)
+    if metadata is not None:
+        updates.append("metadata = ?")
+        params.append(metadata)
+
+    if not updates:
+        return False
+
+    updates.append("updated_at = ?")
+    params.append(get_timestamp())
+    params.append(item_id)
+
+    with get_cursor() as cursor:
+        sql = f"UPDATE items SET {', '.join(updates)} WHERE id = ?"
+        cursor.execute(sql, params)
+        return cursor.rowcount > 0

read/mcp/__init__.py

@@ -0,0 +1,7 @@
+"""MCP Server - Model Context Protocol 服务端
+
+v0.2 版本功能，为 Claude/ChatGPT 等 Agent 提供原生集成。
+"""
+
+# v0.1 预留，v0.2 实现
+__all__ = []

read_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: read-cli
+Version: 0.2.0
+Summary: 读咚咚 (Read) - 个人知识数据层的命令行接口
+Author: gudong
+License: MIT
+License-File: LICENSE
+Keywords: agent,cli,knowledge,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: dong-core>=0.3.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=0.1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# 读咚咚 (Read) - 个人知识数据层
+
+> 读咚咚是个人知识数据层的 Python 库，提供 CLI、SDK 和 MCP Server 等多种访问方式。
+>
+> 本地、私有、可编程的个人知识基础设施。
+
+[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/Version-0.1.0-orange.svg)](https://github.com/gudong/read)
+
+---
+
+## 简介
+
+**读咚咚** 是一个个人知识数据层，以 **Core Library** 为核心资产，支持多种客户端访问。
+
+当你看到一句有启发的话、一篇好文章，快速存下来。CLI、浏览器插件、Agent 都可以访问这些数据。
+
+### 核心特点
+
+- **数据层优先** - Core Library 是核心，CLI/插件/SDK 都是客户端
+- **本地私有** - 数据存放在 `~/.read/read.db`，不上云、不同步、不追踪
+- **Agent 友好** - JSON 输出 + Python SDK + MCP Server（v0.2）
+- **极简核心** - 只做收集，不做整理
+
+---
+
+## 安装
+
+### 方式一：从 PyPI 安装（推荐）
+
+```bash
+pip install read-cli
+```
+
+### 方式二：从源码安装
+
+```bash
+git clone https://github.com/gudong/read.git
+cd read
+pip install -e .
+```
+
+### 初始化
+
+```bash
+read init
+```
+
+---
+
+## 安装 Agent Workspace
+
+如果你使用 OpenClaw，可以把 agent 目录复制到工作区：
+
+```bash
+# 复制 agent workspace
+mkdir -p ~/.openclaw/agents/read
+cp -r agent/* ~/.openclaw/agents/read/
+
+# 从模板创建 MEMORY.md
+cp agent/MEMORY.md.template ~/.openclaw/agents/read/MEMORY.md
+```
+
+---
+
+## 快速开始
+
+```bash
+# 添加摘录
+read add "开始，就是最好的时机"
+
+# 收藏文章
+read add --url "https://mp.weixin.qq.com/s/xxx"
+
+# 列出所有
+read ls
+
+# 搜索
+read search "AI"
+
+# 删除
+read delete 123 --force
+```
+
+---
+
+## 项目结构
+
+```
+read/
+├── src/read/           # CLI 源码
+├── agent/             # Agent workspace（OpenClaw 使用）
+│   ├── IDENTITY.md    # Agent 身份
+│   ├── SOUL.md        # Agent 性格
+│   ├── TOOLS.md       # CLI 工具定义
+│   └── MEMORY.md.template  # 记忆模板
+├── docs/              # 文档
+├── tests/             # 测试
+├── pyproject.toml     # Python 包配置
+└── README.md          # 本文件
+```
+
+---
+
+## Python SDK
+
+```python
+from read import Client
+
+client = Client()
+
+# 添加
+item = client.add("开始，就是最好的时机")
+
+# 列出
+items = client.list(limit=10)
+
+# 搜索
+results = client.search("AI")
+```
+
+---
+
+## 命令参考
+
+| 命令 | 说明 |
+|------|------|
+| `read init` | 初始化数据库 |
+| `read add "内容"` | 添加摘录 |
+| `read add --url "..."` | 收藏链接 |
+| `read ls` | 列出所有 |
+| `read search "关键词"` | 搜索 |
+| `read get 123` | 获取单条 |
+| `read delete 123` | 删除 |
+
+---
+
+## 架构设计
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    客户端层                              │
+├──────────────┬──────────────┬──────────────┬────────────┤
+│ CLI          │ Browser      │ Python SDK   │ MCP Server  │
+│ (read add)    │ Extension    │ (import)     │ (Agent)     │
+└──────────────┴──────────────┴──────────────┴────────────┘
+                             │
+                    ┌────────▼────────┐
+                    │   Core Library  │
+                    │ (read.core.Client)│
+                    └────────┬────────┘
+                             │
+                    ┌────────▼────────┐
+                    │   SQLite DB     │
+                    │   ~/.read/read.db │
+                    └─────────────────┘
+```
+
+---
+
+## 路线图
+
+| 版本 | 核心资产 | 客户端 | 状态 |
+|------|----------|--------|------|
+| v0.1 | Core Library v0.1 | CLI | ✅ 完成 |
+| v0.2 | Core Library v0.1 | **MCP Server** | 🚧 开发中 |
+| v0.3 | Core Library v0.1 | Python SDK 增强 | 📋 计划中 |
+| v0.4 | Core Library v0.1 | Browser Extension | 📋 计划中 |
+
+---
+
+## 文档
+
+- [API 参考文档](docs/API_REFERENCE.md)
+- [架构设计](ARCHITECTURE.md)
+- [产品理念](WHY.md)
+
+---
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+## 作者
+
+[@gudong](https://github.com/gudong)
+
+---
+
+**让 AI 看见你的知识。**