Metadata-Version: 2.4
Name: lightclaw
Version: 0.1.26
Summary: Self-hosted AI personal assistant with multi-channel chat, smart memory, and extensible skills.
License-Expression: MIT
Project-URL: Repository, https://git.woa.com/orcakit/finnie
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.14,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi<1.0,>=0.100.0
Requires-Dist: starlette<1.0,>=0.27.0
Requires-Dist: uvicorn>=0.40.0
Requires-Dist: wecom-aibot-sdk>=1.0.0
Requires-Dist: langchain>=1.2
Requires-Dist: langchain-openai>=1.1
Requires-Dist: langchain-anthropic>=1.1
Requires-Dist: langchain-tavily>=0.2.17
Requires-Dist: langgraph>=1.0
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: pydantic==2.12.5
Requires-Dist: pydantic-core==2.41.5
Requires-Dist: qdrant-client>=1.9.0
Requires-Dist: watchdog>=4.0.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: dingtalk-stream>=0.24.3
Requires-Dist: discord-py>=2.3
Requires-Dist: lark-oapi>=1.5.3
Requires-Dist: websocket-client>=1.6.0
Requires-Dist: apscheduler<4,>=3.11.2
Requires-Dist: langfuse<5,>=4
Requires-Dist: cryptography>=42.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: websockets>=12.0
Requires-Dist: mss>=9.0.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: playwright>=1.49.0
Requires-Dist: harness-browser>=0.1.2
Requires-Dist: pymupdf<2,>=1.24
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-frontmatter>=1.0.0
Requires-Dist: questionary>=2.1.1
Requires-Dist: segno>=1.6.1
Requires-Dist: googleapis-common-protos>=1.62
Requires-Dist: onnxruntime<1.24
Requires-Dist: fastembed<0.8,>=0.3.0
Requires-Dist: python-socketio[asyncio_client]>=5.0
Requires-Dist: edge-tts>=6.1.0
Requires-Dist: cos-python-sdk-v5>=1.9.0
Requires-Dist: python-multipart>=0.0.26
Provides-Extra: dev
Requires-Dist: pre-commit>=4.2.0; extra == "dev"
Requires-Dist: pytest>=8.3.5; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Provides-Extra: ollama
Requires-Dist: langchain-ollama>=1.0; extra == "ollama"
Requires-Dist: ollama>=0.4.0; extra == "ollama"
Provides-Extra: video-stt
Requires-Dist: faster-whisper>=1.1.0; extra == "video-stt"
Requires-Dist: numpy>=1.24.0; extra == "video-stt"
Requires-Dist: soundfile>=0.12.0; extra == "video-stt"
Provides-Extra: video-tts-edge
Requires-Dist: edge-tts>=6.1.0; extra == "video-tts-edge"
Provides-Extra: video-tts-kokoro
Requires-Dist: kokoro>=0.9.4; extra == "video-tts-kokoro"
Provides-Extra: video-tts-xtts
Requires-Dist: coqui-tts>=0.22.0; extra == "video-tts-xtts"
Provides-Extra: qq-voice
Requires-Dist: graiax-silkcoder>=0.3.0; extra == "qq-voice"
Provides-Extra: local-embedding
Dynamic: license-file

# Changelog

本文件记录项目的所有重要变更。

格式遵循 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)，版本号遵循 [语义化版本规范](https://semver.org/spec/v2.0.0.html)。

## [Unreleased]

## [0.1.26] - 2026-06-11

### 新增
- 为 `/api/models` 和 `/api/star-office` 读端点添加 JWT 认证
- 添加 embedding 接口 JWT 认证，统一路径为 `/api/embedding`

### 修复
- 重连时自动刷新一次性 ticket，修复 401 无限重连问题

## [0.1.23] - 2026-06-10

### 新增
- 重连时自动刷新一次性 ticket，修复 401 无限重连问题

## [0.1.22] - 2026-06-09

### 变更
- 重构多账号支持与配置解析逻辑，优化 config 与 channel 模块

## [0.1.21] - 2026-06-08

### 新增
- 新增 OpenAI 兼容的 `/v1/embeddings` HTTP 服务
- 优化 ACE 对新版 agent-chat 的支持

### 修复
- 修复引擎异常时部分历史记录未持久化的问题
- 修复设置向导中强制密码修改逻辑，加固 setup-done 端点安全性
- 修复终端二维码渲染过大导致无法扫描的问题

### 变更
- 优化记忆整理流程，支持 USER.md 内容分流

## [0.1.20] - 2026-06-02

### 修复
- 启动飞书 bot creator 前清理残留 Chromium 进程与单实例锁
- 修复飞书 bot creator 反 headless 检测问题，每次扫码前清理会话

### 变更
- 内置渠道改为懒加载，加速服务启动

## [0.1.18] - 2026-05-28

### 修复
- 修复 token budget 动态调整时丢弃图片内容的问题，保留多模态输入逻辑

## [0.1.17] - 2026-05-25

### 变更
- 锁定 pydantic 依赖为稳定版本，避免不兼容的预发布版本引入问题

## [0.1.16] - 2026-05-25

### 新增
- 浏览器工具迁移到 harness-browser，统一 agent 与 dashboard 的会话共享
- 新增 `browser_orckit` 纯 CDP 浏览器工具，基于 harness-browser

### 修复
- 修复打开 dashboard 面板时覆盖 agent 当前标签页的问题，保留 agent 标签页
- 修复今日 token 统计与自定义时间范围 token 统计错误
- 修复时区错乱问题
- 默认关闭 MEMORY.md 超长压缩，防止压缩篡改 MEMORY.md 格式

### 变更
- 优化记忆蒸馏提示词及输出文件格式
- 优化应用镜像制作脚本

## [0.1.15] - 2026-05-20

### 新增
- 定时任务支持为每个任务独立配置模型
- 新增环境变量开关，支持禁用 MEMORY.md 自动压缩
- 新增 CVM 迁移仪表盘技能（cvm migration dashboard）
- 新增集群诊断和 CVM AI 医生技能（cluster doctor、cvm ai doctor）

### 修复
- 修复关闭信号处理，避免定时任务调度时异常退出
- 跳过仅含模板占位内容的 HEARTBEAT.md，避免浪费 token

### 变更
- 优化定时任务调度配置的交互体验

## [0.1.14] - 2026-05-18

### 新增
- 新增 Chrome 扩展功能，支持侧边栏面板与后端通信
- 新增 lightclaw_assistant 技能，提供 LightClaw 使用帮助与引导

### 修复
- 修复 session 注入不带时间戳的问题

### 变更
- 技能卡片 UI 全面重构，布局与样式优化
- 欢迎屏幕新增快捷功能入口与动效优化
- Token 用量页面展示优化
- 前端国际化（i18n）文案补充与更新

## [0.1.13] - 2026-05-15

### 新增
- 升级提示中展示 PyPI CHANGELOG 发布说明
- 欢迎界面重新设计，UI 细节优化
- 新增 `/bgtokenusage` 斜杠命令及后台 token 消耗 API
- 主动记忆引入混合评分 + 触发计数惩罚，提升候选多样性
- 主动推送支持事件感知时间分桶，4 分支提示词，延迟回填
- 三态事件时间提取器，支持将来时语义
- Qdrant 可续跑回填脚本，补全事件时间字段
- Dashboard 快捷指令菜单新增 `/topics` 和 `/token`
- 新增按话题/会话级 token 流水账系统（UsageLedger）
- 全项目时区统一为 Asia/Shanghai（CST）
- 新增 PyPI 自动发布 skill

### 修复
- 修复新建对话出现幽灵话题（#?）的显示 bug
- 修复飞书首次运行浏览器启动可靠性问题
- 会话文件加载增加 UTF-8 容错与自愈机制
- 修复主动消息中 thinking block 残留及 delta 去重问题
- Cron 任务默认超时由 120s 调整为 600s
- 一键更新仅升级 lightclaw 自身，不再连带升级所有依赖
- 微信 markdown 过滤器适配 iLink 渲染兼容性
- 记录主动触达反馈，避免重复追问
- 修复后台内存任务 token 串流到用户会话的 bug（ContextVar 分桶）
- 修复主分支合并后 `/bgtokenusage` 命令丢失问题

### 变更
- 主动推送：无 embedding 时降级为 FTS 候选搜索
- 主动推送默认触发间隔调整

<p align="center">
  <img src="screenshots/banner.png" alt="LightClaw Banner" width="600" />
</p>

<h1 align="center">LightClaw</h1>

<p align="center">
  <strong>Self-hosted AI personal assistant — affordable, personalized, and ready to go.</strong>
</p>

<p align="center">
  <a href="https://www.python.org/downloads/"><img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-blue?logo=python&logoColor=white" /></a>
  <a href="https://github.com/orcakit/finnie/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green" /></a>
  <a href="https://github.com/orcakit/finnie/releases"><img alt="Version" src="https://img.shields.io/badge/version-0.0.23-orange" /></a>
  <a href="https://github.com/orcakit/finnie"><img alt="GitHub stars" src="https://img.shields.io/github/stars/orcakit/finnie?style=social" /></a>
</p>

<p align="center">
  <a href="README_zh.md">简体中文</a> · English
</p>

---

**LightClaw** is an open-source, self-hosted AI personal assistant built with Python. Compared to similar projects, it focuses on three key differentiators: **Cost-efficient** — significantly lower token consumption; **Personalized** — built-in multi-layer memory system that learns your preferences over time; **Ready to use** — 6 deeply optimized scenes out of the box, zero-config to get started.

Chat with LightClaw through Feishu, QQ, WeChat or the built-in Web Dashboard. All capabilities are driven by an extensible **Skills** system and the **MCP** (Model Context Protocol).

## ✨ Highlights

| | Feature | Description |
|---|---------|-------------|
| 💰 | **Cost-efficient** | Smart multi-model routing dispatches cheap models for simple tasks, large models only when needed. Aggressive context trimming and memory compression slash token costs by an order of magnitude. |
| 🧠 | **Memory System** | Long-term memory extraction, user profiling, and conversation summaries — the assistant gets smarter the more you use it. |
| 🎮 | **Built-in Scenes** | 6 production-ready scenes: WeChat Official Account operations, stock market analysis, news tracking, low-code development, AI video generation, and smart education. |
| 🔌 | **Multi-channel** | Feishu · QQ · DingTalk · Discord · Web Dashboard — one assistant across all your chat platforms. |
| 🧩 | **Extensible Skills** | 5 built-in skills + community SkillHub marketplace + MCP protocol for unlimited tool integration. |
| 🏠 | **Local-first** | All data stays in `~/.lightclaw/`. Supports fully offline mode with local LLMs (Ollama / LLaMA-CPP / MLX). |

## 🏗️ Tech Stack

| Layer | Technologies |
|-------|-------------|
| **Language** | Python 3.11+ |
| **Agent Framework** | LangChain + LangGraph (ReAct Agent) |
| **API Server** | FastAPI + Uvicorn |
| **Frontend** | React + TypeScript + Vite + Ant Design |
| **Memory** | Qdrant + SQLite FTS5 + Structured Fact System |
| **LLM Providers** | OpenAI · DashScope (Qwen) · Ollama · LLaMA-CPP · MLX |
| **Scheduling** | APScheduler |
| **Browser Automation** | Playwright |
| **MCP** | Model Context Protocol (stdio + HTTP + SSE) |
| **Build / Lint** | setuptools · ruff · pytest · pre-commit |

## 🚀 Quick Start

### Prerequisites

- Python **3.11 – 3.13**
- [uv](https://github.com/astral-sh/uv) (recommended) or pip

### 1. Install

```bash
# macOS / Linux — one-line installer
curl -fsSL https://finnie-1258344699.cos.ap-guangzhou.myqcloud.com/install.sh | bash
```

After installation, open a **new terminal** or reload your shell:

```bash
source ~/.zshrc   # Zsh
# or
source ~/.bashrc  # Bash
```

### 2. Initialize

```bash
lightclaw init
```

The interactive wizard walks you through: language → LLM provider → API key → model selection.

### 3. Run

```bash
# Start the server
lightclaw run

# Bind to a custom host/port
lightclaw run --host 0.0.0.0 --port 80

# Or register as a system service (auto-start on boot)
lightclaw start --host 0.0.0.0 --port 80
```

Open your browser and start chatting!

## 🎮 Built-in Scenes

LightClaw ships with 6 deeply optimized **Scenes** — each is a complete agent configuration package including a dedicated persona, specialized skills, and fine-tuned behavior rules.

| Scene | Description | Example Prompt |
|-------|-------------|----------------|
| ✍️ **WeChat Official Account** | End-to-end content pipeline: trending topic discovery → research → AI writing → one-click publish | "Write an article about today's AI news and publish it" |
| 📈 **Stock Market** | Market watcher with technical analysis (MA/MACD/RSI/BOLL), powered by 1090+ akshare data APIs | "What's happening in the A-share market today?" |
| 📰 **News & Trends** | Real-time aggregation from 70+ platforms (Weibo, Zhihu, HN, GitHub Trending, etc.) | "Summarize today's tech news" |
| 💻 **Low-code Dev** | Full-stack development assistant: requirements → code generation → preview → deploy | "Build me a personal blog with dark mode" |
| 🎬 **Video Production** | Text-to-video pipeline: script → storyboard → image generation → video synthesis | "Turn this story into a short video" |
| 🎓 **Smart Education** | Personalized AI tutor: study plans, lectures, exercises, mistake tracking, spaced repetition | "Create a 30-day plan to learn linear algebra" |

## 🧩 Built-in Skills

### Global Skills (always available)

| Skill | Description |
|-------|-------------|
| `cron` | Scheduled task management — create, list, pause, resume, delete. Supports text messages and agent-powered responses across all channels. |
| `pdf` | Full PDF processing — extract text/tables, merge, split, rotate, watermark, encrypt, OCR, form filling. |
| `file-reader` | Read local text files (.txt, .md, .json, .yaml, .csv, .log, code). Auto-summarizes large files. |
| `skill-creator` | Create, modify, evaluate, and benchmark custom skills. |
| `install-skill` | Search and install community skills from SkillHub. |

### Native Tools (always on)

| Tool | Description |
|------|-------------|
| `execute_shell_command` | Run shell commands |
| `read_file` / `write_file` / `edit_file` | File operations |
| `browser_use` | Playwright browser automation |
| `desktop_screenshot` | Desktop / window screenshot |
| `send_file_to_user` | Send files through the active channel |
| `get_current_time` | Get current system time |

## ⚙️ Configuration

All config lives in `~/.lightclaw/lightclaw.json`. Manage it via CLI or edit directly.

```bash
# View/switch LLM models
lightclaw models
lightclaw models switch

# Install chat channels
lightclaw channels install

# Manage skills
lightclaw skills
lightclaw skills install

# Manage cron jobs
lightclaw cron list
lightclaw cron create --help

# Manage environment variables
lightclaw env
```

### Supported LLM Providers

| Provider | Description | API Key Required |
|----------|-------------|:----------------:|
| OpenAI | GPT-4o, GPT-4, GPT-3.5, etc. | ✅ |
| DashScope | Alibaba Qwen series | ✅ |
| Ollama | Local Ollama server | ❌ |
| LLaMA-CPP | Local GGUF model inference | ❌ |
| MLX | macOS Apple Silicon local inference | ❌ |

### Supported Channels

| Channel | Credentials Needed |
|---------|-------------------|
| **Feishu** | App ID, App Secret |
| **QQ** | Bot AppID, Token |
| **DingTalk** | App Key, App Secret |
| **Discord** | Bot Token |
| **Web Dashboard** | Enabled by default |

## 📖 CLI Reference

| Command | Description |
|---------|-------------|
| `lightclaw init` | Initialize workspace at `~/.lightclaw/` |
| `lightclaw config` | Interactive re-configuration |
| `lightclaw run` | Start LightClaw (API + Dashboard + channels) |
| `lightclaw start` | Register & start as system service |
| `lightclaw stop` | Stop system service |
| `lightclaw restart` | Restart system service |
| `lightclaw channels install` | Install chat channels |
| `lightclaw skills install` | Install skills |
| `lightclaw models` | Manage LLM providers |
| `lightclaw cron` | Manage scheduled tasks |
| `lightclaw chats` | Manage conversation history |
| `lightclaw env` | Manage environment variables |
| `lightclaw clean` | Clean temp files and caches |
| `lightclaw uninstall` | Uninstall and clean workspace |

## 🖥️ Web Dashboard

After starting LightClaw, access the dashboard at `http://localhost:80`.

Features:
- 💬 **Chat** — Real-time conversation with LightClaw
- 📋 **Sessions** — Browse conversation history
- ⚙️ **Settings** — Configure providers, models, channels
- 🧩 **Skills** — Enable/disable skills
- ⏰ **Cron** — Visual cron job management
- 🔗 **MCP** — Manage MCP tool services
- 📊 **Env** — Manage environment variables

## 📁 Project Structure

```
~/.lightclaw/                          ← Data directory
├── lightclaw.json                     # Core config
├── auth.json                          # Authentication
├── jobs.json                          # Cron job definitions
├── chats.json                         # Conversation metadata
├── logs/                              # Runtime logs
└── workspace/                         ← Agent workspace
    ├── .env                           # Persistent env vars
    ├── AGENTS.md                      # Agent behavior rules
    ├── SOUL.md                        # Core identity & principles
    ├── MEMORY.md                      # Long-term memory
    ├── USER.md                        # User profile & agent self-portrait
    ├── skills/                        # All skills
    ├── memory/                        # Message DB & summaries
    ├── sessions/                      # Session state
    └── uploads/                       # User uploads
```

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────┐
│                    LightClaw App                     │
│                                                     │
│  Web Dashboard (port 80) ◄── REST ──► FastAPI       │
│                                                     │
│  Channel Integrations (Feishu, QQ, DingTalk, etc.)  │
│                                                     │
│  Agent Engine: ReAct Agent → Skill Hub → LLM        │
│                                                     │
│  Config / Memory / Jobs (stored at ~/.lightclaw/)   │
└─────────────────────────────────────────────────────┘

User (via channel) → ChannelManager → Runner → ReAct Agent
                                                    ↓
                                              LLM Provider
                                                    ↓
                                             Skill Executor
                                                    ↓
                                          Response → Channel
```

## 🔒 Security & Privacy

- **Local-first**: All data (config, memory, chats, uploads) stored locally at `~/.lightclaw/` — never uploaded to third-party servers.
- **Minimal data to LLM**: Only current conversation context and trimmed memory summaries are sent to LLM providers. Config, other channel chats, and the full message DB are never sent.
- **Fully offline mode**: Use local models (Ollama / LLaMA-CPP / MLX) for zero API calls and complete data isolation.
- **Access control**: Web Dashboard supports password authentication. Credentials stored as hashes, never plaintext.
- **Skill vetting**: Community skills in SkillHub undergo security and compliance review before publication.

## 🛠️ Development

### Frontend (Dashboard)

```bash
cd dashboard
npm install
npm run dev       # Dev server at http://localhost:80
npm run build     # Production build
npm run lint      # ESLint + TypeScript check
npm run format    # Prettier
```

### Backend

```bash
# Install dev dependencies
uv sync --extra dev

# Lint & format
ruff check . --fix
ruff format .

# Run tests
pytest
pytest -xvs       # Verbose, stop on first failure

# Type checking
mypy src/lightclaw/
```

## 🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Ensure code passes `ruff check` and `ruff format`
4. Add tests for new functionality
5. Submit a Pull Request

Please read the coding standards in `CLAUDE.md` for detailed guidelines.

## 📋 Changelog

### v0.0.1 (2026-03-17)

- 🎉 **Initial public release** — first open-source version of LightClaw
- 🎮 6 built-in scenes: WeChat Official Account, Stock Market, News & Trends, Low-code Dev, Video Production, Smart Education
- 🧠 Multi-layer memory system: long-term memory + user profiling + conversation summaries
- 💰 Smart multi-model routing for cost-efficient token consumption
- 🔌 Multi-channel support: Feishu, QQ, DingTalk, Discord, Web Dashboard
- 🧩 5 built-in skills + SkillHub marketplace + MCP protocol integration
- 🏠 Local-first architecture with full offline mode support (Ollama / LLaMA-CPP / MLX)
- 🖥️ Web Dashboard with chat, session management, settings, skill management, and cron jobs
- 📄 Added MIT License

## 📄 License

This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.

---

<p align="center">
  Made with ❤️ by the OrcaKit team
</p>
