mcp-watcher

    Download zip
    Author
    Version
    0.2.0
    License
    Apache-2.0
    Last updated
    3 hours ago
    Downloads
    8

    #mcp-watcher · AI 工作区自治运行时

    一句话定位:让 AI 工作区自己照顾自己,而不占用你和 Agent 的每一轮对话。

    mcp-watcher 不是一个"通用的文件监控触发器"。它是面向 AI 工作区的自治运行时(Autonomous Runtime):你(或 AI 自己)用一份声明式规则描述"当什么发生,做什么",它就在后台常驻、沉默地执行,并在规则改变时不停机热更新。


    #为什么不是"通用文件触发器"

    通用文件触发器只回答"文件变了 → 跑命令"。而 AI 工作区的真实诉求是产物的生命周期治理——临时文件何时清理、敏感产物如何加密、过期文件如何进回收站、Agent 跑出的中间产物如何被安全回收。mcp-watcher 把"事件"当作触发器,把"动作"当作生命周期语义而非裸命令。


    #四大产品支柱

    #1. 后台常驻、沉默自治(不占用 Agent 的一轮对话)

    • 作为独立进程后台运行,启动后与你的对话 / Agent 完全解耦。
    • Agent 不必为了"等一个文件生成"而空转一轮对话;规则在守护进程里自行完成。
    • 通过 status 可观测、stop 可终止,但默认不打扰。

    #2. 声明式规则系统(非程序员能写、AI 能自己写)

    • 规则是 JSON DSL:事件 + glob + 条件 + 动作,可读、可审查、可版本化(见 workbuddy/plan/config-schema.md)。
    • 非程序员照例能写;AI 在运行期也能自己生成并热加载规则(例如"把 >10MB 的日志压缩归档")。
    • 不是脚本、不是 cron 行——是一份机器与人类可共同维护的"工作区宪法"。

    #3. 热重载(规则变了不停机)

    • 规则文件变更后,守护进程在不重启、不丢状态的前提下加载新规则表(设计见 workbuddy/plan/design-spec.md 热重载章节)。
    • 新规则立即生效、旧规则平滑退出,保证自治不中断。

    #4. 产物生命周期语义(不是泛泛的"跑命令")

    动作(action)是有语义的,而非裸 shell。当前实现状态(诚实标注):

    能力状态说明
    TTL✅ 已落地产物注册追踪表(可持久化);到期判定 + product.expired 生命周期事件 + 追踪表移除
    trash(回收站)✅ native 已做实 / 🚧 其他目标降级native 用 moonbitlang/async/fs 的 mkdir/rename 真实移入 <watch_dir>/.trash/<name>.<ts>(零新增 C FFI);js/wasm 无此 API,诚实返回"不支持"
    加密🚧 明确降级(不可做实)rx 的 Fernet 原语是 extern "js"(node:crypto),native/wasm 加密返回空串;本项返回可诊断 Err,绝不写空密文破坏产物,待 rx 补 native crypto FFI
    command✅ 已落地argv 数组执行,ExecPolicy 显式白名单(规则不会自动放行命令);拒绝事件现已落结果记录、可 e2e 对拍
    mcp_tool_call / webhook / internal🚧 扩展位 EP-01返回可诊断错误

    设计取舍详见 workbuddy/plan/p3-feasibility.md(历史定位)。trash 后续发现 moonbitlang/async@0.22.9(rx 0.4.4 传递依赖)在 native 提供 mkdir/rename C stub, 实测可做实,故由"规划中"升级为"native 已做实";加密因底层依赖 node:crypto 无法在 native 做实,维持诚实降级。两条路径均以实测为准,不把 no-op 包装成已实现。

    #双门禁(schema v1.1 · PLAN-gates.md)

    支柱 4 的强化:动作准入(前)+ 产物有效性(后)。全部纯函数判定、零新依赖、 不引入重试循环;v1.0 规则(无这两个字段)行为逐位不变。

    门禁位置判定失败处置
    guard(守卫门)动作执行前单命令必须 exit 0(argv 与 command 同走白名单校验,绝不走 shell)on_fail=skip:记 guard_fail 事件跳过本次动作(规则存活);on_fail=stop:记事件并停止本规则后续处理
    acceptance(验收门)动作执行后expect_exit / stdout_contains(AND) / stdout_not_contains / stderr_not_contains / artifact_glob(相对 watch_dir 至少命中 1 文件)accepted=false(保留真实 exit 与输出原文),触发 product.invalid 进入既有 TTL/trash 回收流,不做自动重试(重试留给上层)

    红线:guard 不做组合逻辑(需要 AND/OR 的守卫用条件层组合),防止长成规则里 套规则的策略引擎。字段契约见 workbuddy/plan/config-schema.md §5.1 / §5.2。


    #自治闭环

    声明式规则 (.mcp-watch.json) │ ▼ ┌──────────────────┐ │ watch 后端 │ inotify / FSEvents / ReadDirectoryChangesW └────────┬─────────┘ ▼ ┌──────────────────┐ │ rule 两层匹配 │ 事件类型 + glob → exclude 优先 → 条件(AND) └────────┬─────────┘ ▼ ┌──────────────────┐ │ action 生命周期 │ TTL✅ / trash(native✅) / 加密🚧 / command✅ / mcp🚧 / webhook🚧 └──────────────────┘ │ ▼ 自治结果(落盘 / 回写 / 通知),全程无需 Agent 介入


    #架构(脚手架,详见 fist-mbt/plans/)

    包职责
    config规则 DSL 模型 + JSON 解析 + 累积式校验
    watch文件系统事件源(后端扩展点 EP-01)
    rule两层匹配算法(事件+glob、exclude 优先、条件 AND)
    action生命周期动作(TTL✅ / trash native✅·其他🚧 / 加密🚧 / command✅…)扩展点 EP-01
    ext扩展位注册表(EP-01~EP-12)
    croncron 表达式解析与下次触发计算(纯逻辑、可测)
    scheduler事件源 + cron 合并的主循环(待接入 rx EventBus)
    cmd/mainCLI 入口(start/stop/status/run/validate)

    实现期将复用兄弟项目 rx-mbt(响应式内核:EventBus / 真实时钟 / 原生监控 / 命令 Observable),详见 rx-mbt/PLAN-mcp-watcher-apis.md。


    #当前状态

    • ✅ 产品定位与四大支柱(本文)
    • ✅ 详细设计决议 workbuddy/plan/design-spec.md、配置契约 config-schema.md、rx 依赖决策 rx-mbt-dependency.md、复用与测试规划 reuse-and-test-plan.md
    • ✅ 项目架构脚手架已落地(本仓库包结构与核心类型):config/watch/rule/action/ext/cron/scheduler/cmd/main 八个包 + moon.mod;提案与执行汇报见 fist-mbt/plans/、fist-mbt/reports/
      • 门禁(当时的历史快照,现状见下):moon check --target native 0 error;moon test --target native 21/21 通过。当前门禁以 bash scripts/test_all.sh 为准(check 0 error + 三目标各 87 测试 + e2e 全绿)。
    • ✅ 已完成:接入 rx-mbt 0.4.4(R1~R4)、CLI 子命令、TTL 生命周期动作、双进程端到端测试(tests/harness/)
    • 🚧 规划中:热重载(P2)、加密(rx 无 native Fernet,见 workbuddy/plan/p3-feasibility.md)、mcp/webhook 扩展位
    • ✅ 已落地:trash 物理回收(native,async fs mkdir/rename;js/wasm 诚实降级)


    #快速开始(实现后)

    moon build --target native ./mcp-watch validate --config .mcp-watch.json # 校验规则 ./mcp-watch run --config .mcp-watch.json # 后台自治运行 ./mcp-watch status # 观测 ./mcp-watch stop # 终止


    #设计文档索引

    • workbuddy/plan/design-spec.md — 总体设计决议
    • workbuddy/plan/config-schema.md — 配置契约
    • workbuddy/plan/rx-mbt-dependency.md — 依赖决策
    • workbuddy/plan/reuse-and-test-plan.md — 复用与测试规划
    • rx-mbt/PLAN-mcp-watcher-apis.md — rx 增资计划
    • tests/harness/README.md — 双进程集成测试物料
    • fist-mbt/plans/2026-11-12-architecture-proposal.md — 本项目架构提案(FIST)