Metadata-Version: 2.4
Name: qstclaw
Version: 0.1.8.post5
Summary: QSTClaw is a **personal assistant** that runs in your own environment. It talks to you over multiple channels (DingTalk, Feishu, QQ, Discord, iMessage, 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
License-File: LICENSE
Requires-Dist: agentscope==1.0.16.dev0
Requires-Dist: agentscope-runtime==1.1.0
Requires-Dist: httpx>=0.27.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.5
Requires-Dist: transformers>=4.30.0
Requires-Dist: torch>=2.5.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: python-telegram-bot>=20.0
Requires-Dist: twilio>=9.10.2
Requires-Dist: pywebview>=4.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: local
Requires-Dist: huggingface_hub>=0.20.0; extra == "local"
Provides-Extra: llamacpp
Requires-Dist: copaw[local]; extra == "llamacpp"
Requires-Dist: llama-cpp-python>=0.3.0; extra == "llamacpp"
Provides-Extra: mlx
Requires-Dist: copaw[local]; extra == "mlx"
Requires-Dist: mlx-lm>=0.10.0; sys_platform == "darwin" and extra == "mlx"
Provides-Extra: ollama
Requires-Dist: ollama>=0.6.1; extra == "ollama"
Provides-Extra: full
Requires-Dist: copaw[llamacpp,local,ollama]; extra == "full"
Requires-Dist: mlx-lm>=0.10.0; sys_platform == "darwin" and extra == "full"
Dynamic: license-file

<div align="center">

# qstclaw


<p align="center"><b>懂你所需，伴你左右。</b></p>

</div>

你的AI个人助理；安装极简、本地与云上均可部署；支持多端接入、能力轻松扩展。

> **核心能力：**
>
> **全域触达** — 钉钉、飞书、QQ、Discord、iMessage 等频道，一个 qstclaw 按需连接。
>
> **由你掌控** — 记忆与个性化由你掌控，本地或云端均可；定时与协作发往指定频道。
>
> **Skills 扩展** — 内置定时任务，自定义技能目录，qstclaw 自动加载，无绑定。
>
> <details>
> <summary><b>你可以用 qstclaw 做什么</b></summary>
>
> <br>
>
> - **社交媒体**：每日热帖摘要（小红书、知乎、Reddit），B 站/YouTube 新视频摘要。
> - **生产力**：邮件与 Newsletter 精华推送到钉钉/飞书/QQ，邮件与日历整理联系人。
> - **创意与构建**：睡前说明目标、自动执行，次日获得雏形；从选题到成片全流程。
> - **研究与学习**：追踪科技与 AI 资讯，个人知识库检索复用。
> - **桌面与文件**：整理与搜索本地文件、阅读与摘要文档，在会话中索要文件。
> - **探索更多**：用 Skills 与定时任务组合成你自己的 agentic app。
>
> </details>

---



## 目录

## 快速开始
### 从源码安装【清众开发人员注意阅读】

```bash
# 克隆 qstclaw.git 的 main 分支
git clone -b main http://10.7.11.140/ai/qstclaw.git
cd qstclaw
pip install -e .

```

#### 使用uv创建python虚拟环境
```bash
uv venv
.\.venv\Scripts\activate
uv sync
```

- **开发**（测试、格式化）：`pip install -e ".[dev]"`

**控制台**（构建前端）：在项目根目录执行 。
```bash
cd console
```
```bash
npm ci
```
```bash
npm run build
```
```bash
cd ..
```
```bash
# 只删除目录下的内容，保留目录本身：
Remove-Item -Recurse -Force -Path "src\copaw\console\*"
```
```bash
xcopy /s /e /y /q console\dist\* src\copaw\console\
```
```bash
qstclaw app
```
### 本地二开后打包
```
# 1. 构建前端
Remove-Item -Recurse -Force -Path "dist\*"
cd console

npm ci
npm run build
cd ..

# 2. 复制到 Python 包
Remove-Item -Recurse -Force -Path "src\copaw\console\*"
xcopy /s /e /y /q console\dist\* src\copaw\console\

# 3. 构建 wheel
pip install build
python -m build --outdir dist .

# 4. 上传 wheel 到 PyPI（需要提前清理旧版本包，否则上传报错）
twine upload dist\*.whl
```
### pip 安装 (推荐)

如果你习惯自行管理 Python 环境：

```bash
pip install qstclaw
qstclaw init --defaults
qstclaw app
```

在浏览器打开 **http://127.0.0.1:8888/** 即可使用控制台（与 qstclaw 对话、配置 Agent）。若要在钉钉、飞书、QQ 等 app 内对话。


### 一键安装（beta，持续完善中）

无需预装 Python — 安装脚本自动处理一切：
```bash
pip install qstclaw
```
初始化，可以省略

```bash
qstclaw init --defaults   # 或：qstclaw init（交互式）
```
启动控制台：
```bash
qstclaw app
```

<details>
<summary><b>安装选项</b></summary>

**macOS / Linux：**

```bash
# 安装指定版本
curl -fsSL ... | bash -s -- --version 0.0.2

# 从源码安装（开发/测试用）
curl -fsSL ... | bash -s -- --from-source

# 安装本地模型支持
bash install.sh --extras llamacpp    # llama.cpp（跨平台）
bash install.sh --extras mlx         # MLX（Apple Silicon）
bash install.sh --extras llamacpp,mlx

# 升级 — 重新运行安装命令即可
curl -fsSL ... | bash

# 卸载
qstclaw uninstall          # 保留配置和数据
qstclaw uninstall --purge  # 删除所有内容
```

**Windows（PowerShell）：**

```powershell
# 安装指定版本
irm ... | iex; .\install.ps1 -Version 0.0.2

# 从源码安装（开发/测试用）
.\install.ps1 -FromSource

# 安装本地模型支持
.\install.ps1 -Extras llamacpp      # llama.cpp（跨平台）
.\install.ps1 -Extras mlx           # MLX
.\install.ps1 -Extras llamacpp,mlx

# 升级 — 重新运行安装命令即可
irm ... | iex

# 卸载
qstclaw uninstall          # 保留配置和数据
qstclaw uninstall --purge  # 删除所有内容
```

</details>


## 本地模型

qstclaw 可在本机完全本地运行大模型，无需 API Key 或云端服务。

| 后端          | 适用场景                          | 安装                                                                 |
| ------------- | --------------------------------- | -------------------------------------------------------------------- |
| **llama.cpp** | 跨平台（macOS / Linux / Windows） | `pip install 'qstclaw[llamacpp]'` 或 `bash install.sh --extras llamacpp` |
| **MLX**       | Apple Silicon（M1/M2/M3/M4）      | `pip install 'qstclaw[mlx]'` 或 `bash install.sh --extras mlx`         |
| **Ollama**    | 跨平台（需要 Ollama 服务运行）    | `pip install 'qstclaw[ollama]'` 或 `bash install.sh --extras ollama`   |

安装后下载模型并开始对话：

```bash
qstclaw models download Qwen/Qwen3-4B-GGUF
qstclaw models # 选择已下载的模型
qstclaw app # 启动服务
```

也可在控制台界面中下载与管理本地模型。

---

## 文档

| 主题                                                      | 说明                                 |
| --------------------------------------------------------- | ------------------------------------ |
| [项目介绍](https://qstclaw.agentscope.io/docs/intro)        | qstclaw 是什么、怎么用                 |
| [快速开始](https://qstclaw.agentscope.io/docs/quickstart)   | 安装与运行（本地或魔搭创空间）       |
| [控制台](https://qstclaw.agentscope.io/docs/console)        | Web 界面：对话与 Agent 配置          |
| [频道配置](https://qstclaw.agentscope.io/docs/channels)     | 钉钉、飞书、QQ、Discord、iMessage 等 |
| [心跳](https://qstclaw.agentscope.io/docs/heartbeat)        | 定时自检与摘要                       |
| [本地模型](https://qstclaw.agentscope.io/docs/local-models) | 使用 llama.cpp 或 MLX 本地运行模型   |
| [CLI](https://qstclaw.agentscope.io/docs/cli)               | 初始化、定时任务、Skills、清理       |
| [Skills](https://qstclaw.agentscope.io/docs/skills)         | 扩展与自定义能力                     |
| [FAQ](https://qstclaw.agentscope.io/docs/faq)               | 常见问题与报错排查                   |
| [记忆](https://qstclaw.agentscope.io/docs/memory)           | 上下文管理与长期记忆                 |
| [配置与工作目录](https://qstclaw.agentscope.io/docs/config) | 工作目录与配置文件                   |

完整文档见本仓库 [website/public/docs/](website/public/docs/)。

---

## 常见问题

常见问题、排错指南与已知问题，请访问 **[FAQ 页面](https://qstclaw.agentscope.io/docs/faq)**。

---

## 路线图

| 方向 | 事项 | 状态 |
| --- | --- | --- |
| 横向拓展 | 更多频道、模型、Skills、MCP 等 — **欢迎社区贡献** | 征集中 |
| 已有功能扩展与完善 | 展示优化、下载提示、Windows 路径兼容等 — **欢迎社区贡献** | 征集中 |
| 兼容性与易用性 | 应用级打包（DMG、EXE） | 进行中 |
| | 一键部署：内置依赖、dev 扩展、安装/升级教程 | 进行中 |
| 版本发布与贡献规范 | 贡献文档与测试框架 | 进行中 |
| | 对社区贡献的积极响应 | 进行中 |
| | Vibe Coding 等 Agent 的贡献引导 | 计划中 |
| Bug 修复与功能增强 | 消息折叠/隐藏 | 计划中 |
| | Skills 与 MCP 运行时安装、热加载改进 | 计划中 |
| | 上下文管理与压缩（长工具返回、降低 token 消耗） | 计划中 |
| | 多模态支持 | 进行中 |
| 安全 | Shell 执行确认 | 计划中 |
| | 工具/Skills 安全性 | 计划中 |
| | 可配置安全等级 | 计划中 |
| 多模态 | 语音/视频通话与实时交互 | 长期规划 |
| 多智能体 | 基于 [AgentScope](https://github.com/agentscope-ai/agentscope)，原生支持多智能体协作 | 长期规划 |
| 沙箱 | 与 AgentScope Runtime 沙箱深度集成 | 长期规划 |
| 自愈 | 守护进程 Agent，实现自动恢复与健康监控 | 长期规划 |
| qstclaw 优化本地模型 | 针对 qstclaw 原生 Skills 与常见任务调优的本地模型，提升个人助理可用性 | 长期规划 |
| 大小模型协同 | 本地模型处理敏感数据，云端模型负责规划与编码；兼顾隐私、性能与能力 | 长期规划 |
| 云原生 | 与 AgentScope Runtime 深度集成，充分利用云端算力、存储与工具生态 | 长期规划 |
| Skills 生态 | 丰富 [AgentScope Skills](https://github.com/agentscope-ai/agentscope-skills) 仓库，提升优质 Skill 的发现与使用 | 长期规划 |

*状态说明：进行中 — 正在推进；计划中 — 已排期或设计中，也**欢迎贡献**；**征集中** — 我们**非常欢迎**社区参与；长期规划 — 中长期路线。*

### 参与贡献

qstclaw 在开放协作中持续演进，欢迎各种形式的参与！请参考上方 [路线图](#路线图)（尤其是标记为 **征集中** 的项）选择你感兴趣的方向，并阅读 [CONTRIBUTING](https://github.com/agentscope-ai/qstclaw/blob/main/CONTRIBUTING_zh.md) 了解如何开始。我们特别欢迎：

- **横向拓展** — 新频道、模型提供商、Skills、MCP。
- **已有功能扩展与完善** — 展示与交互优化、下载提示、Windows 路径兼容等。

欢迎在 [GitHub Discussions](https://github.com/agentscope-ai/qstclaw/discussions) 参与讨论、提出想法或认领任务。

---

