Qclaw Workbuddy Bridge

QClaw 与 WorkBuddy 任务分发集成桥。当用户想要： - 通过微信让 QClaw 发送任务给 WorkBuddy 执行 - QClaw 写任务 → WorkBuddy 执行 → 微信推送结果 - 打通 QClaw（微信入口）和 WorkBuddy（执行引擎） - 远程任务分发、跨客户端任务执行 触发词...

Security Scan

The skill is broadly coherent with a file-based queue bridge, but documentation and runtime instructions contain inconsistencies and the prompts encourage automatic writing of tasks that may include local file paths—these issues warrant caution before installing.

Purpose & Capability

The stated purpose (a simple QClaw ↔ WorkBuddy bridge using a shared JSON queue) matches the included Python queue manager and the documented file-based architecture. Nothing in the code requires cloud credentials or unrelated system access. However, SKILL.md contains inconsistent command paths (references to qclaw_tasks.py in ~/.workbuddy/queue vs the actual script qclaw_queue.py located in ~/.workbuddy/skills/...), which is an incoherence between documentation and shipped files.

Instruction Scope

The runtime instructions tell QClaw to proactively write tasks into the queue whenever many broad conditions are met (including when tasks require access to local files). That behavior is plausible for a delegation bridge, but it expands the agent's authority and can lead to unintended exposure of local file paths and data. The WorkBuddy side is instructed to "自主执行任务（调用所有需要的工具、Skill 完成工作）", granting broad discretion to use other tools/skills when executing tasks. Also the docs inconsistently reference different script paths/filenames (qclaw_tasks.py vs qclaw_queue.py), which could cause misconfiguration and unintended execution of files in the queue directory.

Install Mechanism

No install spec (instruction-only with a helper script) — lowest-risk install behavior. The only code is a small Python script that reads/writes JSON files under ~/.workbuddy; no downloads or external installers are included.

Credentials

The skill requests no environment variables or credentials, which is proportionate. However, the design intentionally passes file paths and user/context information through the queue; if users or QClaw supply sensitive local paths, WorkBuddy (or any automation processing the queue) may access those files. The SKILL.md instructs QClaw to ask for local file paths and include them in the task context, which is functionally necessary but increases data-exposure risk.

Persistence & Privilege

The skill does not request always:true and does not modify other skills’ configurations. It writes files under the user's home (~/.workbuddy) which is expected for a user-space queue bridge. No privileged system changes are performed.

What to consider before installing

What to check and do before installing: - Fix the path/filename inconsistency: SKILL.md sometimes tells QClaw to run python3 ~/.workbuddy/queue/qclaw_tasks.py, but the shipped script is scripts/qclaw_queue.py under ~/.workbuddy/skills/qclaw-workbuddy-bridge/. Confirm which path will be installed and update all commands to the same, correct path. A mismatched path can cause failed runs or accidental execution of a different script placed in the queue directory. - Review and limit what QClaw will automatically enqueue. The provided prompt encourages automatic queuing for many conditions (including tasks that access local files). Consider restricting automatic enqueuing to explicit user consent, or require a confirmation step before writing tasks that include local file paths or sensitive context. - Restrict file paths and privileges for WorkBuddy execution. Because tasks may include local paths, ensure WorkBuddy runs in a sandbox, or add validation to prevent reading sensitive system files. Use least privilege for any automations that process queue entries. - Protect the queue directory: set tight filesystem permissions (owner-only) and monitor/validate files placed in ~/.workbuddy/queue. Because some doc commands reference executing scripts under ~/.workbuddy/queue, ensure no untrusted files can be executed from that location. - Test in a safe environment first: run the scripts locally on a non-production account to validate behavior (add/list/poll/done) and confirm triggers and file writes behave as expected. - If you need higher assurance, request the author to (a) correct documentation inconsistencies, (b) include optional safeguards (confirmation prompts, path whitelists), and (c) sign or package the script in a predictable install location so QClaw/WorkBuddy run the intended code.

QClaw ↔ WorkBuddy 任务分发桥

通过共享 JSON 队列文件，实现 QClaw（微信入口）和 WorkBuddy（执行引擎）的双向打通。

架构概览

微信消息
    ↓
QClaw（解析意图） → 写入任务到队列文件
    ↓
WorkBuddy（自动化轮询） → 读取任务 → 执行 → 写回结果
    ↓
QClaw（读取结果） → 微信推送回复给用户

• 队列文件: ~/.workbuddy/queue/qclaw_tasks.json
• 队列管理器: ~/.workbuddy/skills/qclaw-workbuddy-bridge/scripts/qclaw_queue.py
• 轮询方式: WorkBuddy 自动化（recurring）定期检查队列

---

第一步：安装与初始化

1.1 验证依赖

# 确认 Python 3 已安装
python3 --version

# 确认队列目录存在
ls ~/.workbuddy/queue/
# 首次运行会自动创建

1.2 初始化队列文件

python3 ~/.workbuddy/skills/qclaw-workbuddy-bridge/scripts/qclaw_queue.py list

---

第二步：在 QClaw 侧配置

QClaw 通过对话解析用户意图，将需要 WorkBuddy 执行的任务写入队列。

QClaw 提示词配置（发送给 QClaw）

在 QClaw 的自定义提示词或系统提示中加入以下规则：

---
你有一个新的能力：当用户请求的任务需要：
- 生成长文档、报告、PPT、Excel
- 深度数据分析或研究
- 需要访问本地文件的复杂操作
- 定时自动化任务
- 批量文件处理

你应主动将任务写入队列文件，格式如下：

任务分发触发条件（满足任一即写入）：
1. 用户说"帮我生成/制作/分析/整理..."
2. 涉及文件创建、数据处理、多步骤操作
3. 用户说"远程执行"、"交给 WorkBuddy"、"你做不到的事"

写入命令：
```bash
python3 ~/.workbuddy/queue/qclaw_tasks.py add "任务描述"

如果任务复杂，先简要总结（100字内），再写入队列。

队列文件路径：/.workbuddy/queue/qclaw_tasks.json 队列管理脚本：/.workbuddy/skills/qclaw-workbuddy-bridge/scripts/qclaw_queue.py

### 快速手动测试（QClaw 侧）

```bash
# 添加一个测试任务
python3 ~/.workbuddy/skills/qclaw-workbuddy-bridge/scripts/qclaw_queue.py add "帮我查一下今天的天气并生成出行建议"

# 查看队列
python3 ~/.workbuddy/skills/qclaw-workbuddy-bridge/scripts/qclaw_queue.py list

# 只看待处理任务
python3 ~/.workbuddy/skills/qclaw-workbuddy-bridge/scripts/qclaw_queue.py list --status pending

---

第三步：在 WorkBuddy 侧配置自动化

3.1 创建轮询自动化

在 WorkBuddy 中创建定时自动化：

• 名称: qclaw-bridge-poll
• 触发频率: 每 5 分钟一次（FREQ=MINUTELY;INTERVAL=5）
• 执行内容: 见下方自动化脚本

3.2 自动化执行脚本

创建自动化时，在 prompt 中填入：

检查任务队列 ~/.workbuddy/queue/qclaw_tasks.json 中是否有 status="pending" 的任务。

如果有，按以下步骤处理：

1. 先运行：
   python3 ~/.workbuddy/skills/qclaw-workbuddy-bridge/scripts/qclaw_queue.py poll --once

2. 读取返回的 JSON 任务内容，提取 input.description 作为任务描述

3. 自主执行任务（调用所有需要的工具、Skill 完成工作）

4. 任务完成后，将结果写入队列：
   python3 ~/.workbuddy/skills/qclaw-workbuddy-bridge/scripts/qclaw_queue.py done <task_id> - << 'EOF'
   {"summary": "一句话结果描述", "details": "详细说明", "files": ["文件路径列表"]}
   EOF

5. 如果执行失败：
   python3 ~/.workbuddy/skills/qclaw-workbuddy-bridge/scripts/qclaw_queue.py error <task_id> "失败原因"

如果队列为空，不做任何操作，直接退出。

---

第四步：QClaw 读取结果并推送

自动化推送脚本（WorkBuddy 端）

任务完成后，WorkBuddy 可以主动将结果写入一个结果文件：

# 在 WorkBuddy 自动化中，完成任务后调用：
python3 ~/.workbuddy/skills/qclaw-workbuddy-bridge/scripts/qclaw_queue.py result <task_id>

QClaw 读取结果（轮询模式）

QClaw 可以设置一个定期检查结果的逻辑：

定期检查结果：
每 5 分钟检查一次 ~/.workbuddy/queue/qclaw_tasks.json
找出所有 status="done" 且尚未推送的任务
将 result.summary 通过微信消息发送给用户
然后将任务 status 改为 "pushed"

---

队列任务数据结构

{
  "version": "1.0",
  "tasks": [
    {
      "id": "a1b2c3d4",
      "created_at": "2026-04-15T08:30:00+08:00",
      "status": "pending",
      "input": {
        "description": "帮我生成一份本周的工作周报",
        "intent": "用户原始意图描述",
        "context": {
          "user": "刘博",
          "project": "ITS系统"
        }
      },
      "result": {
        "summary": "周报已生成，共5个工作项",
        "details": "...",
        "files": ["/path/to/weekly_report.md"]
      },
      "done_at": null,
      "error": null
    }
  ]
}

队列操作命令速查

操作	命令
添加任务	python3 .../qclaw_queue.py add "任务描述" [--intent "意图"]
查看队列	python3 .../qclaw_queue.py list [--status pending]
等待任务	python3 .../qclaw_queue.py poll --once
获取结果	python3 .../qclaw_queue.py result <task_id>
标记完成	python3 .../qclaw_queue.py done <task_id> <result.json>
标记失败	python3 .../qclaw_queue.py error <task_id> "原因"
更新状态	python3 .../qclaw_queue.py status <task_id> <new_status>

---

场景示例

场景 1：微信说"帮我生成周报"

QClaw 侧:

用户: 帮我生成本周的工作周报
→ QClaw 识别为复杂任务，写入队列
→ python3 .../qclaw_queue.py add "生成本周工作周报，包含ITS系统进展和下周计划"

WorkBuddy 侧（自动化触发）:

→ 读取任务，识别为"生成周报"
→ 询问/查找本周的工作内容
→ 调用 Word/DOCX Skill 生成周报文档
→ 完成后写入结果

结果推送:

✅ 周报已生成！
📄 文件: ~/weekly_report_2026-04-15.docx
📝 摘要: 包含ITS系统、配置管理、问题管理等5个工作项

场景 2：微信说"帮我分析这份Excel"

QClaw 侧:

用户: 帮我分析一下这份销售数据
→ QClaw 询问用户文件路径
→ 用户提供路径后，写入队列
→ python3 .../qclaw_queue.py add "分析销售数据，生成可视化图表和关键洞察" --ctx '{"file": "/path/to/sales.xlsx"}'

---

进阶：多用户支持

如果需要支持多用户场景，可以在队列中加入 user_id 字段：

{
  "input": {
    "description": "...",
    "user_id": "liubo",
    "reply_to": "wechat"
  }
}

WorkBuddy 在处理时根据 user_id 区分用户，结果通过对应渠道推送。

---

故障排查

问题	原因	解决方法
队列文件不存在	首次未初始化	运行 qclaw_queue.py list 自动创建
自动化没触发	频率太低/自动化暂停	改为每 1 分钟或手动触发一次
结果未推送	QClaw 未轮询结果	检查 QClaw 侧结果读取逻辑
权限错误	队列文件无读写权限	chmod 600 ~/.workbuddy/queue/qclaw_tasks.json