qwenpaw-usage

# QwenPaw 命令行使用技巧 本 Skill 覆盖两类高频场景：**心跳（Heartbeat）任务配置** 和 **打包部署 QwenPaw 实例到其他服务器**。 --- ## 场景一：添加 / 修改心跳（Heartbeat）任务 ### 什么是心跳 心跳是 QwenPaw 的定时自检机制：按固定间隔读取 `HEARTBEAT.md` 的内容作为用户消息发给 QwenPaw，QwenPaw 执行后可选择将回复投递到上次对话的频道。适合做「定期自检、每日摘要、定时提醒」。 ### 操作步骤 **1. 编写 HEARTBEAT.md** 文件位于工作目录下，默认路径：`~/.qwenpaw/HEARTBEAT.md`。 可通过环境变量 `QWENPAW_HEARTBEAT_FILE` 更改文件名。 直接用文本编辑器或 `cat` / `echo` 写入即可，内容是每次心跳要问 QwenPaw 的问题： ```markdown # Heartbeat checklist - 扫描收件箱紧急邮件 - 查看未来 2h 的日历 - 检查待办是否卡住 - 若安静超过 8h，轻量 check-in ``` > 文件为空则跳过心跳，不会触发任何操作。 **2. 配置心跳参数** 心跳参数有两层配置： - **全局默认**：`~/.qwenpaw/config.json` → `agents.defaults.heartbeat`（对所有智能体生效） - **智能体独立**：`~/.qwenpaw/workspaces/{agent_id}/agent.json` → `heartbeat`（覆盖全局默认） 可用字段： | 字段 | 类型 | 默认值 | 说明 | | --------------------- | ----------- | ----------- | ----------------------------------------------------------- | | `every` | string | `"30m"` | 间隔，支持 `Nh`、`Nm`、`Ns` 组合（如 `"1h30m"`） | | `target` | string | `"main"` | `"main"` 仅执行不投递；`"last"` 发到上次对话的频道/用户 | | `activeHours` | object/null | `null` | 可选活跃时段限制 | | `activeHours.start` | string | `"08:00"` | 开始时间（HH:MM） | | `activeHours.end` | string | `"22:00"` | 结束时间（HH:MM） | 配置示例（每 30 分钟自检，不发到频道，写在 config.json 中）： ```json "agents": { "defaults": { "heartbeat": { "every": "30m", "target": "main" } } } ``` 配置示例（每 1 小时，发到上次频道，限 08:00-22:00，写在 agent.json 中）： ```json "heartbeat": { "every": "1h", "target": "last", "activeHours": { "start": "08:00", "end": "22:00" } } ``` **3. 生效方式** 保存文件后，若服务正在运行会自动加载新配置。也可通过以下命令手动重载： ```bash qwenpaw daemon reload-config ``` > 注意：频道和 MCP 配置的变更需要在对话中执行 `/daemon restart` 或重启进程后才能生效。 ### 心跳 vs 定时任务 | | 心跳 | 定时任务 (cron) | | ---- | ------------------------------------------ | ---------------------------- | | 数量 | 每个智能体只有一份 HEARTBEAT.md | 可创建多个 | | 间隔 | 一个全局间隔 | 每个任务独立 cron 表达式 | | 投递 | 仅 `main`（不发）或 `last`（上次频道） | 每个任务独立指定频道和用户 | | 适用 | 固定的一套自检/摘要 | 多条不同时间、不同内容的任务 | > 如果用户需要的是「每天 9 点发早安到钉钉」「每 2 小时检查待办发到飞书」这类多条独立任务，应引导使用 `qwenpaw cron create`（参见下方定时任务部分），而非心跳。 ### 完整操作示例 用户说：「帮我添加一个 heartbeat 任务，每小时检查一下有没有新邮件，如果有就通知我」 执行步骤： ```bash # 1. 写入心跳内容 cat > ~/.qwenpaw/HEARTBEAT.md << 'EOF' # 心跳任务 - 检查收件箱是否有新邮件 - 如果有新的未读邮件，列出发件人和主题 - 如果有紧急邮件，标注提醒 EOF # 2. 编辑 agent.json 中的 heartbeat 配置 # 将 heartbeat 设为： # { # "every": "1h", # "target": "last", # "activeHours": { "start": "08:00", "end": "22:00" } # } # 3. 重载配置 qwenpaw daemon reload-config ``` --- ## 补充：定时任务（Cron）快速参考 当用户需要多条定时任务时，使用 `qwenpaw cron` 命令（需服务运行中）： ```bash # 创建 agent 类型任务（向 QwenPaw 提问并发结果到频道） qwenpaw cron create \ --type agent \ --name "检查邮件" \ --cron "0 */1 * * *" \ --channel dingtalk \ --target-user "USER_ID" \ --target-session "SESSION_ID" \ --text "检查收件箱有没有新邮件，如果有列出来" # 创建 text 类型任务（定时发固定文案） qwenpaw cron create \ --type text \ --name "每日早安" \ --cron "0 9 * * *" \ --channel dingtalk \ --target-user "USER_ID" \ --target-session "SESSION_ID" \ --text "早上好！新的一天开始了！" # 常用管理命令 qwenpaw cron list # 列出所有任务 qwenpaw cron get <job_id> # 查看任务配置 qwenpaw cron state <job_id> # 查看运行状态 qwenpaw cron pause <job_id> # 暂停任务 qwenpaw cron resume <job_id> # 恢复任务 qwenpaw cron run <job_id> # 立刻执行一次 qwenpaw cron delete <job_id> # 删除任务 # 从 JSON 文件创建（复杂配置） qwenpaw cron create -f job_spec.json ``` 可选参数：`--timezone`（默认用户时区）、`--enabled/--no-enabled`、`--mode`（`stream`/`final`）、`--base-url`、`--agent-id`。 Cron 表达式速查（五段式：分 时 日 月 周）： ``` 0 9 * * * 每天 09:00 0 */2 * * * 每 2 小时 30 8 * * 1-5 工作日 08:30 */15 * * * * 每 15 分钟 0 0 * * 0 每周日零点 ``` --- ## 场景二：打包 QwenPaw 实例部署到其他服务器 ### 方案概览 | 方案 | 适用场景 | 复杂度 | | --------------------------------- | -------------------------------------- | ------ | | **工作区导出 + 官方镜像** | 已有配置和记忆需迁移到新服务器（推荐） | 低 | | **docker-compose 快速部署** | 新服务器全新部署 | 低 | | **自定义 Dockerfile** | 需要定制镜像（加自定义依赖/技能） | 中 | ### 方案 A：工作区导出 + 官方 Docker 镜像（推荐） 最简单的方式：导出当前工作区，在新服务器上用官方镜像挂载。 **步骤 1：导出当前工作区** 通过控制台（智能体 -> 工作区 -> 下载）可将整个工作区下载为 `.zip` 文件。 或手动打包： ```bash # 打包工作目录（包含配置、对话、记忆、技能等） cd ~/.qwenpaw tar czf qwenpaw-workspace.tar.gz \ config.json \ workspaces/ ``` **步骤 2：在新服务器创建 docker-compose.yml** ```yaml version: '3.8' volumes: qwenpaw-data: name: qwenpaw-data qwenpaw-secrets: name: qwenpaw-secrets services: qwenpaw: image: agentscope/qwenpaw:latest container_name: qwenpaw restart: always ports: - "127.0.0.1:8088:8088" volumes: - qwenpaw-data:/app/working - qwenpaw-secrets:/app/working.secret environment: # 按需传入 API Key - DASHSCOPE_API_KEY=${DASHSCOPE_API_KEY} # 如需连接宿主机的 Ollama/LM Studio，取消下方注释 # - OLLAMA_BASE_URL=http://host.docker.internal:11434 # 如需连接宿主机服务，取消下方注释 # extra_hosts: # - "host.docker.internal:host-gateway" ``` > 国内用户可替换为 ACR 镜像：`agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/qwenpaw:latest` **步骤 3：恢复工作区** ```bash # 启动容器（会自动初始化默认配置） docker compose up -d # 找到数据卷挂载点 MOUNT_PATH=$(docker volume inspect qwenpaw-data --format '{{ .Mountpoint }}') # 将备份解压到数据卷 sudo tar xzf qwenpaw-workspace.tar.gz -C "$MOUNT_PATH" # 重启使配置生效 docker compose restart ``` 或在控制台中使用「上传工作区」功能恢复 `.zip` 文件（最大 100 MB）。 **步骤 4：验证服务** ```bash curl -s http://localhost:8088/api/agent/status | head -20 ``` ### 方案 B：docker-compose 全新部署 适合不需要迁移旧数据的场景。 ```bash # 1. 创建 docker-compose.yml（同方案 A 的 step 2） # 2. 通过环境变量传入 API Key echo "DASHSCOPE_API_KEY=your-key-here" > .env # 3. 启动 docker compose up -d # 4. 访问控制台完成初始化 # 浏览器打开 http://<server_ip>:8088 ``` 如需对外暴露，将 `127.0.0.1:8088:8088` 改为 `0.0.0.0:8088:8088`（注意安全风险，建议配合反向代理和认证）。 ### 方案 C：自定义 Dockerfile 当需要在镜像中预装自定义技能、额外 Python 包或特殊系统依赖时使用。 参考 Dockerfile： ```dockerfile # 基于官方镜像 FROM agentscope/qwenpaw:latest # 预装额外 Python 包 RUN pip install --no-cache-dir some-package another-package # 复制自定义技能 COPY my_skills/ /app/working/customized_skills/ # 复制自定义配置（可选） # COPY config.json /app/working/config.json # 如需更改默认端口 # ENV QWENPAW_PORT=3000 # EXPOSE 3000 ``` 构建并运行： ```bash docker build -t my-qwenpaw . docker run -d \ --name qwenpaw \ --restart always \ -p 127.0.0.1:8088:8088 \ -v qwenpaw-data:/app/working \ -v qwenpaw-secrets:/app/working.secret \ -e DASHSCOPE_API_KEY="your-key" \ my-qwenpaw ``` ### Docker 部署关键参数 | 环境变量 | 默认值 | 说明 | | -------------------------- | ----------------------------------------------- | ------------------ | | `QWENPAW_WORKING_DIR` | `/app/working` | 工作目录（容器内） | | `QWENPAW_SECRET_DIR` | `/app/working.secret` | 敏感数据目录 | | `QWENPAW_PORT` | `8088` | 服务端口 | | `QWENPAW_ENABLED_CHANNELS` | `discord,telegram,dingtalk,feishu,qq,console` | 启用的频道 | ### Docker 中连接本机模型服务 容器内 `localhost` 指向容器自身，需使用 `host.docker.internal`： ```bash docker run ... \ --add-host=host.docker.internal:host-gateway \ -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \ agentscope/qwenpaw:latest ``` --- ## 使用建议 - 用户描述模糊时，先询问确认：是要心跳（单一自检循环）还是定时任务（多条独立任务）？是要迁移现有实例还是全新部署？ - 涉及 API Key 等敏感信息时，引导用户使用环境变量或 `qwenpaw env set` 命令，不要在配置文件中明文写入。 - 多智能体场景下，几乎所有命令支持 `--agent-id` 参数，默认为 `default`。 - 配置修改后可用 `qwenpaw daemon reload-config` 热加载，无需重启服务。