docs: talk-Skill mit Opt-in-Etikette, AGENTS-Snippet, README Installation/Release/Toast

skills/talk/SKILL.md: wann sprechen (nur auf Trigger in der Session oder
Standing-Order in der AGENTS.md, session-sticky bis Widerruf), wann nicht,
was eine gute Ansage ist (Status · nächster Schritt · wofür der Nutzer
gebraucht wird; Beispiele gut/schlecht), Umgang mit muted/discarded/
--now/Prioritäten, Pitfalls. AGENTS-snippet.md: der Block für Projekt-
AGENTS.md.

README: Installation (Release-Asset mit Prüfsumme, Nix-Flake, go install),
Skill-Abschnitt, Toast als echte Desktop-Benachrichtigung, Release-Ablauf
und nix build in „Entwicklung". Spec-Nachtrag: Release ohne GoReleaser,
Notifications ohne beeep.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
m3ta-chironandClaude Fable 5.1 committed 2026-10-24 10:37:46 +02:00
1 parent 423377bade
commit 2e2bc27acf
4 files changed
+152 -3

No files matched your search

+46 -3
View File
@@ -29,6 +29,26 @@ Runtime-Abhängigkeiten.
Say-Flags (gelten auch für `talk "Text"`): `--wait`, `--now`, `--priority`,
`--voice`, `--lang`, `--provider`.
## Installation
**Release-Binary** (Linux, macOS, Windows; amd64/arm64): von den
[Releases](https://code.m3ta.dev/m3tam3re/talk/releases) das passende
`talk_<os>_<arch>` laden, Prüfsumme gegen `checksums.txt` vergleichen, als
`talk` in den PATH legen. Keine weiteren Abhängigkeiten.
```console
curl -LO https://code.m3ta.dev/m3tam3re/talk/releases/latest/download/talk_linux_amd64
sha256sum -c --ignore-missing <(curl -sL https://code.m3ta.dev/m3tam3re/talk/releases/latest/download/checksums.txt)
install -m 755 talk_linux_amd64 ~/.local/bin/talk
```
**Nix** (Flake): `nix run git+https://code.m3ta.dev/m3tam3re/talk -- doctor`
oder in der Konfiguration `inputs.talk.url = "git+https://code.m3ta.dev/m3tam3re/talk";`
und `inputs.talk.packages.${system}.talk` bzw. `inputs.talk.overlays.default`.
Das Paket bringt espeak-ng (OS-Stimme) und libnotify (Toast) mit.
**Aus dem Quelltext:** `go install code.m3ta.dev/m3tam3re/talk/cmd/talk@latest`.
## Erste Schritte
```console
@@ -150,9 +170,10 @@ sind Opt-in wie Mute). In der Ruhezeit verfällt Audio, auch für high
(Burst ist ein Rate-Recht, kein Ruhe-Recht):
- `quiet_mode = "discard"` (Default): still verwerfen.
- `quiet_mode = "toast"`: Benachrichtigung statt Audio — derzeit eine
Protokoll-Zeile über den Notification-Pfad (OS-Toast folgt mit der
Notification-Anbindung).
- `quiet_mode = "toast"`: Desktop-Benachrichtigung statt Audio — über die
Bordmittel des Systems (Linux `notify-send`, macOS Notification Center,
Windows Toast), best effort: fehlt das Werkzeug, bleibt es bei der
Protokoll-Zeile, `talk doctor` zeigt es unter „Toast".
- `now:true` **bricht auch die Ruhezeit** (bewusster Ausbruch).
**Länge und Alter:** Zwei weitere Gesetze gegen das, was Prompts gern tun
@@ -350,6 +371,18 @@ talk wrap --wait -- make test
label = "Deployment" # Ansage-Label statt Befehls-Basisname (TALK_WRAP_LABEL)
```
## Für Agenten: Skill und Standing-Order
[`skills/talk/SKILL.md`](skills/talk/SKILL.md) ist die Etikette als
Skill-Artefakt: **striktes Opt-in** (Sprechen nur auf Aufforderung in der
Session oder Standing-Order in der AGENTS.md, session-sticky bis Widerruf),
Inhalt = Status · nächster Schritt · wofür der Nutzer gebraucht wird, nie
die Langantwort, `muted`/`discarded` respektieren. Der Drei-Zeilen-Block
für Projekt-AGENTS.md steht in
[`skills/talk/AGENTS-snippet.md`](skills/talk/AGENTS-snippet.md). Der
Daemon erzwingt Rate-Limit, Längen- und Alters-Grenze, Mute und Ruhezeit
unabhängig davon, was im Prompt steht.
## Entwicklung
```console
@@ -357,11 +390,21 @@ go build ./... # bauen
go test ./... # Tests
go vet ./... # statische Analyse
gofmt -l . # Formatierung prüfen (leerer Output = ok)
nix develop # devShell mit go, gopls, espeak-ng, libnotify
```
CI: `.gitea/workflows/test.yml` (Gitea Actions) läuft vet, gofmt-Check, Tests
und Build bei jedem Push und Pull Request.
**Release:** Tag `v*` pushen → `.gitea/workflows/release.yml` testet, baut
mit `scripts/release.sh` die sechs Targets (statisch, `CGO_ENABLED=0`,
Version per ldflags) und legt ein Gitea-Release mit `talk_<os>_<arch>[.exe]`
und `checksums.txt` an. Lokal: `scripts/release.sh 1.2.3` → `dist/`. Bewusst
ohne GoReleaser: ein Shell-Skript über `go build` ist dasselbe Artefakt,
lokal wie in CI, ohne zusätzliches Werkzeug. `nix build .#talk` baut das
Nix-Paket (nach Änderungen an go.mod den `vendorHash` in flake.nix
nachziehen — `nix build` nennt den erwarteten Wert).
## Lizenz
MIT — siehe [LICENSE](LICENSE).