copal-app 2026.4.7

Enhanced CoPaw fork with dynamic prompt management, context control, agent delegation, and layered knowledge management.

CoPal

基于 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

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
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）

# 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

快速开始

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

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

开发

# 后端（可编辑安装）
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。