Paweł Domański
175 lines
3.9 KiB
Markdown
175 lines
3.9 KiB
Markdown
Poniżej masz **konkretny, README‑ready opis HOOK‑a typu `command‑logger`**, dopasowany do Twojego stylu operacyjnego (OpenClaw / org‑mode / „plaintext productivity”). To **opis projektowy + kontrakt**, nie marketing.
|
||
|
||
***
|
||
|
||
# HOOK: `command-logger`
|
||
|
||
## Cel
|
||
|
||
`command-logger` to **globalny hook obserwacyjny**, który **rejestruje każde polecenie / wywołanie SKILL‑a** wraz z kontekstem wykonania, **bez wpływu na logikę biznesową**.
|
||
Jego jedyną odpowiedzialnością jest **audit trail** i **rekonstrukcja przebiegu pracy**.
|
||
|
||
> To jest odpowiednik `bash history + strace + journalctl`, ale na poziomie **AI / SKILL routera**.
|
||
|
||
***
|
||
|
||
## Miejsce w architekturze
|
||
|
||
* typ: **HOOK (side‑effect only)**
|
||
* moment: **BEFORE + AFTER execution**
|
||
* zasięg: **router + wszystkie sub‑skills**
|
||
* brak modyfikacji danych wejściowych/wyjściowych
|
||
|
||
<!---->
|
||
|
||
User → Router
|
||
↳ HOOK: command-logger (BEFORE)
|
||
→ Skill / Sub-skill
|
||
↳ HOOK: command-logger (AFTER)
|
||
|
||
***
|
||
|
||
## Co jest logowane (kontrakt)
|
||
|
||
### 1. Metadane techniczne
|
||
|
||
* `timestamp_start`
|
||
* `timestamp_end`
|
||
* `duration_ms`
|
||
* `session_id`
|
||
* `trace_id`
|
||
* `parent_trace_id`
|
||
* `host` / `agent_id`
|
||
|
||
### 2. Kontekst wykonania
|
||
|
||
* `actor` (user / system / agent)
|
||
* `skill_name`
|
||
* `skill_version`
|
||
* `hook_phase` (`before` | `after`)
|
||
* `stage` (np. Inicjacja / Badania / Transakcja)
|
||
* `intent` (jeśli wykryty przez router)
|
||
|
||
### 3. Dane operacyjne (bezpieczne)
|
||
|
||
* `command` – **skrót/identyfikator**, nie pełny prompt
|
||
* `input_fingerprint` (hash / checksum)
|
||
* `output_fingerprint`
|
||
* `status` (`ok` | `error`)
|
||
* `error_type` (jeśli wystąpił)
|
||
|
||
> **Zasada**: logujemy **fakty o operacji**, nie jej treść semantyczną.
|
||
|
||
***
|
||
|
||
## Format zapisu (org‑mode friendly)
|
||
|
||
### Jeden plik = jeden strumień pracy
|
||
|
||
`command-log.org`
|
||
|
||
```org
|
||
* 2026-03-16 09:12:04 | router
|
||
:PROPERTIES:
|
||
:session: 9f3a…
|
||
:trace: r-001
|
||
:phase: before
|
||
:actor: user
|
||
:stage: Badania
|
||
:intent: seo-research
|
||
:END:
|
||
Command: route → seo-research
|
||
Input: sha256:8ac7…
|
||
```
|
||
|
||
```org
|
||
* 2026-03-16 09:12:18 | seo-research
|
||
:PROPERTIES:
|
||
:session: 9f3a…
|
||
:trace: r-001
|
||
:parent: r-000
|
||
:phase: after
|
||
:status: ok
|
||
:duration_ms: 14231
|
||
:END:
|
||
Output: sha256:91bd…
|
||
```
|
||
|
||
✅ spełnia:
|
||
|
||
* plaintext
|
||
* diff‑friendly
|
||
* audytowalne
|
||
* nadaje się do grep / ripgrep / org‑agenda
|
||
|
||
***
|
||
|
||
## Zasady projektowe (ważne)
|
||
|
||
### ✅ Co `command-logger` MOŻE
|
||
|
||
* rejestrować
|
||
* tagować
|
||
* agregować
|
||
* eksportować (np. do Splunk / JSONL)
|
||
|
||
### ❌ Czego NIE MOŻE
|
||
|
||
* zmieniać inputu
|
||
* zmieniać outputu
|
||
* blokować wykonania
|
||
* podejmować decyzji
|
||
|
||
> Jeśli HOOK zaczyna „myśleć” → to **nie jest już hook**, tylko policy‑engine.
|
||
|
||
***
|
||
|
||
## Przykładowa definicja (konceptualna)
|
||
|
||
```yaml
|
||
hook:
|
||
name: command-logger
|
||
type: observer
|
||
phases: [before, after]
|
||
scope: global
|
||
output:
|
||
format: org
|
||
file: command-log.org
|
||
privacy:
|
||
log_payload: false
|
||
use_fingerprints: true
|
||
```
|
||
|
||
***
|
||
|
||
## Typowe use‑case’y
|
||
|
||
* ✅ **rekonstrukcja dnia pracy** („co robiłem i dlaczego”)
|
||
* ✅ **debug AI** (gdzie poszło nie tak)
|
||
* ✅ **time audit** pod książkę o produktywności
|
||
* ✅ **compliance / audit trail**
|
||
* ✅ **trening systemu** (analiza sekwencji, nie treści)
|
||
|
||
***
|
||
|
||
## Anty‑wzorce
|
||
|
||
❌ logowanie pełnych promptów
|
||
❌ logowanie danych wrażliwych
|
||
❌ zależność innych SKILL‑i od loggera
|
||
❌ brak identyfikatorów sesji / trace
|
||
|
||
***
|
||
|
||
## TL;DR (jednym zdaniem)
|
||
|
||
> **`command-logger` to czarny skrzynkowy rejestr zdarzeń**, który zapisuje *że coś się stało, kiedy, gdzie i z jakim skutkiem* — **bez ingerencji w to, co i dlaczego**.
|
||
|
||
***
|
||
|
||
Jeśli chcesz, w kolejnym kroku mogę:
|
||
|
||
* dodać **diagram Mermaid tylko dla HOOK‑ów**
|
||
* rozpisać **drugiego hooka**: `decision-logger` (tylko dla routera)
|
||
* albo przygotować **OpenClaw SKILL: hooks/command-logger** (router + middleware)
|