Eine Änderung planen

handbook plan --source <repo> --handbook <dir> --request "<text>" --out plan.md

Der Planner ist ein rein lesender Agent. Er listet, liest und greppt — er hat überhaupt kein Schreibwerkzeug, nicht einmal ein deaktiviertes — und seine Ausgabe ist ein Plan, den etwas anderes ausführt.

Die Schleife

1. Mit dem Handbook routen: Welche Dateien, Funktionen und welcher Zustand sind betroffen?
2. Die echte Quelle an jeder gefundenen Adresse lesen.
3. ### EDIT n-Blöcke mit byte-genauem old- und new-Text ausgeben.
4. Mit einem JSON-Deklarationsblock abschließen.

Eine gute Anfrage formulieren

Beschreiben Sie das gewünschte Verhalten, nicht die Datei, in der Sie es vermuten. Eine Datei zu nennen verengt die Suche des Planners auf die Stelle, an die Sie ohnehin schon gedacht haben — und genau das verfehlt den Zweck.

Den Plan lesen

### EDIT 1

- file: `src/upload.py`
- where: `Uploader.send (~88)` — wrap the request in the retry helper

```old
    response = self._client.put(url, data)
```

```new
    response = self._retry(lambda: self._client.put(url, data), attempts=3)
```

### EDIT 2

- file: `src/upload.py`
- where: `Uploader` — add the helper

```old
    def send(self, url, data):
```

```new
    def _retry(self, call, attempts):
        last = None
        for _ in range(attempts):
            try:
                return call()
            except TransientError as exc:
                last = exc
        raise last

    def send(self, url, data):
```

Both call sites now share one retry policy.

```json
{ "will_modify": ["Uploader.send"], "will_add": ["Uploader._retry"], "will_remove": [] }
```

Regeln, denen das Format gehorcht:

• old muss byte-genau sein und genau einmal in der Datei vorkommen.
• Ein leeres old bedeutet „diese Datei anlegen".
• Edits sind nummeriert und aufsteigend, von oben nach unten.
• Der abschließende json-Block wird von resync konsumiert, um seinen Aktualisierungsumfang zu schärfen.

Lesen Sie den Plan, bevor Sie ihn anwenden. Der Dry-Run sagt Ihnen, ob er sich anwenden ließe; nur Sie können beurteilen, ob er angewendet werden sollte.

Wenn er aufgibt

plan beendet sich mit einem Exit-Code ungleich null — es schreibt keine Entschuldigung in plan.md, die ein Skript anschließend in apply füttert.

Feinjustieren

Ohne Handbooks

handbook plan --source ~/code/api --request "…"

Es funktioniert — der Planner fällt darauf zurück, die Quelle direkt zu erkunden —, aber das ist der degradierte Modus. Das Handbook existiert genau deshalb, weil ungeführte Exploration die offensichtlichen Stellen findet und die verstreuten übersieht.

Was die Sandbox erlaubt

list_dir(path)
read_file(path, start_line?, end_line?)
grep(pattern, path)
finish(plan)

• Jeder Pfad wird innerhalb des Sandbox-Wurzelverzeichnisses aufgelöst; Ausbrüche, auch über Symlinks, werden abgelehnt.
• Das Handbook ist schreibgeschützt unter __handbook__/ eingehängt, einer von der Quelle getrennten Sandbox.
• Lesezugriffe sind auf 60.000 Zeichen begrenzt; grep ist auf 100 Treffer begrenzt und überspringt Dateien über 5 MB.
• Katastrophale reguläre Ausdrücke — ein unbeschränkter Quantifizierer über einer Gruppe, die selbst einen enthält, wie (a+)+ oder (.*)* — werden mit einem sauberen Tool-Fehler abgewiesen, statt den Lauf aufzuhängen.

Weiter