Metadata-Version: 2.4
Name: copal-app
Version: 2026.4.7
Summary: Enhanced CoPaw fork with dynamic prompt management, context control, agent delegation, and layered knowledge management.
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: agentscope==1.0.18
Requires-Dist: agentscope-runtime==1.1.4
Requires-Dist: httpx>=0.27.0
Requires-Dist: markdownify>=0.14.1
Requires-Dist: packaging>=24.0
Requires-Dist: discord-py>=2.3
Requires-Dist: dingtalk-stream>=0.24.3
Requires-Dist: alibabacloud-dingtalk>=2.2.42
Requires-Dist: alibabacloud-tea-openapi>=0.4.4
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.1.8
Requires-Dist: transformers>=4.30.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
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: paho-mqtt>=2.0.0
Requires-Dist: wecom-aibot-python-sdk==1.0.2
Requires-Dist: matrix-nio>=0.24.0
Requires-Dist: markdown-it-py>=3.0.0
Requires-Dist: shortuuid>=1.0.0
Requires-Dist: google-genai>=1.67.0
Requires-Dist: tzdata>=2024.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: json-repair>=0.30.0
Requires-Dist: segno>=1.6.6
Requires-Dist: modelscope>=1.35.0
Requires-Dist: huggingface_hub>=0.20.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: anyio<4.13.0,>=4.0.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"
Requires-Dist: hypothesis>=6.0.0; extra == "dev"
Provides-Extra: local
Requires-Dist: huggingface_hub>=0.20.0; extra == "local"
Provides-Extra: llamacpp
Requires-Dist: copal[local]; extra == "llamacpp"
Requires-Dist: llama-cpp-python>=0.3.0; extra == "llamacpp"
Provides-Extra: mlx
Requires-Dist: copal[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: whisper
Requires-Dist: openai-whisper>=20231117; extra == "whisper"
Provides-Extra: full
Requires-Dist: copal[llamacpp,local,ollama,whisper]; extra == "full"
Requires-Dist: mlx-lm>=0.10.0; sys_platform == "darwin" and extra == "full"
Dynamic: license-file

# CoPal

基于 [QwenPaw](https://github.com/agentscope-ai/QwenPaw) 的增强分支，在上游基础上增加了 Claude Code 透传模式、动态 Prompt 管理、跨模型兼容、对话体验优化等功能。

## 相比 QwenPaw 的改动

### 易用性改进

- **输入框内容缓存** — 切换对话时，输入框中未发送的草稿自动保存到 `sessionStorage`，切回时恢复
- **对话级模型绑定** — 对话首次使用时自动记录当前模型配置，已存在对话保持原模型不变
- **对话列表锁定与排序** — 支持置顶（pin），置顶对话可拖拽排序，未置顶按最近更新时间倒序
- **MCP 并行连接** — 启动时所有已启用的 MCP 客户端通过 `asyncio.gather` 并行连接，单个失败不阻塞其他
- **提示词子文件挂载** — 工作区的 `.md` 提示词文件支持挂载同名子目录，子目录内可放置多个附属 `.md` 文件
- **对话列表导航按钮** — 聊天界面输入区域注入 4 个导航按钮，方便在长对话中快速定位

### 新增功能

- **Claude Code 透传模式** — 在 Channels 页面配置 Claude Code 透传，支持启用/禁用、指定 CLI 路径和默认工作目录
- **动态 Prompt 管理** — Session 级别的系统提示词热插拔，斜杠命令 `/prompts`、`/prompt add|remove|reset`，前端面板管理
- **提示词库** — 团队级 prompt 管理系统，支持广播、同步、ZIP 整体下载/上传
- **智能体模板** — 内置模板系统，支持从预设配置一键创建 Agent
- **Sub-agent 模板管理** — 管理 Sub-agent 的 system prompt、工具集和可见范围
- **共享 MCP 配置** — 跨 Agent 的集中式 MCP 配置，支持广播和同步
- **对话管理** — 重新设计的对话模型，每个对话拥有独立 UUID，支持批量删除
- **跨模型 Tool ID 归一化** — 解决对话中途切换模型时的工具调用 ID 格式不兼容问题
- **上下文 Thinking Block 自动裁剪** — 自动剥离历史对话中的 thinking block 以节省 token
- **上下文管理完整降级链** — 6 级降级链（预处理 → Snip → Session Memory → AutoCompact → 硬截断 → 阻断）
- **语音朗读（TTS）** — 支持浏览器内置 TTS和服务端 TTS（DashScope Qwen-TTS / OpenAI TTS）
- **`ask_user` 交互式问答** — Agent 主动向用户提问，支持批量问题、单选/多选
- **Task DAG 调度系统** — 事件驱动的任务调度器，支持 DAG 依赖编排、并行执行、双执行器
- **定时任务管理** — `cron_create` / `cron_delete` / `cron_list`

### Agent 工具能力增强

- `edit_file` — 新增唯一性检查和 `replace_all` 参数
- `write_file` — 新增防覆盖机制（read-before-write + staleness detection）
- `read_file` — 输出增加行号前缀
- `grep_search` — 优先使用 ripgrep（`rg`）加速搜索，未安装时自动 fallback
- `execute_shell_command` — 大输出采用 head-tail 截断策略
- 新增：`web_fetch`、`web_search`、`ask_user`、Task 系列、Cron 系列

### UI / UX 优化

- 全局 Card 边框和阴影统一
- MCP 卡片重新设计（工具列表弹窗、查看/编辑模式统一）
- 页面布局优化（保存/重置按钮移至右上角 PageHeader）

### 基础变更

| 项目             | QwenPaw                 | CoPal                 |
| ---------------- | --------------------- | --------------------- |
| 包名 / CLI 命令  | `qwenpaw`             | `copal`             |
| 工作目录         | `~/.qwenpaw`          | `~/.copal`          |
| 默认端口         | 8088                  | 8090                  |
| 工作目录环境变量 | `QWENPAW_WORKING_DIR` | `COPAL_WORKING_DIR` |

## 安装

### 前置依赖

- **Python 3.10–3.13**
- **Node.js**（含 npm，用于构建 Web Console 前端）
- **ripgrep**（可选，加速代码搜索；安装时自动下载）

### Linux / macOS

```bash
git clone https://github.com/buggiant-coder/copal.git && cd copal
bash scripts/install.sh                # 标准安装
bash scripts/install.sh --from-source  # 从本地源码安装（开发用）
bash scripts/install.sh --extras dev   # 包含开发依赖
```

### Windows

```powershell
# PowerShell
git clone https://github.com/buggiant-coder/copal.git && cd copal
.\scripts\install.ps1                # 标准安装
.\scripts\install.ps1 -FromSource    # 从本地源码安装

# 或 cmd.exe
scripts\install.bat                  # 标准安装
```

### 从 PyPI 安装（不需要 git）

```bash
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/buggiant-coder/copal/main/scripts/install.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/buggiant-coder/copal/main/scripts/install.ps1 | iex
```

## 快速开始

```bash
copal init --defaults   # 初始化 ~/.copal/config.json（自动下载 ripgrep）
copal app               # 启动服务 http://127.0.0.1:8090
```

`copal init` 会自动检测并下载 ripgrep 到 `~/.copal/bin/`，无需手动安装。

## 开发

```bash
# 后端（可编辑安装）
pip install -e ".[dev,full]"
copal app --reload --log-level debug

# 前端
cd console
npm ci
npm run dev            # Vite 开发服务器 http://localhost:5173

# 前后端分离开发时设置 CORS
export COPAW_CORS_ORIGINS="http://localhost:5173,http://127.0.0.1:5173"
```

## 上游同步

合并上游 QwenPaw 变更的操作指南见 `_for_merge/MERGE_GUIDE.md`。
