lightclaw 0.0.1__tar.gz

lightclaw-0.0.1/PKG-INFO

@@ -0,0 +1,458 @@
+Metadata-Version: 2.4
+Name: lightclaw
+Version: 0.0.1
+Summary: LightClaw is a **personal assistant** that runs in your own environment. It talks to you over multiple channels (DingTalk, Feishu, QQ, Discord, etc.) and runs scheduled tasks according to your configuration. **What it can do is driven by Skills — the possibilities are open-ended.** Built-in skills include cron, PDF/Office handling, news digest, file reading, and more; you can add custom skills. All data and tasks run on your machine; no third-party hosting.
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: discord-py>=2.3
+Requires-Dist: dingtalk-stream>=0.24.3
+Requires-Dist: uvicorn>=0.40.0
+Requires-Dist: apscheduler<4,>=3.11.2
+Requires-Dist: playwright>=1.49.0
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: mss>=9.0.0
+Requires-Dist: reme-ai==0.3.0.0
+Requires-Dist: transformers>=4.30.0
+Requires-Dist: python-frontmatter>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: python-socks>=2.5.3
+Requires-Dist: onnxruntime<1.24
+Requires-Dist: lark-oapi>=1.5.3
+Requires-Dist: langchain>=1.2
+Requires-Dist: langgraph>=1.0
+Requires-Dist: langchain-openai>=1.1
+Requires-Dist: mcp>=1.26
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20
+Requires-Dist: googleapis-common-protos>=1.62
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.5; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pre-commit>=4.2.0; extra == "dev"
+Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
+Provides-Extra: ollama
+Requires-Dist: ollama>=0.4.0; extra == "ollama"
+
+# LightClaw — 自托管 AI 个人助手
+
+> **LightClaw** 是一个运行在你自己设备上的 AI 个人助手。它通过多种聊天渠道（钉钉、飞书、QQ、Discord、Web 控制台）与你对话，还能执行定时任务。所有能力由 **Skills（技能）** 驱动 —— 一套可扩展的模块系统，既有内置技能也支持用户自建。全部数据保存在本地，无需第三方托管。
+
+---
+
+## 📋 目录
+
+- [功能特性](#-功能特性)
+- [环境要求](#-环境要求)
+- [快速开始](#-快速开始)
+  - [1. 克隆仓库](#1-克隆仓库)
+  - [2. 安装 Python 环境](#2-安装-python-环境)
+  - [3. 初始化工作区](#3-初始化工作区)
+  - [4. 启动 LightClaw](#4-启动-lightclaw)
+- [配置指南](#-配置指南)
+  - [选择 LLM 模型](#选择-llm-模型)
+  - [配置聊天渠道](#配置聊天渠道)
+  - [管理技能](#管理技能)
+  - [配置定时任务](#配置定时任务)
+  - [MCP 服务集成](#mcp-服务集成)
+- [Web 控制台](#-web-控制台)
+- [CLI 命令参考](#-cli-命令参考)
+- [内置技能一览](#-内置技能一览)
+- [工作区目录结构](#-工作区目录结构)
+- [系统架构](#-系统架构)
+- [前端开发](#-前端开发)
+- [代码质量与测试](#-代码质量与测试)
+- [常见问题](#-常见问题)
+- [许可证](#-许可证)
+
+---
+
+## ✨ 功能特性
+
+| 特性 | 说明 |
+|------|------|
+| **多渠道支持** | 钉钉、飞书、QQ、Discord、Web 控制台，一个助手多端连接 |
+| **可扩展技能系统** | 内置 PDF/Office 处理、定时任务、新闻摘要、浏览器自动化、邮件管理等技能；支持用户自定义创建技能 |
+| **多 LLM 供应商** | OpenAI、DashScope（阿里千问）、Ollama、本地模型（LLaMA-CPP、MLX）等 |
+| **MCP 集成** | 支持 Model Context Protocol 服务接入，热加载 |
+| **定时任务** | 基于 APScheduler 的 Cron 任务管理，让助手自动执行周期性工作 |
+| **本地优先** | 所有配置、记忆、数据存储在 `~/.lightclaw/`，数据不离开你的设备 |
+
+---
+
+## 🔧 环境要求
+
+在开始之前，请确保你的系统满足以下条件：
+
+| 依赖 | 版本要求 | 说明 |
+|------|---------|------|
+| **Python** | 3.10 – 3.13 | 推荐使用 3.12 |
+| **Node.js** | 18+ | 仅在需要前端开发时安装 |
+| **操作系统** | macOS / Linux / Windows | 均支持，macOS 可额外使用 MLX 本地推理 |
+
+---
+
+## 🚀 快速开始
+
+### 1. 克隆仓库
+
+```bash
+git clone git@git.woa.com:orcakit/lightclaw.git
+cd lightclaw
+```
+
+### 2. 安装 Python 环境
+
+```bash
+# 创建虚拟环境
+python -m venv .venv
+
+# 激活虚拟环境
+# macOS / Linux:
+source .venv/bin/activate
+# Windows:
+.venv\Scripts\activate
+
+# 安装 LightClaw
+pip install ".[dev]"
+```
+
+#### 可选依赖
+
+根据你的需求安装额外的本地推理后端：
+
+```bash
+# LLaMA-CPP 本地推理（支持 macOS / Linux / Windows）
+pip install ".[llamacpp]"
+
+# MLX 本地推理（仅 macOS Apple Silicon）
+pip install ".[mlx]"
+
+# Ollama 集成
+pip install ".[ollama]"
+```
+
+### 3. 初始化工作区
+
+首次使用时需要执行初始化，该命令会在 `~/.lightclaw/` 下创建配置文件和目录结构：
+
+```bash
+lightclaw init
+```
+
+初始化过程中，CLI 将以**交互式向导**引导你完成以下配置：
+
+1. **选择语言**：中文 / English
+2. **选择 LLM 供应商**：OpenAI、DashScope（阿里千问）、Ollama、本地模型等
+3. **填写 API Key**：根据选择的供应商输入对应的密钥
+4. **选择模型**：从供应商的可用模型列表中选择
+
+### 4. 启动 LightClaw
+
+```bash
+# 启动应用（后端 + Web 控制台）
+lightclaw run
+```
+
+或通过 Python 模块启动：
+
+```bash
+python -m lightclaw run
+```
+
+启动后：
+- 🌐 **Web 控制台**：`http://localhost:80`
+- 🔌 **后端 API**：`http://localhost:8088`
+
+你现在可以打开浏览器访问 Web 控制台，开始与 LightClaw 对话了！
+
+---
+
+## ⚙️ 配置指南
+
+所有配置存储在 `~/.lightclaw/config.json` 中，你可以通过 CLI 命令或直接编辑文件来修改配置。
+
+### 选择 LLM 模型
+
+LightClaw 支持多种 LLM 供应商，使用以下命令管理：
+
+```bash
+# 查看当前模型配置
+lightclaw models
+
+# 交互式切换供应商/模型
+lightclaw models switch
+```
+
+支持的供应商：
+
+| 供应商 | 说明 | 需要 API Key |
+|--------|------|:----------:|
+| OpenAI | GPT-4o、GPT-4、GPT-3.5 等 | ✅ |
+| DashScope | 阿里千问系列 | ✅ |
+| Ollama | 本地 Ollama 服务 | ❌ |
+| LLaMA-CPP | 本地 GGUF 模型推理 | ❌ |
+| MLX | macOS Apple Silicon 本地推理 | ❌ |
+
+### 配置聊天渠道
+
+使用以下命令安装和配置聊天渠道：
+
+```bash
+# 安装渠道（交互式选择）
+lightclaw channels install
+```
+
+各渠道的配置要求：
+
+| 渠道 | 需要的凭证 |
+|------|-----------|
+| **钉钉** | App Key、App Secret |
+| **飞书** | App ID、App Secret |
+| **QQ** | Bot AppID、Token |
+| **Discord** | Bot Token |
+| **iMessage** | macOS 本地 iMessage（无需额外配置） |
+| **Web 控制台** | 默认启用，无需配置 |
+
+### 管理技能
+
+```bash
+# 安装/启用技能
+lightclaw skills install
+
+# 查看已安装的技能
+lightclaw skills
+```
+
+技能安装后会存放在 `~/.lightclaw/active_skills/` 目录中。你也可以在 `~/.lightclaw/customized_skills/` 中创建自定义技能。
+
+### 配置定时任务
+
+LightClaw 支持定时让助手自动执行任务，例如"每天早上 8 点发送新闻摘要"：
+
+```bash
+# 管理定时任务
+lightclaw crons
+
+# 查看已有定时任务
+lightclaw crons list
+
+# 添加新定时任务
+lightclaw crons add
+```
+
+定时任务定义存储在 `~/.lightclaw/jobs.json` 中。
+
+### MCP 服务集成
+
+LightClaw 支持通过 Model Context Protocol（MCP）接入外部工具服务，配置方法：
+
+1. 在 `~/.lightclaw/config.json` 中的 `mcp_servers` 字段添加 MCP 服务配置
+2. LightClaw 支持 MCP 服务的**热加载**，修改配置后无需重启即可生效
+
+---
+
+## 🖥️ Web 控制台
+
+启动 LightClaw 后，在浏览器中访问 `http://localhost:80` 即可使用 Web 控制台。
+
+Web 控制台提供以下功能：
+- 💬 **对话界面**：与 LightClaw 进行实时对话
+- ⚙️ **配置管理**：在线修改供应商、模型、渠道等设置
+- 🧩 **技能管理**：查看、启用、禁用技能
+- ⏰ **定时任务**：可视化管理 Cron 任务
+- 🔗 **MCP 服务**：管理已接入的 MCP 工具服务
+- 📊 **环境变量**：管理持久化的环境变量
+
+---
+
+## 📖 CLI 命令参考
+
+| 命令 | 说明 |
+|------|------|
+| `lightclaw init` | 初始化 `~/.lightclaw/` 工作区，引导完成首次配置 |
+| `lightclaw run` | 启动 LightClaw（后端 API + Web 控制台 + 所有已配置渠道） |
+| `lightclaw channels install` | 安装并配置聊天渠道 |
+| `lightclaw skills install` | 安装技能 |
+| `lightclaw models` | 管理 LLM 模型供应商与模型选择 |
+| `lightclaw crons` | 管理定时任务 |
+| `lightclaw chats` | 管理对话历史 |
+| `lightclaw env` | 管理持久化环境变量 |
+| `lightclaw clean` | 清理临时文件和缓存 |
+| `lightclaw uninstall` | 卸载 LightClaw 并清理工作区 |
+
+全局选项：
+
+```bash
+lightclaw --host 0.0.0.0 --port 9090 run   # 自定义主机和端口
+lightclaw -h                                 # 查看帮助信息
+```
+
+---
+
+## 🧩 内置技能一览
+
+| 技能 | 功能说明 |
+|------|---------|
+| `cron` | 创建和管理定时任务，让 LightClaw 定期自动执行指定工作 |
+| `pdf` | PDF 文档的提取、编辑、合并 |
+| `xlsx` | Excel 电子表格的读取和写入 |
+| `pptx` | PowerPoint 演示文稿的读取和创建 |
+| `docx` | Word 文档的读取和编辑 |
+| `file_reader` | 读取文本、JSON、YAML 等格式的文件 |
+| `news` | 获取新闻并生成摘要 |
+| `browser_visible` | 浏览器自动化操作与网页截图 |
+| `himalaya` | 基于 IMAP 协议的邮件管理 |
+| `skill-creator` | 帮助你创建自定义技能的内置工具 |
+| `find-skills` | 搜索和发现更多可用技能 |
+
+> 💡 **提示**：你可以通过 `skill-creator` 技能让 LightClaw 帮你创建全新的自定义技能，无需手动编写代码。
+
+---
+
+## 📁 工作区目录结构
+
+`lightclaw init` 执行后会在用户目录下创建以下结构：
+
+```
+~/.lightclaw/
+├── config.json              # 核心配置文件（供应商、模型、渠道凭证等）
+├── jobs.json                # 定时任务定义
+├── chats.json               # 对话历史记录
+├── envs.json                # 持久化环境变量
+├── active_skills/           # 已启用的技能
+├── customized_skills/       # 用户自定义技能
+├── custom_channels/         # 自定义渠道插件
+└── memory/
+    ├── MEMORY.md            # 长期记忆（LightClaw 从对话中学到的信息）
+    ├── PROFILE.md           # 用户画像（你的偏好和习惯）
+    └── YYYY-MM-DD.md        # 每日笔记
+```
+
+### 关键文件说明
+
+- **`config.json`**：最核心的配置文件，包含 LLM 供应商设置、API Key、模型选择、渠道凭证等。建议通过 CLI 命令修改，也可以直接编辑。
+- **`memory/`**：LightClaw 的记忆系统。MEMORY.md 存储长期记忆，PROFILE.md 存储用户画像，每日笔记自动记录。
+- **`active_skills/`**：将技能文件夹放入此目录即可启用对应技能。
+- **`customized_skills/`**：你自己创建的技能存放在这里。
+
+---
+
+## 🏗️ 系统架构
+
+```
+┌──────────────────────────────────────────────────────┐
+│                   LightClaw 应用                         │
+│                                                      │
+│  React 控制台 (端口 80) ◄── REST ──► FastAPI (8088)  │
+│                                                      │
+│  渠道集成 (钉钉、飞书、QQ、Discord…)                   │
+│                                                      │
+│  Agent 引擎: ReAct Agent → 技能中心 → LLM            │
+│                                                      │
+│  配置 / 记忆 / 任务 (存储在 ~/.lightclaw/)               │
+└──────────────────────────────────────────────────────┘
+```
+
+**请求处理流程：**
+
+```
+用户 (通过渠道) → ChannelManager → Runner → ReAct Agent
+                                                 ↓
+                                          LLM 供应商
+                                                 ↓
+                                          技能执行器
+                                                 ↓
+                                       响应 → 返回渠道
+```
+
+---
+
+## 🖥️ 前端开发
+
+如果你需要参与 Web 控制台的前端开发：
+
+```bash
+# 进入前端项目目录
+cd console
+
+# 安装依赖
+npm install
+
+# 启动开发服务器（访问 http://localhost:80）
+npm run dev
+
+# 构建生产版本
+npm run build
+
+# 代码检查（ESLint + TypeScript）
+npm run lint
+
+# 代码格式化（Prettier）
+npm run format
+```
+
+前端技术栈：React + TypeScript + Vite + Ant Design
+
+---
+
+## ✅ 代码质量与测试
+
+```bash
+# 代码格式化（行宽 79 字符）
+python -m black src/lightclaw/
+
+# Lint 检查
+flake8 src/lightclaw/
+
+# 类型检查
+mypy src/lightclaw/
+
+# 运行 pre-commit 钩子
+pre-commit run --all-files
+
+# 运行全部测试
+pytest
+
+# 详细模式运行，遇到首个失败即停止
+pytest -xvs
+```
+
+---
+
+## ❓ 常见问题
+
+### Q: 启动时端口被占用怎么办？
+
+使用自定义端口启动：
+
+```bash
+lightclaw --port 9090 run
+```
+
+### Q: 如何切换语言？
+
+重新运行初始化命令，或直接编辑 `~/.lightclaw/config.json` 中的 `language` 字段。
+
+### Q: 如何使用本地模型？
+
+1. 安装对应的本地推理后端：
+   ```bash
+   pip install ".[llamacpp]"   # 或 ".[mlx]"（仅 macOS）
+   ```
+2. 通过 `lightclaw models` 命令切换到本地模型供应商
+3. 选择或下载要使用的模型
+
+### Q: 如何创建自定义技能？
+
+有两种方式：
+1. **让 LightClaw 帮你创建**：在对话中告诉 LightClaw 你需要什么技能，内置的 `skill-creator` 会自动生成
+2. **手动创建**：在 `~/.lightclaw/customized_skills/` 目录下创建技能文件夹，包含 `SKILL.md` 描述文件
+
+### Q: 数据存储在哪里？
+
+所有数据都存储在本地的 `~/.lightclaw/` 目录下，不会上传到任何第三方服务器。你可以随时备份或迁移这个目录。
+
+---
+
+## 📄 许可证
+
+详见 [LICENSE](LICENSE) 文件。