QoderWake文件监控：目录变化触发自动构建

QoderWake 支持三种自动构建触发方式，各自适配不同场景：其一，基于 Qt 的 QFileSystemWatcher 本地监听，延迟低且响应迅速；其二，Linux 专属的 inotify + Webhook 桥接方案，适用于无图形界面的环境；其三，复用防腐治理模块进行哈希/时间戳比对，安全合规等级达到最高标准。

如果你已经配置好 QoderWake，期望它在目标目录内容发生增删改时自动触发构建，却发现变更未被识别、构建也未启动，那么问题通常集中在三个方面：文件系统监听未启用、路径配置不正确、事件与工作流之间的绑定缺失。下面将详细说明实现文件监控并自动触发的几种技术路线。

一、基于 QFileSystemWatcher 集成的本地目录监听

这条路径直接利用 Qt 框架自带的 QFileSystemWatcher 类，在 QoderWake 运行环境中嵌入一套轻量级的跨平台文件系统监听能力。它不依赖外部服务，延迟控制在 200 毫秒以内，特别适合开发机、CI 边缘节点等可信的本地环境。具体操作分四步：

1. 先确认 QoderWake 的运行环境已加载 Qt5.15+ 或 Qt6.2+ 运行时库，执行 qoderwake --check-deps 验证 QFileSystemWatcher 是否可用。

2. 在 QoderWake 配置目录 config/integrations/ 下新建文件 fs_watcher.yaml，填入以下内容：

watcher_type: qfilesystem
paths:
  - /home/user/project/src
  - /home/user/project/config
events:
  - directoryChanged
  - fileChanged
debounce_ms: 300

3. 在 QoderWake 的工作流编排器中，新建一个“FS 变更触发”类型的节点，将其 source 字段指向刚才定义的路径组。

4. 将该触发节点的输出连接到“执行 Shell 构建脚本”技能上，脚本路径设为 ./scripts/build.sh，并为脚本赋予可执行权限。

二、通过系统 inotify+Webhook 桥接的 Linux 专用方案

这套方案绕过 Qt 依赖，直接调用 Linux 内核的 inotify 机制监听目录，由独立的守护进程将 inotify 事件转换为标准的 HTTP Webhook，推送给 QoderWake 内置的接收端点。适用于无 GUI、最小化镜像部署的场景，即使目录中包含上百万个文件也能稳定监听。操作步骤如下：

1. 在宿主机上安装 inotify-tools：Ubuntu/Debian 使用 sudo apt-get install inotify-tools，CentOS/RHEL 使用 sudo yum install inotify-tools。

2. 创建监听脚本 monitor_dir.sh，内容大致如下：

#!/bin/bash
DIR="/home/user/project"
while inotifywait -e create,delete,modify,move $DIR; do
  curl -X POST https://localhost:8080/v1/webhook/inotify-trigger \
    -H "Content-Type: application/json" \
    -d '{"event":"dir_modified","target":"'$DIR'","timestamp":'$(date +%s)'}'
done

3. 赋予执行权限并在后台运行：chmod +x monitor_dir.sh && nohup ./monitor_dir.sh > /dev/null 2>&1 &

4. 在 QoderWake 控制台的“触发管理”中创建一个“API 回调触发”，Webhook URL 填写 https://localhost:8080/v1/webhook/inotify-trigger，启用 JSON Schema 校验，要求字段包含 event 和 target。

5. 将该触发器绑定到预置的“Clean-Build-Deploy”工作流，开启自动执行模式。

三、启用 QoderWake 内置防腐治理规则联动监控

这条路线无需新增监听组件，而是复用 QoderWake 已激活的防腐治理（Anti-Rot Governance）模块。该模块将目录时间戳、文件哈希快照纳入长期记忆比对周期，一旦检测到监控路径的 mtime 或 SHA256 摘要发生变化，便自动触发构建。特别适合高安全合规场景——所有操作在权限沙盒内完成，无需开放网络或系统调用。操作步骤：

1. 进入 config/governance/ 目录，编辑 custom_rules.yaml，在 memory 节点下追加 watch_paths 区块：

watch_paths:
  - path: "/home/user/project/package.json"
    type: "file_hash"
    hash_algo: "sha256"
  - path: "/home/user/project/src"
    type: "dir_mtime"
    recursive: true

2. 确认 config/core.yaml 中 governance_rule_path 指向该 custom_rules.yaml 文件。

3. 执行 qoderwakectl reload-governance 热加载规则。

4. 在 QoderWake“技能市场”中启用“Governance-Driven Build Trigger”技能，将触发阈值设为“任意 watch_path 变更即触发”，并绑定目标构建流水线。

5. 手动修改 package.json 内容并保存，验证 QoderWake 日志中是否出现 [GOVERNANCE] Path /home/user/project/package.json hash mismatch → triggering build 这一条目。若出现，则说明配置已生效。