expergis (P Stryder)

Expergis

*来自拉丁语 expergīscī --醒来，从沉睡中被唤醒。自 前- （外）+ 佩格尔 （继续前进）。Velle是行动的意志，Expergis是觉醒的时刻。*

基于插件的事件观察器 克劳德代码.

Expergis检测系统事件，并在事件触发时唤醒代理。它是对感知的补充 Velle的意志——它们共同创建了一个完全由事件驱动的代理。Velle推（自提示），Expergis拉（事件检测）。

当事件触发时，Expergis会格式化一个提示并将其POST到Velle的HTTP sidecar中，后者会将其注入Claude Code会话。Velle的所有护栏（转弯限制、冷却、审计）都适用。

运作原理

Plugin detects event
  -> emit(Event)
  -> Dispatcher (dedup + rate limit + audit)
  -> POST http://127.0.0.1:7839/velle_prompt
  -> Velle injects prompt into Claude Code
  -> Agent wakes up with event context

Expergis与Claude Code一起作为MCP服务器运行。插件运行长期监视循环和调用 emit(Event) 当事情发生时。调度器执行重复数据消除、速率限制，并向Velle调度。

MCP工具

插件

文件查看器

通过轮询检测文件和目录更改。跟踪创建、修改和删除。

{
  "paths": ["/path/to/watch"],
  "patterns": ["*.py", "*.ts"],
  "events": ["modified", "created", "deleted"],
  "debounce_ms": 1000,
  "poll_interval_ms": 2000
}

调度器

使用以下命令按cron时间表触发事件 裙带关系者.

{
  "cron": "*/5 * * * *"
}

进程监视器

通过轮询检测进程启动和停止事件。仅限Windows（使用 tasklist).

{
  "process_names": ["notepad", "python"],
  "poll_interval_ms": 5000
}

安装

需要Python 3.10+和 紫外线.

git clone https://github.com/PStryder/expergis.git
cd expergis
uv sync

克劳德代码MCP配置

添加到您的Claude代码配置中(~/.claude.json 或项目 .mcp.json):

{
  "mcpServers": {
    "expergis": {
      "command": "/path/to/expergis/.venv/Scripts/python",
      "args": ["-m", "expergis.server"],
      "cwd": "/path/to/expergis"
    }
  }
}

或者使用CLI：

claude mcp add -s user expergis -- /path/to/expergis/.venv/Scripts/python -m expergis.server

配置

编辑 expergis.json 在项目根目录中：

{
  "velle_endpoint": "http://127.0.0.1:7839/velle_prompt",
  "rate_limit": {
    "min_interval_ms": 5000,
    "max_events_per_minute": 6,
    "burst_size": 2
  },
  "dedup_window_ms": 10000,
  "watchers": []
}

预配置的监视器

中定义的观察者 expergis.json 服务器启动时自动启动：

{
  "watchers": [
    {
      "watcher_id": "watch-src",
      "plugin_type": "file_watcher",
      "enabled": true,
      "prompt_template": "File changed: {event.summary}. Review and decide if action needed.",
      "config": {
        "paths": ["/my/project/src"],
        "patterns": ["*.py"],
        "events": ["modified", "created"]
      }
    }
  ]
}

速率限制

调度器使用令牌桶算法：

• burst_size --突发事件中分派的最大事件数（默认值：2）
• max_events_per_minute --持续速率（默认值：6/min）
• min_interval_ms --分派之间的最小间隔（默认值：5000ms）
• dedup_window_ms --抑制此窗口内的重复事件（默认值：10000ms）

速率受限事件存储在环形缓冲区中，可通过以下方式检索 expergis_check.

先决条件

Velle 必须在启用HTTP sidecar的情况下安装：

// velle.json
{
  "sidecar_enabled": true,
  "sidecar_port": 7839
}

编写自定义插件

实施 WatcherPlugin ABC：

from expergis.plugins.base import WatcherPlugin, Event, EmitFn

class MyPlugin(WatcherPlugin):
    async def setup(self) -> None:
        # Validate self.config, initialize state
        pass

    async def watch(self, emit: EmitFn) -> None:
        # Long-running loop
        while True:
            await asyncio.sleep(5)
            await emit(Event(
                plugin_type="my_plugin",
                watcher_id=self.watcher_id,
                event_type="something_happened",
                summary="Description of what happened",
            ))

    async def teardown(self) -> None:
        # Cleanup
        pass

在中注册 src/expergis/plugins/__init__.py 通过将其添加到 PLUGIN_REGISTRY.

许可证

Apache 2.0