Руководство по DeepSeek Superagent: наблюдайте за CI и авторизуйте фикс

Что такое DeepSeek Superagent?

DeepSeek Superagent наблюдает за одним репозиторием GitHub через DeepSeek Harness. Правила команды решают, заслуживает ли событие внимания; принятая работа уходит в отдельную сессию. В этом руководстве рассматривается опубликованный прототип, а не идеи на уровне дизайна.

Harness даёт среду выполнения; Superagent добавляет мониторинг событий и авторизацию. Наш обзор agent harness рассказывает об инструментах, памяти и управлении.

Как работает DeepSeek Superagent?

Новое событие GitHub может пройти четыре этапа. Эти этапы отделяют решение от изменения кода:

• Источник и триггер: опрос GitHub превращает каждое событие в триггер на Issue, pull request или main.

• Допуск: шлюз помечает его как явный запрос, предполагаемого кандидата или ничего.

• Оценка и решение: выведенный из CI сигнал сравнивается с правилами. Явный запрос направляется в решение «принять» с причиной explicitRouted.

• Тикет и исполнитель: принятая работа получает авторизацию, рабочую сессию и директорию.

Поздний комментарий в собственном треде тикета уходит его исполнителю без новой оценки. На схеме показаны три пути GitHub: CI основной ветки, явный запрос и его ревью. В ветке CI режим наблюдения и авто-режим у совпадающего правила находятся на разных концах.

CI оценивается. Запросы запускают работу. Изображение автора.

Чем отличается режим наблюдения от авто-режима?

Режим принятия применяется только к работе, которую Superagent вывел из события. Выберите один из трёх вариантов:

• off отбрасывает предполагаемых кандидатов.

• observe оценивает их, но фиксирует положительный результат как «принял бы».

• auto стартует работу после положительной оценки.

Запрос от допущенного лица работает в любом режиме и создаёт свой тикет. Для этого руководства держите auto выключенным.

Постройте рабочий процесс исправления CI в режиме наблюдения

Конвейер использует pytest и два задания GitHub Actions, чтобы превращать события в ежедневную выручку. Superagent вставляет решение перед началом работы. Наш туториал по Claude Code Routines рассматривает иной событийный рабочий процесс.

Найдите баг с повтором события в ежедневной выручке

Баг дважды учитывает повторно доставленный платёж. В каждой строке есть event_id, order_id, метки времени и сумма. Один заказ может иметь несколько корректных платежей.

Поэтому дедупликация по order_id может пройти тест на повтор, но удалить реальные платежи; правильный ключ — event_id. Посчитайте ожидаемые суммы с помощью модуля Python csv до авторизации агента, чтобы вывод агента не стал ответом для проверки.

Определите успешное исправление CI

Успех зависит от того, что делает рабочий процесс, а не только от слов агента. Задайте условия до изменения репозитория:

• Игнорировать сбой, касающийся только документации.

• Совпасть с revenue-integrity, не начиная работу.

• Открывать pull request только после явного запроса.

• Сохранить утверждения и пройти заранее подготовленный закрытый набор тестов.

Подготовьте закрытый набор до того, как Superagent получит доступ. Это держит ожидаемое поведение вне входных данных разработки исполнителя.

Предпосылки и изоляция DeepSeek Superagent

Вам нужен ключ API DeepSeek, два аккаунта GitHub и одноразовая среда Linux. Основы Harness смотрите в нашем базовом руководстве по настройке.

ПО и аккаунты, которые нужны

Зафиксируйте версии ПО, чтобы обновление не изменило рабочий процесс. Последняя колонка фиксирует конфигурацию, использованную для результатов далее в статье:

Агенту нужен собственный пользователь GitHub с правами записи, поскольку Superagent читает уведомления этого аккаунта. В список допущенных добавляйте только тех человеческих мейнтейнеров, кто может авторизовать работу.

Изолируйте агента от личных файлов

Оба предустановленных варианта дают пользователю ОС полный доступ, а обёртка gh не изолирует процесс. Используйте новую дистрибуцию WSL с отключёнными automount и interop:

Если у вас уже есть одноразовая виртуальная машина Linux, пропустите блок WSL и используйте её. Держите посторонние учётные данные и файлы вдали от неё.

# /etc/wsl.conf inside the disposable distribution
[automount]
enabled = false
mountFsTab = false
[interop]
enabled = false
appendWindowsPath = false
[user]
default = superagentРаботает на

Выделенный пользователь superagent должен хранить только ключ DeepSeek и токен агента. Это снижает риск случайного доступа, но не является границей безопасности; модель безопасности WSL от Microsoft рекомендует отдельно управляемую виртуальную машину вне WSL для недоверенного кода.

В GitHub защитите main обязательным pull request, минимум одним независимым одобрением и обоими CI-проверками. Дайте агенту права записи без админского обхода. Ничто из этого не предотвращает внедрение подсказок через текст Issue.

Шаг 1: Постройте конвейер выручки на Python и базовый CI

Опубликованный репозиторий для руководства сейчас содержит слитое исправление в main, поэтому не используйте его текущую ветку как начальное состояние. Используйте эти коммиты, чтобы разделить три стадии:

Приведённые ниже конвейер и тесты упрощены относительно зелёной базы (a6d2036), а не взяты из текущего main. Создайте одноразовый репозиторий из того коммита, прежде чем следовать шагам CI:

git clone https://github.com/KhalidAbdelaty/superagent-revenue-lab.git revenue-lab
cd revenue-lab
git switch -C main a6d2036
git remote remove origin

export EXPERIMENT_REPO="YOUR_LOGIN/superagent-revenue-lab"
gh repo create "$EXPERIMENT_REPO" --private --source=. --remote=origin --pushРаботает на

Используйте этот новый репозиторий для контролируемых сбоев и веток агента. Опубликованный репозиторий оставьте без изменений; его коммиты инцидента и решения служат для сравнения.

"""Daily revenue report built from payment events."""
import pandas as pd


def load_events(path):
    """Read payment events; amounts are integer cents."""
    return pd.read_csv(path, parse_dates=["occurred_at", "received_at"])


def daily_revenue(events):
    """Return one row per UTC day with total revenue in cents."""
    days = events["occurred_at"].dt.strftime("%Y-%m-%d")
    report = (
        events.assign(day=days)
        .groupby("day", as_index=False)["amount_cents"]
        .sum()
        .rename(columns={"amount_cents": "revenue_cents"})
    )
    return reportРаботает на

Базовый датасет охватывает два дня и включает несколько реальных платежей по одному заказу. Pytest проверяет известные суммы и этот случай с общим заказом, а повторы пока ничто не тестирует:

import pandas as pd


def test_daily_totals_match_known_values():
    report = daily_revenue(load_events(DATA))
    assert report["revenue_cents"].tolist() == [20398, 27550]


def test_events_on_the_same_order_are_all_counted():
    t = pd.Timestamp(0, unit="s", tz="UTC")
    events = pd.DataFrame({
        "event_id": ["evt_a", "evt_b"],
        "order_id": ["ord_1", "ord_1"],
        "occurred_at": [t, t],
        "received_at": [t, t + pd.Timedelta(seconds=1)],
        "amount_cents": [1000, 250],
    })
    assert daily_revenue(events)["revenue_cents"].tolist() == [1250]Работает на

Назовите каждое задание в честь проверяемого поведения. Тогда те же имена появятся в GitHub и в тексте триггера Superagent:

name: ci
on:
  push:
    branches: [main]
  pull_request:

jobs:
  revenue-integrity:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -r requirements.txt   # pandas==2.3.3, pytest==8.4.2
      - run: pytest -v

  docs-check:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python scripts/check_docs.py      # fails if README links a missing fileРаботает на

Если голый pytest не может импортировать revenue, добавьте pytest.ini с pythonpath = .. Убедитесь, что оба задания проходят в main до установки Superagent.

Опубликованный каталог experiment/holdout документирует исходный прогон, но виден в публичном клоне. Для нового эксперимента создайте свежий набор вне любого рабочего каталога и файловой системы, доступных исполнителю.

Просчитайте хэш этого набора до отправки запроса на исправление. Покройте такие случаи:

• Повторные доставки одного события.
• Разные события с одинаковым ID заказа.
• Входной DataFrame, который нельзя менять.
• Ожидаемые столбцы и порядок сортировки вывода.

Держите этот набор скрытым до ревью. Шаг 6 запускает его из отдельной человеческой среды после завершения работы исполнителя.

Следующая схема разделяет входные данные разработки исполнителя и итоговую проверку мейнтейнера.

Закрытые данные остаются вне доступа исполнителя. Изображение автора.

Шаг 2: Установите DeepSeek Superagent и подключите GitHub

Установите бандл в выделенный профиль Harness, отдельный от профиля для повседневной работы. Загрузите токен учётной записи агента в AGENT_GH_TOKEN, не записывая его в репозиторий. Затем выполните эти команды от имени пользователя superagent:

npm install -g @deepseek-ai/[email protected] [email protected]

git clone https://github.com/deepseek-ai/dsh-superagent-prototype.git ~/dsh-superagent
cd ~/dsh-superagent
git checkout --detach 8c32a9dc5d72c033816c6a8110b37f40cf94fba4
pnpm install && pnpm build

# A gh wrapper that only ever sees the agent account
mkdir -p "$HOME/.local/bin"
export PATH="$HOME/.local/bin:$PATH"
cat > ~/.local/bin/gh-agent <<'W'
#!/bin/sh
GH_CONFIG_DIR="$HOME/.config/gh-agent" exec gh "$@"
W
chmod +x ~/.local/bin/gh-agent
printf '%s' "$AGENT_GH_TOKEN" | gh-agent auth login --hostname github.com --with-token
gh-agent api user --jq .login            # your dedicated agent account

# Dedicated profile, then the bundle
dsh superagent --from-default-profile web --dump-config > /dev/null
dsh plugin --profile superagent add "link:$PWD"Работает на

Примечание: запуски в этом руководстве использовали коммит 6337fc8, который DeepSeek позднее «сжала» в 8c32a9d.

Используйте пример профиля в клонированном репозитории, чтобы задать директорию состояния и привязать панель к 127.0.0.1:3082. Затем запустите сервис в tmux:

scripts/dsh-superagent start
scripts/dsh-superagent statusРаботает на

Этот профиль отделяет перезапуски сервиса от личных сессий Harness. Он также держит PATH и Git-настройки плагина вне обычного профиля.

status может показывать setup pending или repositoryUnset, пока вы не сохраните источник GitHub на шаге 3. На этом этапе проверьте лишь, что рантайм отвечает и панель Superagent открывается; не ожидайте источника или базовой линии CI.

Откройте Settings → Models в выделенном профиле и выберите deepseek-flash. В Superagent → Settings → Eval и Execution убедитесь, что обе роли наследуют модель профиля или явно указано deepseek-flash.

Шаг 3: Настройте мониторинг GitHub Actions в режиме наблюдения

Оставьте наблюдение за CI основной ветки выключенным, пока сохраняете настройки источника, политики, правила и исполнителя. Включите его только после того, как новый репозиторий станет зелёным в main, чтобы первый снимок зафиксировал чистую базу.

Настройте источник GitHub

В Settings → Sources укажите репозиторий EXPERIMENT_REPO, направьте поле CLI на выделенную обёртку gh-agent и оставьте наблюдение за CI основной ветки выключенным. Сохраните источник и дождитесь окончания перезапуска перед изменением политики.

Настройте политику допуска CI

У результата CI нет отправителя. У его строки допуска одна ячейка, по умолчанию ignore. Если оставить так, оценка никогда не увидит CI.

Определите узкое правило revenue-integrity

Замените примеры одним правилом, названным в честь проверки. Скажите оценщику не гадать о причинах:

{
  "rules": [{
    "id": "revenue-integrity",
    "name": "Revenue integrity CI failures",
    "enabled": true,
    "instruction": "A default-branch CI result in which the check named revenue-integrity newly fails. That check executes the pytest suite guarding the daily revenue totals. Judge only from the check names and results you can read for that commit; do not guess a root cause. Failures limited to other checks, such as docs-check (README links), do not match. A recovery where every check passes does not match. Work, if accepted: investigate the failing revenue-integrity tests, fix the pipeline without weakening or deleting any assertion, add a regression test, and open a pull request for human review. Never merge."
  }],
  "sources": {"github": {
    "allowed": [{"id": "<human-login>"}],
    "bots": [],
    "admission": {"ci": {"unlistedUnaddressed": "inferred"}}
  }}
}Работает на

Добавьте команду подготовки, которая создаёт Git worktree для каждого тикета. Тогда каждый исполнитель начнёт с рабочего клона репозитория:

C=/home/superagent/src/superagent-revenue-lab
git -C $C fetch --no-tags "https://github.com/$DSH_SUPERAGENT_GITHUB_REPOSITORY.git" \
  "${DSH_SUPERAGENT_GITHUB_PR_HEAD:-HEAD}:refs/dsh-superagent/$DSH_SUPERAGENT_TICKET" &&
git -C $C worktree add -b "agent/$DSH_SUPERAGENT_NAME" "$DSH_SUPERAGENT_DIR" "refs/dsh-superagent/$DSH_SUPERAGENT_TICKET"Работает на

Superagent подставляет эти переменные для каждого тикета. Проверьте, что в результате в директории оказался ожидаемый клон, прежде чем авторизовать работу.

Необязательный вспомогательный скрипт конфигурации записывает те же блоки источника, политики, оценки и исполнителя. Он держит наблюдение CI выключенным на первом проходе; всегда явно указывайте репозиторий эксперимента и допущенного отправителя запроса:

export REPO="$EXPERIMENT_REPO"
export ALLOWED="YOUR_GITHUB_LOGIN"
bash /path/to/configure.sh allРаботает на

Держите проактивное выполнение выключенным

Оставьте режим оценки observe с моделью по умолчанию профиля. После каждого события проверяйте вкладку Eval на предмет решения и вкладку Execution — на наличие тикета.

Включите наблюдение CI и запишите базу

После того как оба задания GitHub Actions пройдут в main, включите наблюдение CI основной ветки. Со вспомогательным скриптом используйте его второй проход:

OBSERVE_CI=true bash /path/to/configure.sh source
bash /path/to/configure.sh showРаботает на

Первое чтение записывает состояние, не создавая работу. Проверьте все четыре условия:

• В настройках нет ожидающих требований.

• Источник GitHub сообщает ready.

• Источник записывает чистую базовую линию CI.

• Вкладки Trigger и Execution не показывают базовый триггер или тикет.

Если одна из проверок не проходит, остановитесь до создания сбоя документации. Скриншоты источника и оценки показывают итоговую конфигурацию.

Карточка источника GitHub с наблюдением CI. Изображение автора.

Настройки оценки: одно правило, режим наблюдения. Изображение автора.

Шаг 4: Протестируйте несвязанный сбой GitHub Actions

Используйте битую ссылку в README как несвязанный сбой. Поскольку защищённая ветка отклоняет неуспешную проверку, используйте админский обход только в этом одноразовом репозитории; никогда не давайте такой обход агенту.

sed -i 's|^- Tests: .*|&\n- Data dictionary: [docs/data-dictionary.md](docs/data-dictionary.md)|' README.md
git commit -am "docs: link the data dictionary from the README" && git pushРаботает на

Когда GitHub Actions завершились, docs-check упал, а revenue-integrity прошёл. Это соответствовало заданному мной правилу: Superagent проигнорировал кандидата, потому что правило выручки не совпало.

Решение использовало ignoredFromCard — шорткат для кандидатов, не затрагивающих активное правило. Так что эта проверка покрывает маршрутизацию, а не само правило.

Откатите изменение README и дождитесь прохождения обоих заданий. Superagent должен проигнорировать восстановление и остаться в простое.

Шаг 5: Вызовите сбой CI для целостности выручки

Тем же «человеческим» путём добавьте данные инцидента из репозитория руководства. Эта сводка показывает повторную доставку и отдельные платежи по одному заказу без колонок времени:

event_id,order_id,amount_cents,delivery
evt_1009,ord_507,5000,first
evt_1010,ord_508,6400,first
evt_1011,ord_508,1600,first
evt_1009,ord_507,5000,replay
evt_1012,ord_509,2100,firstРаботает на

Репозиторий хранит полные колонки меток времени; здесь они опущены, поскольку не определяют идентичность события. Ранее подготовленный независимый расчёт ожидает 15 100 центов, так что задайте это значение в тесте и добавьте test_replayed_event_is_counted_once().

E       actual daily total: 20100
E       expected daily total: 15100
E       replay total: 8000 != 4000
FAILED tests/test_revenue.py::test_daily_totals_match_known_values
FAILED tests/test_revenue.py::test_replayed_event_is_counted_once
2 failed, 1 passedРаботает на

Лишние 5 000 центов — это один платёж, посчитанный дважды. Замена 15100 на 20100 или удаление теста на повтор тоже окрасили бы CI в зелёный, но это не исправление.

Неудачный workflow GitHub Actions показывает, что падает только revenue-integrity. Его триггер пришёл примерно через один интервал опроса.

Оценка пометила кандидата «принял бы», а вкладка Execution осталась пустой. Оценщик видел имена и выводы проверок, а не лог pytest, так что он знал, какой «сторож» упал, но не почему.

Режим наблюдения лишь логирует «принял бы». Изображение автора.

Шаг 6: Авторизуйте исправление и проверьте pull request

Путь явного запроса, описанный выше, теперь авторизует выполнение. Уведомления GitHub могут приходить с задержкой.

Обработайте пропущенное упоминание в GitHub Issue

На Superagent 6337fc8 источник GitHub перекрывает опросы на 5 секунд и читает уведомлённый тред из более позднего курсора. Уведомления об упоминании приходили через 21–23 секунды, так что опрос мог проскочить мимо сообщения.

Этим объясняется, почему новое тело Issue и некоторые комментарии не становились триггерами. Сообщение сообщества описывает тот же сбойный сценарий.

Авторизуйте исправление комментарием в GitHub

Отправьте запрос снова как новый комментарий и убедитесь, что появился его триггер. Superagent должен принять его как явный запрос и запустить исполнителя.

Упоминание в комментарии создаёт авторизованный тикет. Изображение автора.

Проверьте исправление дедупликации событий агентом

В результирующем pull request исправление было привязано к event_id. Ревьюйте diff, не полагаясь на описание:

 def daily_revenue(events):
     """Return one row per UTC day with total revenue in cents."""
+    # The payment webhook may deliver the same event more than once, with a
+    # different received_at but the same event_id. One event_id is one payment
+    # event, so keep only its first delivery before aggregating.
+    events = events.drop_duplicates(subset="event_id", keep="first")
     days = events["occurred_at"].dt.strftime("%Y-%m-%d")Работает на

Он добавил тест на повтор и ничего не удалил. Первая команда тестов упала из‑за отсутствующих зависимостей. После создания виртуального окружения исполнителем видимый набор тестов прошёл.

Протестируйте платежи с общим заказом

Запросите изменения без упоминания агента: докажите, что два платежа по одному заказу, идентичные кроме event_id, оба считаются, а повтор одного учитывается один раз. Ревью должно прийти к тому же тикету без новой оценки.

Исполнитель ответил коммитом, который лишь добавил тест и не трогал конвейер. До одобрения проверьте точный head SHA и заново прогоните независимый набор против этой ревизии.

Обратная связь по ревью продолжает тот же тикет. Изображение автора.

Проверьте исправление на независимых данных

Запустите закрытый набор из отдельной человеческой среды против точной головы pull request. На a43c541 оба набора прошли 5 из 5 тестов без удаления утверждений; 62bac08 сохранил то же дерево.

Тесты, написанные исключительно агентом, покрывают только те случаи, которые агент сам выбрал.

Шаг 7: Слейте фикс и замерьте восстановление CI

После слияния проверьте, что main вернулся в зелёное состояние и восстановление не запустило новую работу. Затем изучите трассировку событий, затраченное время и стоимость провайдера.

Слейте фикс и подтвердите восстановление CI

После ручного одобрения и слияния обе проверки основной ветки прошли. Superagent проигнорировал восстановление, не начал новой работы и закрыл существующий тикет с исходом merged.

Оцените приём событий и решения

Проследите каждое событие от приёма до исхода, как описывает наше руководство по оценке ИИ-агентов. В трёх повторах события, дошедшие до оценки, шли ожидаемым путём; пропуски происходили на этапе приёма, а не в решении модели.

Измерьте корректность, время и стоимость исправления

Один и тот же сценарий запускался в трёх свежих репозиториях и дистрибутивах WSL с Superagent 6337fc8, Harness 0.2.1-rc.3, deepseek-flash и одной политикой. Стоимости используют пониженный внепиковый тариф DeepSeek; это воспроизведения, а не бенчмарк.

Все три исправления использовали event_id; каждый тест из закрытого набора прошёл. Больше различий было в приёме событий: упоминание в теле Issue пропускалось каждый раз, а в третьей репродукции также были пропущены два комментария до прихода одного.

Во второй репродукции коммиты были переписаны, и одобрение пришло до повторного прогона закрытого набора. Поздняя проверка прошла, но безопаснее соблюдать порядок: head SHA, закрытый набор, затем одобрение.

Ограничения и устранение неполадок DeepSeek Superagent

Несколько сбоев здесь выглядят как отсутствие реакции, поэтому начните с поиска места, где событие остановилось. Раздражает то, что пропущенное уведомление и корректное игнорирование могут выглядеть одинаково.

Сбои CI, не создающие триггер

Superagent отслеживает изменения в множестве падающих проверок, поэтому базовое чтение, проверка, которая продолжает падать, и проверки, всё ещё выполняющиеся, ничего не создают. Триггер без решения обычно указывает на ячейку допуска CI, а не на модель.

Запросы GitHub, которые не доходят

Запросы могут провалиться, если отправитель не допущен, источник выключен, обработка на паузе или GitHub уведомляет с опозданием. Если эти проверки пройдены, оставьте новый комментарий; редактирование тела Issue события не создаёт.

Пределы автономного исправления CI

Прототип не предоставляет границы безопасности. Исполнители имеют полный доступ пользователя ОС, а правила раскрытия — это текст подсказок. Изолируйте аккаунт агента и ограничьте его одноразовым репозиторием.

Прежде чем переключаться на auto, соберите недели наблюдаемых решений, посчитайте неверные «принятия» и неверные «игноры», а исполнителя перенесите из WSL в отдельную виртуальную машину.

Заключение

Начальный контраст подтвердился: два красных состояния CI не привели к одному и тому же действию. Superagent проигнорировал docs-check и пометил revenue-integrity как «принял бы», а режим наблюдения держал код нетронутым до запроса человека на исправление.

Патч event_id был прямолинейным. Приём уведомлений был менее надёжен: упоминание в теле Issue так и не дошло до оценки, поэтому корректное правило не могло помочь.

Я бы не обобщал этот результат на автономное исправление CI. Репозиторий был маленьким, правило — узким, а слияние — под контролем человека. В других местах начните с зелёного состояния, изучайте решения, авторизуйте явно, держите закрытые данные отдельно и сливайте после независимых проверок.

Мой следующий шаг — починить путь уведомлений GitHub и повторить рабочий процесс с большим числом типов сбоев. Пока таких данных нет, я бы держал режим auto выключенным.