DeepSeek Superagent-handledning: Övervaka CI och auktorisera en fix

Vad är DeepSeek Superagent?

DeepSeek Superagent bevakar ett GitHub-repo via DeepSeek Harness. Teamregler avgör om en händelse förtjänar arbete; accepterat arbete går till en separat session. Den här handledningen täcker den publicerade prototypen, inte idéer som bara finns på designstadiet.

Harness tillhandahåller runtime; Superagent lägger till händelsebevakning och auktorisering. Vår förklaring av agent-harness går igenom verktyg, minne och kontroll.

Hur fungerar DeepSeek Superagent?

En ny GitHub-händelse kan gå igenom fyra steg. Dessa steg håller beslutet och kodändringen åtskilda:

• Källa och Trigger: GitHub-pollning gör varje händelse till en Trigger på ett Issue, en pull request eller main.

• Insläpp: grinden märker den som en explicit begäran, en infererad kandidat eller ingenting.

• Utvärdering och beslut:  infererad CI bedöms mot reglerna. En explicit begäran dirigeras till ett accepterat beslut, orsak explicitRouted.

• Ticket och exekverare: accepterat arbete får sin auktorisering, arbetssession och katalog.

En senare kommentar i Ticketens egen tråd går till dess arbetare utan ny utvärdering. Diagrammet visar tre GitHub-vägar: CI för standardgrenen, en explicit begäran och den granskningen. Inuti CI-vägen ligger observera och auto-lämna en matchad regel i varsin ände.

CI bedöms. Begäranden startar arbete. Bild av författaren.

Vad är skillnaden mellan observera-läge och auto-läge?

Accepteringsläge gäller bara för arbete som Superagent härlett från en händelse. Välj en av tre inställningar:

• off kastar infererade kandidater.

• observe utvärderar dem men loggar ett positivt resultat som ”skulle acceptera”.

• auto startar arbete efter en positiv utvärdering.

En begäran från en behörig person fungerar i alla lägen och skapar en egen Ticket. Håll auto av för den här handledningen.

Bygg ett CI-reparationsflöde i observera-läge

Pipelinen använder pytest och två GitHub Actions-jobb för att omvandla händelser till dagliga intäkter. Superagent lägger in ett beslut innan arbetet börjar. Vår handledning om Claude Code Routines täcker ett annat händelsedrivet arbetsflöde.

Spåra uppspelningsbuggen i dagliga intäkter

Felet räknar en uppspelad betalning två gånger. Varje rad har ett event_id, order_id, tidsstämplar och ett belopp. En order kan innehålla flera giltiga betalningar.

Det är därför deduplicering på order_id kan klara ett uppspelningstest men ta bort riktiga betalningar; korrekt nyckel är event_id. Beräkna förväntade totalsummor med Pythons csv-modul innan du ger agenten tillstånd, så att agentens output inte blir facit.

Definiera en lyckad CI-reparation

Framgång beror på vad arbetsflödet gör, inte bara på vad agenten säger. Ställ in dessa villkor innan du ändrar repot:

• Ignorera ett fel som bara rör dokumentation.

• Matcha revenue-integrity utan att starta arbete.

• Öppna en pull request först efter en explicit begäran.

• Bevara assertioner och klara en förbyggd holdout-svit.

Förbered holdout-sviten innan Superagent får åtkomst. Detta håller det förväntade beteendet utanför arbetarens utvecklingsunderlag.

Förutsättningar och isolering för DeepSeek Superagent

Du behöver en DeepSeek API-nyckel, två GitHub-konton och en engångs Linux-miljö. För grunderna i Harness, se vår grundläggande installationsguide.

Programvara och konton du behöver

Frys programvaruversionerna så att en uppgradering inte kan ändra arbetsflödet. Den sista kolumnen antecknar uppsättningen som användes för resultaten senare i artikeln:

Agenten behöver sitt eget GitHub-användare med skrivåtkomst eftersom Superagent läser det kontots aviseringar. Lägg bara till de mänskliga underhållare som får auktorisera arbete i tillåten-listan.

Isolera agenten från personliga filer

Båda förvalen ger OS-användaren full åtkomst, och gh-omslaget isolerar inte processen. Använd en ny WSL-distribution med automount och interop avstängt:

Om du redan har en engångs Linux-virtuell maskin kan du hoppa över WSL-blocket och använda den istället. Håll orelaterade autentiseringsuppgifter och filer borta från den.

# /etc/wsl.conf inside the disposable distribution
[automount]
enabled = false
mountFsTab = false
[interop]
enabled = false
appendWindowsPath = false
[user]
default = superagentDrivs av

En dedikerad superagent-användare bör bara ha DeepSeek-nyckeln och agenttoken. Detta minskar oavsiktlig åtkomst men är ingen säkerhetsgräns; Microsofts säkerhetsmodell för WSL rekommenderar en separat hanterad virtuell maskin utanför WSL för otillförlitlig kod.

På GitHub, skydda main med ett krav på pull request, minst ett oberoende godkännande och båda CI-kontrollerna. Ge agenten skrivåtkomst utan administratörsgenväg. Inget av detta stoppar promptinjektion via Issue-text.

Steg 1: Bygg Python-pipelinen för intäkter och CI-baslinje

Det publicerade handlednings-repot har nu den sammanslagna reparationen på main, så använd inte dess nuvarande gren som startläge. Använd dessa commits för att separera de tre stegen:

Pipelinen och testerna nedan är förenklade från den gröna baslinjen (a6d2036), inte hämtade från nuvarande main. Skapa ett engångsrepo från den committen innan du följer CI-stegen:

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 --pushDrivs av

Använd detta nya repo för de kontrollerade felen och agentens grenar. Låt det publicerade repot vara oförändrat; dess tillbuds- och lösningscommits är referenser för jämförelse.

"""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 reportDrivs av

Baslinjedatatätheten spänner över två dagar och inkluderar flera riktiga betalningar för en order. Pytest kontrollerar kända totalsummor och det delade order-fallet, och inget testar uppspelningar än:

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]Drivs av

Namnge varje jobb efter beteendet det kontrollerar. Samma namn visas sedan i GitHub och i Superagents Trigger-text:

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 fileDrivs av

Om ren pytest inte kan importera revenue, lägg till en pytest.ini med pythonpath = .. Bekräfta att båda jobben passerar på main innan du installerar Superagent.

Den publicerade experiment/holdout-katalogen dokumenterar den ursprungliga körningen men är synlig i den offentliga klonen. Skapa för ett nytt experiment en färsk svit utanför varje utcheckning och filsystem som arbetaren kan läsa.

Hasha den sviten innan du skickar reparationsbegäran. Täck dessa fall:

• Upprepade leveranser av en händelse.
• Olika händelser med samma order-ID.
• En indata-DataFrame som måste förbli oförändrad.
• Förväntade utgångskolumner och sorteringsordning.

Håll denna svit dold fram till granskning. Steg 6 kör den från den separata mänskliga miljön efter att arbetaren är klar.

Följande diagram separerar arbetarens utvecklingsunderlag från underhållerens slutliga kontroll.

Holdout-data förblir utanför arbetaren. Bild av författaren.

Steg 2: Installera DeepSeek Superagent och koppla GitHub

Installera paketet i en dedikerad Harness-profil, separat från profilen som används för dagligt arbete. Ladda agentkontots token i AGENT_GH_TOKEN utan att skriva den till repot. Kör sedan dessa kommandon som användaren 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"Drivs av

Obs: Körningarna i denna handledning använde commit 6337fc8, som DeepSeek senare squashade till 8c32a9d.

Använd profilexemplet i det klonade repot för att sätta en tillståndskatalog och binda panelen till 127.0.0.1:3082. Starta sedan tjänsten i tmux:

scripts/dsh-superagent start
scripts/dsh-superagent statusDrivs av

Denna profil separerar omstarter av tjänsten från personliga Harness-sessioner. Den håller också insticksprogrammets PATH och Git-inställningar utanför den normala profilen.

status kan rapportera att installation pågår eller repositoryUnset tills du sparar GitHub-källan i steg 3. Bekräfta i detta skede bara att runtime svarar och att panelen Superagent öppnas; förvänta dig varken en källa eller en CI-baslinje ännu.

Öppna Settings → Models i den dedikerade profilen och välj deepseek-flash. I Superagent → Settings → Eval och Execution, bekräfta att båda rollerna ärver den profilmodellen eller namnge deepseek-flash uttryckligen.

Steg 3: Konfigurera övervakning av GitHub Actions i observera-läge

Lämna observation av CI för standardgrenen avstängd medan du sparar Källa, policy, regel- och exekveringsinställningar. Slå på den först efter att det nya repot har en grön main, så att första avläsningen loggar en ren baslinje.

Konfigurera GitHub-källan

I Settings → Sources, sätt repot till EXPERIMENT_REPO, peka CLI-fältet mot det dedikerade gh-agent-omslaget, och håll observation av CI för standardgrenen avstängd. Spara Källan och vänta på att eventuell omstart blir klar innan du ändrar policyn.

Konfigurera CI-insläppspolicyn

Ett CI-resultat har ingen avsändare. Dess insläppsruta har en cell, som standard ignore. Om du lämnar den inställningen oförändrad når CI aldrig utvärderingen.

Definiera en snäv revenue-integrity-regel

Ersätt exempeltabbarna med en regel döpt efter kontrollen. Tala om för utvärderaren att inte gissa orsaker:

{
  "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"}}
  }}
}Drivs av

Lägg till ett förberedelsekommando som skapar ett Git worktree för varje Ticket. Varje arbetare startar då från en repo-utcheckning:

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"Drivs av

Superagent fyller i dessa variabler för varje Ticket. Kontrollera att den resulterande katalogen innehåller den förväntade utcheckningen innan du auktoriserar arbete.

Den valfria konfigurationshjälparen skriver samma källa, policy, Eval och exekveringsblock. Den håller CI-observation avstängd under första passet; ställ alltid in experimentrepot och tillåten begärande uttryckligen:

export REPO="$EXPERIMENT_REPO"
export ALLOWED="YOUR_GITHUB_LOGIN"
bash /path/to/configure.sh allDrivs av

Håll proaktiv exekvering avstängd

Behåll Eval i observe med profilens standardmodell. Efter varje händelse, kontrollera fliken Eval för beslutet och fliken Execution för eventuella Tickets.

Slå på CI-observation och logga baslinjen

Efter att båda GitHub Actions-jobben passerat på main, slå på observation av CI för standardgren. Med hjälpskriptet, använd dess andra pass:

OBSERVE_CI=true bash /path/to/configure.sh source
bash /path/to/configure.sh showDrivs av

Första avläsningen loggar tillstånd utan att skapa arbete. Verifiera alla fyra villkoren:

• Installationen visar inget väntande krav.

• GitHub-källan rapporterar ready.

• Källan loggar en ren CI-baslinje.

• Flikarna Trigger och Execution visar ingen baslinje-Trigger eller Ticket.

Om något av dessa test misslyckas, stoppa innan du skapar dokumentationsfelet. Skärmdumparna för Källa och Eval visar den slutliga konfigurationen.

GitHub-kort med CI-observation. Bild av författaren.

Eval-inställningar: en regel, observera-läge. Bild av författaren.

Steg 4: Testa ett orelaterat fel i GitHub Actions

Använd en trasig README-länk som ett orelaterat fel. Eftersom den skyddade grenen avvisar en misslyckad kontroll, använd en mänsklig administratörs förbikoppling bara i detta engångsrepo; ge aldrig den förbikopplingen till agenten.

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 pushDrivs av

När GitHub Actions blev klart misslyckades docs-check och revenue-integrity passerade. Det matchade regeln jag hade satt: Superagent ignorerade kandidaten eftersom intäktsregeln inte matchade.

Beslutet använde ignoredFromCard, en genväg för kandidater som inte berör en aktiv regel. Så denna kontroll täcker dirigering, snarare än själva regeln.

Återställ README-ändringen och vänta på att båda jobben passerar. Superagent ska ignorera återhämtningen och förbli inaktiv.

Steg 5: Utlös ett CI-fel i Revenue Integrity

Använd samma väg endast för människor för att lägga till tillbudsdatan från handlednings-repot. Denna sammanfattning visar uppspelningen och de separata betalningarna på en order utan tidsstämpelkolumnerna:

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,firstDrivs av

Repot behåller de fullständiga tidsstämpelkolumnerna; de utelämnas här eftersom de inte avgör händelseidentitet. Den oberoende beräkningen som förberetts tidigare förväntar sig 15 100 cent, så sätt det värdet i testet och lägg till 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 passedDrivs av

De extra 5 000 centen är en betalning som räknats två gånger. Att ändra 15100 till 20100 eller ta bort uppspelningstestet skulle också göra CI grönt, och inget av det är en reparation.

Det misslyckade GitHub Actions-arbetsflödet visar bara revenue-integrity som faller. Dess Trigger kom efter ungefär ett pollningsintervall.

Utvärderingen markerade kandidaten ”skulle acceptera”, medan fliken Execution förblev tom. Utvärderaren såg kontrollnamn och slutsatser, inte pytest-loggen, så den visste vilken skydd som fallerade men inte varför.

Observera-läge loggar bara ”skulle acceptera”. Bild av författaren.

Steg 6: Auktorisera reparationen och verifiera pull requesten

Den tidigare beskrivna vägen för explicit begäran auktoriserar nu exekvering. GitHub-aviseringar kan vara sena.

Hantera ett missat omnämnande i GitHub Issue

I Superagent 6337fc8 överlappar GitHub-källan pollningar med fem sekunder och läser en aviserad tråd från den senare markören. Omnämnande-aviseringar anlände 21 till 23 sekunder senare, så en pollning kunde hoppa förbi meddelandet.

Tajmingen förklarar varför den nya Issue-brödtexten och några kommentarer aldrig blev Triggers. En community-rapport beskriver samma felmönster.

Auktorisera reparationen med en GitHub-kommentar

Posta begäran igen som en ny kommentar och bekräfta att dess Trigger dyker upp. Superagent ska acceptera den som en explicit begäran och starta arbetaren.

Kommentar-omnämnande skapar den auktoriserade Ticketen. Bild av författaren.

Kontrollera agentens fix för händelsededuplicering

Den resulterande pull requesten baserade fixen på event_id. Granska diffen i stället för att lita på beskrivningen:

 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")Drivs av

Den lade till ett uppspelningstest och tog inte bort något. Det första testkommandot misslyckades eftersom beroenden saknades. Efter att arbetaren skapat en virtuell miljö passerade den synliga testsuiten.

Testa betalningar som delar en order

Begär ändringar utan att nämna agenten: bevisa att två betalningar på en order, identiska bortsett från event_id, båda räknas, och att en uppspelning av en räknas en gång. Granskningen ska nå samma Ticket utan ny utvärdering.

Arbetaren svarade med en commit som bara lade till ett test och lämnade pipelinen oförändrad. Innan godkännande, kontrollera exakt head-SHA och kör om den oberoende sviten mot just den revisionen.

Granskningsfeedback fortsätter samma Ticket. Bild av författaren.

Kontrollera reparationen med oberoende data

Kör holdouten från den separata mänskliga miljön mot exakt pull request-head. På a43c541 klarade båda sviter 5 av 5 tester utan att ta bort en assertion; 62bac08 behöll samma träd.

Tester skrivna enbart av agenten täcker bara de fall agenten valde.

Steg 7: Slå ihop fixen och mät CI-återhämtning

Efter sammanslagningen, kontrollera att main återgår till grönt och att återhämtningen inte startar nytt arbete. Granska sedan händelsespåret, förlupen tid och leverantörskostnad.

Slå ihop fixen och bekräfta CI-återhämtning

Efter manuell godkännande och sammanslagning passerade båda kontrollerna för standardgrenen. Superagent ignorerade återhämtningen, startade inget mer arbete och stängde den befintliga Ticketen med utfallet merged.

Utvärdera händelseintag och beslut

Följ varje händelse från intag till utfall, som vår guide till utvärdering av AI-agenter beskriver. Över tre upprepningar tog händelser som nådde utvärdering den förväntade vägen; missar inträffade vid intag, inte vid modellbeslut.

Mät reparationsriktighet, tid och kostnad

Samma scenario kördes i tre nya repon och WSL-distributioner med Superagent 6337fc8, Harness 0.2.1-rc.3, deepseek-flash och en policy. Kostnader använder DeepSeeks lägre lågtrafik-taxa; detta är reproduktioner, inte ett benchmark.

Alla tre reparationer använde event_id; varje holdout-test passerade. Intaget varierade mer: omnämnandet i Issue-brödtexten missades varje gång, och den tredje reproduktionen missade dessutom två kommentarer innan en kom fram.

Den andra reproduktionen skrev om commits, och godkännande kom innan holdouten kördes om. Den senare kontrollen passerade, men den säkrare ordningen är head-SHA, holdout, sedan godkännande.

Begränsningar och felsökning för DeepSeek Superagent

Flera fel här ser ut som tystnad, så börja med att hitta var en händelse stannade. Det frustrerande är att en missad avisering och en korrekt ignorering kan se likadana ut.

CI-fel som inte ger någon Trigger

Superagent spårar förändringar i den felande mängden, så baslinjeavläsningen, en kontroll som fortsätter att fallera och kontroller som fortfarande körs ger ingenting. En Trigger utan beslut pekar oftast på CI-insläppscellen, inte modellen.

GitHub-begäranden som aldrig kommer fram

Begäranden kan misslyckas när avsändaren inte är tillåten, källan är avstängd, bearbetning är pausad eller GitHub aviserar sent. Om de kontrollerna passerar, posta en ny kommentar; redigering av Issue-brödtexten skapar ingen händelse.

Begränsningar i autonom CI-reparation

Prototypen ger ingen säkerhetsgräns. Arbetare har full OS-användaråtkomst, och regler för avslöjande är prompttext. Isolera agentkontot och begränsa det till engångsrepot.

Innan du byter till auto, samla veckor av observerade beslut, räkna felaktiga accepter likväl som felaktiga ignoreringar, och flytta arbetaren från WSL till en separat virtuell maskin.

Avslutande tankar

Inledningskontrasten stod sig: två röda CI-tillstånd ledde inte till samma åtgärd. Superagent ignorerade docs-check och markerade revenue-integrity som ”skulle acceptera”, medan observera-läget lät koden vara orörd tills en person begärde reparationen.

Patchen för event_id var okomplicerad. Intag av aviseringar var mindre pålitligt: omnämnandet i Issue-brödtexten nådde aldrig utvärderingen, så en korrekt regel kunde inte hjälpa.

Jag skulle inte generalisera detta resultat till autonom CI-reparation. Repot var litet, regeln snäv och sammanslagningen styrd av människor. På andra håll: börja grönt, inspektera beslut, auktorisera uttryckligen, håll holdout-data separata och slå ihop efter oberoende kontroller.

Mitt nästa steg vore att fixa GitHub-aviseringarnas väg och upprepa arbetsflödet med fler feltyper. Tills det finns bevis skulle jag hålla auto-läget av.