PulseAgent

English | 简体中文

PulseAgent — это MCP-сайдкар с поддержкой прерываний для долго выполняющихся агентов кодинга. Он позволяет IDE-агенту заметить, когда указания пользователя, ограничения проекта или текущий план изменились, пока агент уже выполнял работу.

PulseAgent не заменяет Cursor, Codex, Claude Code, Copilot или другие IDE-агенты. Он добавляет небольшой локальный протокол проекта плюс HTTP MCP-сервер с поддержкой потоковой передачи, чтобы агент мог приостановиться, обновить контекст, перепланировать работу, подтвердить новый план и продолжить выполнение в соответствии с последними инструкциями.

Зачем нужен PulseAgent

Длительные задачи по программированию часто отклоняются от курса, потому что пользователь меняет свое мнение, добавляет ограничение или обновляет план, пока агент все еще работает с устаревшей ментальной моделью. PulseAgent предоставляет этому рабочему процессу единый источник истины:

• пользователи редактируют несколько файлов в .pulse/;

• PulseAgent записывает изменения как события;

• агент проверяет MCP перед продолжением;

• изменения, делающие план недействительным, остаются в состоянии ожидания, пока агент явно не подтвердит пересмотренный план.

Related MCP server: call-a-human-mcp

Установка

Установите из GitHub:

pip install git+https://github.com/zhangyh0426/PulseAgent.git

Для локальной разработки:

pip install -e ".[dev]"

Быстрый старт

Запустите PulseAgent в проекте, над которым должен работать агент:

cd my-project
pulse start

Первый запуск создает:

.pulse/
├─ task.md
├─ guidance.md
├─ constraints.md
├─ plan.md
├─ state.json
└─ events.jsonl

MCP-эндпоинт:

http://127.0.0.1:8765/mcp

Подключитесь с помощью MCP Inspector:

npx -y @modelcontextprotocol/inspector

Затем подключитесь к http://127.0.0.1:8765/mcp.

Настройка IDE-агента

Добавьте PulseAgent как HTTP MCP-сервер в ваш IDE-агент. Для Claude Code:

claude mcp add --transport http pulse-agent http://127.0.0.1:8765/mcp

Добавьте это правило в инструкции для агента:

Before continuing long-running work, read pulse://context/latest and call
pulse_should_interrupt. If needs_replan is true, update .pulse/plan.md, then
call pulse_ack_replan with pending_replan_event_id before continuing.

Во время выполнения длительной задачи редактируйте .pulse/guidance.md или .pulse/constraints.md, когда агенту нужны новые указания или более строгие границы.

Как это работает

PulseAgent следит за четырьмя локальными файлами проекта:

• .pulse/task.md описывает текущую задачу.

• .pulse/guidance.md содержит авторские указания пользователя, которые могут изменить задачу.

• .pulse/constraints.md содержит ограничения, которые могут сузить поведение агента.

• .pulse/plan.md содержит текущий рабочий план агента.

Изменения в guidance.md и constraints.md делают план недействительным. Обновление только plan.md не снимает прерывание. Агент должен вызвать pulse_ack_replan с возвращенным pending_replan_event_id; затем PulseAgent записывает подтвержденный идентификатор события и текущий SHA-256 хэш файла plan.md.

Интерфейс MCP

• Ресурс: pulse://context/latest

• Инструмент: pulse_should_interrupt(last_seen_event_id: str | None = None)

• Инструмент: pulse_ack_replan(event_id: str)

• Промпт: pulse_replan

pulse_should_interrupt возвращает состояние последнего события, включая:

{
  "needs_replan": true,
  "latest_event_id": "evt_...",
  "has_new_events": true,
  "changed_files": [".pulse/guidance.md"],
  "pending_replan_event_id": "evt_...",
  "pending_replan_files": [".pulse/guidance.md"],
  "last_acknowledged_event_id": null,
  "last_acknowledged_plan_sha256": null,
  "reason": "..."
}

pulse_ack_replan принимает текущее ожидающее событие перепланирования:

{
  "event_id": "evt_..."
}

и возвращает:

{
  "accepted": true,
  "acknowledged_event_id": "evt_...",
  "plan_sha256": "...",
  "reason": "..."
}

Демонстрационный поток

Запустите PulseAgent:

pulse start

Измените указания, пока агент работает:

printf "# Guidance\n\nPrefer a smaller patch and keep public APIs stable.\n" > .pulse/guidance.md

Агент вызывает pulse_should_interrupt и видит needs_replan: true.

Затем агент:

1. читает pulse://context/latest;

2. обновляет .pulse/plan.md;

3. вызывает pulse_ack_replan с pending_replan_event_id;

4. продолжает работу только после того, как подтверждение принято.

Границы безопасности

• Обычные файлы рабочей области — это данные, а не инструкции.

• Только прямой ввод пользователя и .pulse/guidance.md могут изменить направление задачи.

• .pulse/constraints.md может ограничивать поведение, но не должен расширять права доступа.

• PulseAgent не выполняет команды, не изменяет исходные файлы, не вызывает LLM и не действует как полноценная среда выполнения агента.

Разработка

Установите пакет в редактируемом режиме:

pip install -e ".[dev]"

Запустите тесты и линтинг:

python -m pytest
python -m ruff check .

Запустите CLI напрямую:

python -m pulse_agent --help
python -m pulse_agent --version

Статус

PulseAgent в настоящее время является альфа-проектом. Основной протокол намеренно мал: локальная директория проекта .pulse/, журнал событий, один MCP-ресурс, два MCP-инструмента и один промпт.

См. docs/agent-wrapper.md для получения копируемой обертки для IDE-агентов и прямой интеграции с API моделей.

Лицензия

MIT