Metadata-Version: 2.4
Name: lightclaw
Version: 0.0.23
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.11
Description-Content-Type: text/markdown
Requires-Dist: orcakit-sdk>=0.1.0
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: python-frontmatter>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-socks>=2.5.3
Requires-Dist: pymupdf>=1.24
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
Requires-Dist: pillow>=10.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: tiktoken>=0.7.0
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"
Requires-Dist: langchain-ollama>=1.0; extra == "ollama"
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"

# LightClaw — 更易用、更省钱、越用越懂你的 AI Agent

> **LightClaw** 是一个开源的 AI 个人助手，支持本地部署与云托管。相比 OpenClaw，它聚焦三个核心差异：**省钱** — Token 消耗大幅降低；**懂你** — 内置多层记忆系统，越用越贴合你的习惯；**好用** — 内置场景开箱即用，零配置直接上手。通过飞书、QQ、Web Dashboard 等渠道随时对话，所有能力由可扩展的 **Skills（技能）** 系统驱动。

---

## 🎯 为什么做 LightClaw？

OpenClaw 在实际使用中面临几个核心痛点：**场景打磨成本高**、**Token 消耗高**、**缺乏经验沉淀能力**。LightClaw 正是为了解决这些问题而生。

### 💰 更省钱 — Token 消耗降低一个数量级

- **智能多模型调度**：内置路由引擎，根据任务复杂度自动分配最经济的模型，简单任务用小模型、复杂任务才用大模型，避免资源浪费。
- **高效记忆管理**：通过精细的短期记忆裁剪与长期记忆压缩策略，大幅缩减每次请求的上下文长度，直接降低 Token 费用。
- **本地模型支持**：集成 LLaMA-CPP、MLX、Ollama 等本地推理后端，零 API 费用运行。

### 🧠 越用越懂你 — 内置记忆系统

- **长期记忆**：自动从对话中提取关键信息，沉淀为持久化的经验和偏好，不再每次都要重复说明背景。
- **用户画像**：持续学习你的习惯、风格、需求，助手的响应越来越贴合你。
- **对话摘要**：历史会话自动生成摘要存档，跨会话也能无缝衔接上下文。

### 🚀 更易用 — 开箱即用的场景化能力

- **内置实用场景**：深度集成公众号全链路运营、证券市场分析、新闻热点追踪、轻代码开发、AI 视频生成、智能教育等 6 大场景，无需额外配置即可直接使用。
- **一键部署**：`lightclaw init` 交互式向导完成全部配置，开箱即用。
- **多渠道无缝连接**：QQ、飞书、Web Dashboard，一个助手覆盖你的所有对话入口。
- **移动端深度优化**：界面与交互专为移动场景打造，随时随地使用。
- **OpenClaw 轻松迁移**：可将 OpenClaw 大模型、技能、渠道等配置平滑迁移至 LightClaw。

### 🔒 更安全 — 可信的私有化环境

- **本地优先**：所有配置、记忆、对话数据存储在 `~/.lightclaw/`，数据不离开你的设备。
- **原生账户体系**：支持密码登录等身份验证方式，保障访问安全。
- **技能安全前置校验**：对技能市场中的 Skill 进行安全性与合规性前置审核，降低第三方扩展风险。

---

## ⚔️ LightClaw vs OpenClaw

[OpenClaw](https://github.com/openclaw/openclaw) 是一款优秀的开源 AI 智能体平台，拥有成熟的插件生态和广泛的渠道支持。LightClaw 在 OpenClaw 的基础上，针对 **Token 消耗**、**记忆深度**和**上手门槛**三个方向做了重点优化。

| 对比维度 | OpenClaw | LightClaw |
|---------|----------|-----------|
| **技术栈** | Node.js，Monorepo 插件架构 | Python，LangGraph Agent 框架 |
| **Token 消耗** | 完整上下文透传，长对话成本较高 | 智能裁剪 + 多模型调度，上下文压缩降低消耗 |
| **记忆系统** | 持久化记忆，支持上下文延续 | 长期记忆 + 用户画像 + 对话摘要，多层记忆架构 |
| **模型支持** | 多供应商（Claude、GPT、Qwen 等）+ 本地模型（Ollama / llama.cpp） | 多供应商 + 本地模型（Ollama / LLaMA-CPP / MLX）+ 智能路由按任务复杂度自动分配 |
| **渠道支持** | 50+ 平台（Telegram、WhatsApp、Discord、Slack、飞书、钉钉、QQ 等） | 飞书、QQ、Web Dashboard（聚焦国内主流渠道） |
| **技能生态** | ClawHub 3000+ 社区技能，npm 插件包管理 | 5 个全局内置技能 + 6 个深度场景 + 技能市场 + MCP 协议 |
| **场景开箱度** | 通用框架，场景需要通过安装技能 + 配置来打磨 | 内置 6 个深度打磨场景（公众号运营、证券分析、新闻追踪、轻代码开发、视频剪辑、智能教育），零配置直接上手 |
| **部署方式** | brew / npm 一行安装，Gateway 架构 | 一键安装脚本 + `lightclaw init` 交互式向导 |
| **数据存储** | 本地优先，数据存储在用户设备 | 本地优先，数据存储在 `~/.lightclaw/` |
| **移动端体验** | 依赖第三方渠道客户端 | Web Dashboard 深度适配移动端 |
| **客户端** | CLI + macOS App + iOS/Android | CLI + Web Dashboard |
| **迁移支持** | — | 内置一键迁移工具，支持从 OpenClaw 无缝迁移配置、技能和工作区 |

---

## 📋 目录

- [为什么做 LightClaw？](#-为什么做-lightclaw)
- [LightClaw vs OpenClaw](#️-lightclaw-vs-openclaw)
- [快速开始](#-快速开始)
- [内置场景](#-内置场景)
- [配置指南](#️-配置指南)
- [Web Dashboard](#️-web-dashboard)
- [CLI 命令参考](#-cli-命令参考)
- [内置技能一览](#-内置技能一览)
- [工作区目录结构](#-工作区目录结构)
- [安全与隐私](#-安全与隐私)
- [系统架构](#️-系统架构)
- [前端开发](#️-前端开发)
- [代码质量与测试](#-代码质量与测试)
- [常见问题](#-常见问题)
- [许可证](#-许可证)

---

## 🚀 快速开始

只需 3 步，5 分钟内即可启动你的 AI 助手。

### 1. 一键安装

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

安装完成后，打开一个**新的终端窗口**，或手动加载环境：

```bash
source ~/.zshrc   # Zsh 用户
# 或
source ~/.bashrc  # Bash 用户
```

### 2. 初始化配置

```bash
lightclaw init
```

交互式向导会引导你完成：选择语言 → 选择 LLM 供应商 → 填写 API Key → 选择模型。

### 3. 启动服务

```bash
# 常规启动
lightclaw run

# 指定主机和端口（如需网络访问）
lightclaw run --host 0.0.0.0 --port 80

# 或注册为系统服务并启动（开机自启）
lightclaw start --host 0.0.0.0 --port 80
```

打开浏览器访问 Web Dashboard，开始与 LightClaw 对话吧！

---

## 🎮 内置场景

LightClaw 内置了多个深度打磨的场景（Scene）。每个场景不仅仅是一个技能，而是一套**完整的 Agent 配置包** — 包含专属人格（SOUL/IDENTITY）、专属技能、以及场景优化过的行为规则。

> **为什么是这几个场景？** 我们从 OpenClaw 社区的高频使用场景中筛选，优先覆盖六类需求：**信息获取**（每天发生了什么）、**投资决策辅助**（行情怎么样）、**内容创作分发**（写了文章怎么发出去）、**轻量开发**（快速把想法变成可运行的产品）、**视频创作**（把文字故事变成短视频）、**教育学习**（高效学习新知识、备考冲刺）。这几类场景的共性是：用户有强烈的**日常重复需求**，但现有工具要么需要在多个平台之间跳转，要么需要大量手动操作，要么门槛太高。LightClaw 的场景化设计让你一句话就能完成原来需要专业技能或多个工具才能做的事。

### ✍️ 微信公众号运营助手

> "帮我写一篇关于今天 AI 热点的公众号文章，写完直接发布"

不只是发布工具，而是**从选题到发布的全链路内容运营助手**。结合 LightClaw 的多项能力，形成完整闭环：

1. **热点发现** — 调用新闻技能从 70+ 平台抓取实时热点，帮你找到值得写的选题
2. **资料收集** — 通过浏览器自动化联网查询相关资料、数据、案例，为写作提供素材
3. **AI 写作** — 基于收集到的素材，利用 LLM 能力自动撰写 Markdown 格式的完整文章
4. **一键发布** — 通过 wenyan-cli 渲染精美公众号排版，自动上传图片素材，推送到公众号草稿箱

数据完全自主可控，不依赖第三方 SaaS 平台。微信端只推送到草稿箱，最终发布权始终在你手中。

**解决的问题**：内容创作者的日常是一条痛苦的长链路 — 刷热点找选题、搜资料做调研、写文章排版、上传发布，每一步都要在不同工具间跳转。现有的多平台分发工具大多只解决"最后一公里"的发布问题，且多为 SaaS 服务，数据需要托管给第三方。LightClaw 打通了从热点发现到自动发布的完整链路，一句话启动整个工作流，全程本地运行、数据完全可控。

### 📈 证券市场助手

> "帮我看看今天 A 股有什么值得关注的"

市场观察者「老钱」— 查行情、看基本面、做技术分析（MA/MACD/RSI/BOLL）、追市场热点。以 A 股为主，兼顾港美股及全球市场。底层接入 akshare 的 1090+ 数据接口，覆盖股票、基金、期货、债券、外汇、宏观经济等数据。

**解决的问题**：散户投资者获取行情数据需要在多个软件之间切换（同花顺看行情、东方财富看研报、雪球看讨论），且缺乏个性化分析。LightClaw 用自然语言对话替代了多工具跳转，一句话就能拉数据、跑指标、出分析。严格合规不荐股，只做信息整合和辅助判断。

### 📰 热点新闻趋势

> "帮我总结今天的科技新闻"

从微博、知乎、虎扑、B 站、抖音、百度、36 氪、Hacker News、GitHub Trending 等 **70+ 平台**实时抓取热点，筛选最有价值的内容，结合你的偏好生成个性化新闻简报。

**解决的问题**：每天在十几个 App 之间来回刷信息流，效率低、噪音大。LightClaw 帮你做信息漏斗 — 全网采集、智能筛选、一份简报搞定。配合定时任务，早上睁眼就能看到昨晚的全球要闻。

### 💻 轻代码开发助手

> "帮我做一个个人博客网站，要有暗色模式和文章搜索功能"

**从需求到上线的全栈开发助手**。不需要你会写代码，只需要描述你想要什么，LightClaw 会自动完成整个开发流程：

1. **需求分析** — 理解你的自然语言描述，拆解为具体的功能模块和技术方案
2. **代码生成** — 自动生成完整的前端页面、后端脚本、配置文件，支持 HTML/CSS/JS、Python、Node.js 等
3. **本地预览** — 启动本地开发服务器，让你实时预览效果、提出修改意见
4. **迭代优化** — 通过对话持续调整样式、功能、交互细节，直到满意为止
5. **一键发布** — 打包部署到云服务器或静态托管平台，生成可访问的公网链接

**解决的问题**：非技术用户有想法但不会写代码，找外包贵且沟通成本高；技术用户搭建小工具、原型页面、个人网站仍需要花大量时间在环境搭建和样板代码上。LightClaw 把"想法→可运行产品"的路径缩短到几句对话，让每个人都能快速把创意变成现实。

### 🎬 视频剪辑助手

> "帮我把这个故事拍成一个短视频"

**从文字剧本到成片的全自动视频生成工作流**。你只需要提供一段文字故事或剧本，LightClaw 通过 8 个步骤自动完成整部短视频的制作：

1. **解析剧本** — 理解故事结构，拆分为场景、角色、对话、动作
2. **设计角色** — 基于剧本描述，用 AI 生成每个角色的视觉外观设定
3. **设计场景** — 生成每个故事场景的环境设定（室内/室外、光线、氛围）
4. **生成分镜** — 将剧本转化为专业的分镜脚本，确定每个镜头的构图、景别、运动方式
5. **生成参考图** — 为每个分镜生成静态参考图，预览视觉效果
6. **生成镜头图片** — 基于参考图生成高质量的最终镜头画面
7. **生成镜头视频** — 将静态画面转化为动态视频片段（平移、缩放、转场）
8. **合成最终视频** — 拼接所有镜头、添加字幕和配乐，输出完整成片

底层基于大语言模型进行创意决策，结合火山引擎的图像和视频生成 API 实现视觉内容创作。支持**断点续跑**（中途暂停后从上次进度继续）、**手动编辑**（任意步骤人工调整后继续流程）、**AI 智能优化**（自动优化分镜节奏和画面构图）。

**解决的问题**：短视频创作门槛高 — 传统流程需要编剧写分镜、美术画概念图、后期用 Premiere/After Effects 剪辑合成，一个人根本搞不定。现有 AI 视频工具大多只能做单镜头生成，缺乏从剧本到成片的完整流水线。LightClaw 把专业影视制作的 8 步流程自动化，让一个人一段文字就能产出一部完整短视频。

### 🎓 智能教育助手

> "帮我制定一个 30 天学完线性代数的计划，每天帮我讲一节课并出练习题"

**你的专属 AI 家教**，覆盖从学习规划到考试冲刺的完整闭环：

1. **个性化学习计划** — 根据你的目标（考研、考证、兴趣学习）、当前水平和可用时间，自动生成分阶段学习路线图
2. **知识讲解** — 像真人老师一样逐个知识点讲解，支持追问、举例、类比，直到你真正理解
3. **联网取材** — 自动搜索最新教材、论文、教学视频、真题资源，补充权威学习素材
4. **智能出题** — 根据学习进度自动生成练习题、模拟卷，覆盖选择、填空、简答、编程等题型
5. **错题分析** — 记录每次做错的题目，分析薄弱知识点，针对性推送强化练习
6. **定时复习** — 结合艾宾浩斯遗忘曲线，通过定时任务自动推送复习提醒和闪卡

支持数学、编程、英语、物理、历史等**全学科覆盖**。可以上传 PDF 教材、课件、历年真题，LightClaw 自动解析内容并纳入教学体系。

**解决的问题**：自学效率低 — 找教材要翻半天、看完了不知道重点、做题没人讲解、复习没有计划。一对一家教贵且时间不灵活，在线课程是单向灌输无法互动。LightClaw 提供 7×24 小时的个性化教学，根据你的实际掌握程度动态调整进度和难度，真正做到"因材施教"。

---

## ⚙️ 配置指南

所有配置存储在 `~/.lightclaw/lightclaw.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 ID、App Secret |
| **QQ** | Bot AppID、Token |
| **Web Dashboard** | 默认启用，无需配置 |

### 管理技能

```bash
# 安装/启用技能
lightclaw skills install

# 查看已安装的技能
lightclaw skills
```

技能文件统一存放在 `~/.lightclaw/workspace/skills/` 目录中。技能是否启用记录在 `~/.lightclaw/lightclaw.json` 的 `skills.entries` 里。

### 配置定时任务

LightClaw 支持定时让助手自动执行任务，例如"每天早上 8 点发送新闻摘要"：

```bash
# 管理定时任务
lightclaw cron

# 查看已有定时任务
lightclaw cron list

# 添加新定时任务
lightclaw cron add
```

定时任务定义存储在 `~/.lightclaw/jobs.json` 中。

### MCP 服务集成

LightClaw 支持通过 Model Context Protocol（MCP）接入外部工具服务，配置方法：

1. 在 `~/.lightclaw/lightclaw.json` 中的 `mcp_servers` 字段添加 MCP 服务配置
2. LightClaw 支持 MCP 服务的**热加载**，修改配置后无需重启即可生效

---

## 🖥️ Web Dashboard

启动 LightClaw 后，在浏览器中访问 `http://localhost:80` 即可使用 Web Dashboard。

Web Dashboard 提供以下功能：
- 💬 **Chat**：与 LightClaw 进行实时对话
- 📋 **Sessions**：查看历史会话记录与消息详情
- ⚙️ **配置管理**：在线修改供应商、模型、渠道等设置
- 🧩 **技能管理**：查看、启用、禁用技能
- ⏰ **定时任务**：可视化管理 Cron 任务
- 🔗 **MCP 服务**：管理已接入的 MCP 工具服务
- 📊 **环境变量**：管理持久化的环境变量

---

## 📖 CLI 命令参考

| 命令 | 说明 |
|------|------|
| `lightclaw init` | 初始化 `~/.lightclaw/` 工作区，引导完成首次配置 |
| `lightclaw config` | 交互式重新配置（渠道、LLM、技能、环境变量） |
| `lightclaw run` | 启动 LightClaw（后端 API + Web Dashboard + 已配置渠道） |
| `lightclaw start` | 将 LightClaw 注册为系统服务并启动（systemd / launchd） |
| `lightclaw stop` | 停止系统服务 |
| `lightclaw restart` | 重启系统服务 |
| `lightclaw channels install` | 安装并配置聊天渠道 |
| `lightclaw skills install` | 安装技能 |
| `lightclaw models` | 管理 LLM 模型供应商与模型选择 |
| `lightclaw cron` | 管理定时任务 |
| `lightclaw chats` | 管理对话历史 |
| `lightclaw env` | 管理持久化环境变量 |
| `lightclaw clean` | 清理临时文件和缓存 |
| `lightclaw uninstall` | 卸载 LightClaw 并清理工作区 |

全局选项：

```bash
lightclaw run --host 0.0.0.0 --port 9090   # 自定义主机和端口
lightclaw -h                                 # 查看帮助信息
```

---

## 🧩 内置技能一览

LightClaw 的能力分为两层：**底层工具**（Agent 原生能力，始终可用）和**技能（Skill）**（可插拔的扩展模块，按需启用）。

> **技能的设计哲学**：底层工具解决 Agent 的"手脚"问题（读写文件、执行命令、操控浏览器），技能解决"脑子"问题 — 给 Agent 注入特定领域的知识和工作流程。一个技能本质上是一份 `SKILL.md` 指令文件 + 参考资料 + 脚本，告诉 Agent 在特定场景下应该怎么思考和行动。

### 全局内置技能

这 5 个技能随安装自动同步到工作区，覆盖了个人助手最高频的通用需求。

> **为什么是这 5 个？** 我们的选型逻辑是：哪些能力是「AI 个人助手」几乎每天都会用到的？答案是：**自动化**（定时任务）、**文档处理**（PDF 是最常见的非结构化数据格式）、**文件读取**（Agent 需要理解本地文件）、**生态扩展**（安装和创建新技能）。这 5 个技能构成了 LightClaw 的基础能力骨架，更多垂直领域能力通过场景和技能市场扩展。

| 技能 | 功能说明 | 使用示例 |
|------|---------|---------|
| `cron` | 定时任务管理 — 创建、查询、暂停、恢复、删除。支持固定消息和智能 Agent 回复两种模式，可投递到 Dashboard / 飞书 / QQ 等渠道 | "每天早上 9 点提醒我喝水"、"每周一发周报提醒" |
| `pdf` | PDF 全功能处理 — 读取提取文本和表格、合并拆分、旋转裁剪、添加水印、加密解密、OCR 扫描、填写表单、创建新 PDF | "把这份 PDF 里的表格提取出来"、"合并这两个 PDF" |
| `file-reader` | 读取本地文本文件（.txt / .md / .json / .yaml / .csv / .log / 代码等），大文件自动提取摘要 | "帮我看看这个日志文件有什么报错" |
| `skill-creator` | 技能开发全流程 — 创建新技能、修改优化现有技能、运行评估测试、基准对比性能、优化触发描述 | "帮我做一个每天查天气的技能" |
| `install-skill` | 从技能市场（SkillHub）搜索、安装和管理社区技能 | "有什么好玩的技能"、"帮我装一个翻译技能" |

### 底层内置工具

这些工具是 Agent 的原生能力，始终可用，不需要手动启用：

| 工具 | 功能说明 |
|------|---------|
| `execute_shell_command` | 执行 Shell 命令 |
| `read_file` / `write_file` / `edit_file` | 文件读取、创建、编辑 |
| `browser_use` | Playwright 浏览器自动化（网页访问、表单填写、数据提取、截图） |
| `desktop_screenshot` | 桌面 / 窗口截图 |
| `send_file_to_user` | 向用户发送文件（通过当前聊天渠道） |
| `get_current_time` | 获取当前系统时间 |

> **提示**：想要更多能力？对 LightClaw 说"帮我做一个 xxx 技能"，`skill-creator` 会自动生成代码、创建测试并迭代优化。也可以说"有什么好玩的技能"，从社区技能市场直接安装。

---

## 📁 工作区目录结构

`lightclaw init` 执行后会在用户目录下创建以下结构：

```
~/.lightclaw/                                ← BASE_DIR
├── lightclaw.json                           # 核心配置（供应商、模型、渠道凭证、技能启用状态等）
├── auth.json                                # 账户认证配置
├── jobs.json                                # 定时任务定义
├── chats.json                               # 对话历史元数据
├── .env                                     # 持久化环境变量
├── logs/                                    # 运行日志
│   ├── lightclaw.log                        # 当天日志
│   └── lightclaw.log.YYYY-MM-DD             # 历史日志（自动轮转）
├── media/                                   # 渠道下载的媒体文件（QQ等）
│
└── workspace/                               ← WORKING_DIR（Agent 工作空间）
    ├── AGENTS.md                            # Agent 行为规则
    ├── SOUL.md                              # 核心身份与行为原则
    ├── USER.md                              # 用户信息
    ├── IDENTITY.md                          # Agent 身份定义
    ├── TOOLS.md                             # 工具说明
    ├── HEARTBEAT.md                         # 心跳检查清单
    ├── MEMORY.md                            # 长期记忆（Agent 运行时自动维护）
    ├── PROFILE.md                           # 用户画像（Agent 从对话中学到的偏好与习惯）
    ├── BOOTSTRAP.md                         # 首次引导流程（完成后自动删除）
    │
    ├── skills/                              # 所有技能（内置同步 + 用户创建）
    │   └── <skill-name>/
    │       ├── SKILL.md
    │       ├── references/
    │       └── scripts/
    │
    ├── memory/                              # 消息持久化 & 对话摘要
    │   ├── messages.db                      # SQLite 消息数据库
    │   └── YYYY-MM-DD_channel_session.md    # 对话摘要记忆文件
    │
    ├── sessions/                            # 会话状态持久化
    │   └── <session_id>.langgraph.json
    │
    ├── uploads/                             # 用户上传文件
    │   ├── .meta/                           # 文件元数据
    │   └── .derived/                        # 衍生文本（文档解析结果）
    │
    └── custom_channels/                     # 自定义渠道插件
```

### 关键文件说明

- **`lightclaw.json`**：最核心的配置文件，包含 LLM 供应商设置、API Key、模型选择、渠道凭证，以及技能启用状态 `skills.entries`。建议通过 CLI 命令修改，也可以直接编辑。
- **`auth.json`**：账户认证配置，存储密码哈希等信息，保障 Web Dashboard 访问安全。
- **`workspace/*.md`**：Agent 的系统提示词文件。`AGENTS.md` 和 `SOUL.md` 定义核心行为，`MEMORY.md` 存储长期记忆，`PROFILE.md` 存储用户画像，均由 Agent 运行时自动维护。
- **`workspace/memory/`**：消息持久化层。`messages.db` 保存完整消息记录，摘要文件用于高效的上下文回忆。
- **`workspace/skills/`**：所有技能都存放在这里，包括从源码同步的内置技能和你自己创建的技能。
- **`.env`**：持久化环境变量，启动时会自动加载进进程环境。

---

## 🔒 安全与隐私

作为一个存储对话、记忆和个人偏好的 AI 助手，安全和隐私是 LightClaw 的核心设计原则。

### 数据本地存储

所有数据（配置、记忆、对话历史、上传文件）都存储在本地 `~/.lightclaw/` 目录中，**不会上传到任何第三方服务器**。你可以随时备份、迁移或删除这个目录。

### 哪些数据会发送给 LLM 供应商？

LightClaw 仅在需要 AI 响应时，将**当前对话上下文**发送给你配置的 LLM 供应商（如 OpenAI、DashScope 等）。具体包括：

- **发送**：当前对话消息、经裁剪的相关记忆摘要、技能执行结果
- **不发送**：`lightclaw.json` 配置、其他渠道的聊天记录、本地文件（除非你主动上传）、完整的消息数据库

如果你不希望任何数据离开设备，可以使用**本地模型**（Ollama / LLaMA-CPP / MLX），实现完全离线运行。

### 访问安全

- **账户认证**：Web Dashboard 支持密码登录保护，凭证存储在 `auth.json`（密码哈希，非明文）
- **API Key 管理**：所有 API Key 存储在本地 `lightclaw.json` 中，不会在日志中打印

### 技能安全

- **前置审核**：技能市场中的 Skill 经过安全性与合规性审核
- **透明执行**：所有技能源码可见，你可以随时查看 `~/.lightclaw/workspace/skills/` 中的技能代码

---

## 🏗️ 系统架构

```
┌──────────────────────────────────────────────────────┐
│                   LightClaw 应用                      │
│                                                      │
│  Web Dashboard (端口 80) ◄── REST ──► FastAPI        │
│                                                      │
│  渠道集成 (飞书、QQ、Web Dashboard)                    │
│                                                      │
│  Agent 引擎: ReAct Agent → 技能中心 → LLM            │
│                                                      │
│  配置 / 记忆 / 任务 (存储在 ~/.lightclaw/)             │
└──────────────────────────────────────────────────────┘
```

**请求处理流程：**

```
用户 (通过渠道) → ChannelManager → Runner → ReAct Agent
                                                 ↓
                                          LLM 供应商
                                                 ↓
                                          技能执行器
                                                 ↓
                                       响应 → 返回渠道
```

---

## 🖥️ 前端开发

如果你需要参与 Web Dashboard 的前端开发：

```bash
# 进入前端项目目录
cd dashboard

# 安装依赖
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 run --port 9090
```

### Q: 如何切换语言？

重新运行配置命令，或直接编辑 `~/.lightclaw/lightclaw.json` 中的 `language` 字段。

```bash
lightclaw config
```

### Q: 如何使用本地模型？

1. 通过 `lightclaw models switch` 命令切换到本地模型供应商（Ollama / LLaMA-CPP / MLX）
2. 选择或下载要使用的模型
3. 使用本地模型时零 API 费用，数据完全不离开设备

### Q: 如何将 LightClaw 设置为开机自启？

使用系统服务命令（支持 Linux systemd 和 macOS launchd）：

```bash
lightclaw start
```

### Q: 如何创建自定义技能？

有两种方式：
1. **让 LightClaw 帮你创建**：在对话中告诉 LightClaw 你需要什么技能，内置的 `skill-creator` 会自动生成
2. **手动创建**：在 `~/.lightclaw/workspace/skills/` 目录下创建技能文件夹，包含 `SKILL.md` 描述文件

### Q: 数据存储在哪里？

所有数据都存储在本地的 `~/.lightclaw/` 目录下，不会上传到任何第三方服务器。你可以随时备份或迁移这个目录。

---

## 📄 许可证

详见 [LICENSE](LICENSE) 文件。
