--- title: AgentScope-Patterns — Adoption-Mapping für Aria (KAR-686) type: reference date: 2026-06-04 status: aktiv tags: [agentscope, patterns, hooks, compaction, skill-loader, architecture, kar-686] source: https://github.com/agentscope-ai/agentscope related: [[oss-stack-audit-2026-06-04]], [[HOOKS]] --- # AgentScope-Patterns → Aria-Adoption (KAR-686) Quelle: agentscope-ai/agentscope (Apache-2.0, v2.0.0). **Nicht das Framework** — die Architektur-Patterns. Aria läuft auf Claude Code, nicht auf einer eigenen Python-Agent-Loop. Das setzt Grenzen, die hier ehrlich gemappt sind (kein Cargo-Cult). ## Die 5 Patterns + ehrliche Aria-Übersetzung ### 1. Onion-Middleware-Chain → Hook-Manifest (legibel + geordnet + validiert) **AgentScope**: 5 named Lifecycle-Hooks (`on_reply`, `on_reasoning`, `on_acting`, `on_model_call`, `on_compress_context`) mit `next_handler`-Chaining — explizite Reihenfolge, introspektierbar. **Runtime-Constraint**: Arias Hooks laufen über Claude Codes **natives** Hook-System (settings.json, Events: SessionStart/UserPromptSubmit/PreToolUse/PostToolUse/PreCompact/Stop). Der Dispatch + die Reihenfolge (Array-Order pro Event+Matcher) gehören dem Harness — ich kann sie NICHT durch eine eigene Python-Middleware-Chain ersetzen. Eine selbstgebaute Chain wäre tot, weil der Runtime sie nie aufruft. **Adoptierbarer Kern**: Was AgentScope wirklich gibt, ist *Legibilität + explizite Ordnung + Introspektion*. Arias Äquivalent = ein **auto-generiertes, validiertes Hook-Manifest** aus settings.json: - pro Event die Hooks in Ausführungs-Reihenfolge (`order`-Index = die „Chain") - Matcher, Script-Pfad, Timeout, Zweck - Validierung: referenziertes Script existiert? Orphan-Scripts im hooks-Dir die nirgends registriert sind? - rendert die HOOKS.md-Sektion automatisch → killt den Drift (HOOKS.md stand auf „V5 Sprint 1", gateguard/tdd-guard/rtk/pre-output-critic fehlten). **Status: IMPLEMENTIERT + VERDRAHTET** — `scripts/aria-hook-manifest.py` (--check / --render / --json / --update-hooks-md) + Test 15/15. HOOKS.md hat jetzt einen marker-delimitierten Auto-Block (``), additiv eingefügt (manuelle Detail-Tabelle erhalten), per `--update-hooks-md` regenerierbar → Drift tot. Re-Run ist idempotent. Fehlende UserPromptSubmit-Kette (auto-memory-inject/telegram-reply-discipline/aria-effort-detect) war der reale Drift, jetzt sichtbar. ### 2. Context-Compression mit Summary-Field → garantierte Compaction-Summary **AgentScope**: `AgentState.summary` = komprimierter Alt-Kontext wird dem LLM **vorangestellt**, nicht verworfen. **Aria heute**: `pre-compact.sh` schreibt nur einen `(TBD)`-Stub nach HANDOFF.md mit dem Kommentar „Aria sollte vor Compaction selbst füllen". Wenn Aria das nicht tut → Stub bleibt leer → Kontext-Verlust über Compaction-Grenze (das ist die HANDOFF.md-Drift-Wurzel, KAR-73). Es gibt zwar `aria-compaction-watch.sh` + `aria-memory-consolidate-night.py`, aber die garantieren keine Pre-Compact-Summary. **Adoption**: `pre-compact.sh` v2 garantiert jetzt eine **nicht-leere Summary** — bettet die ACTIVE_TASK-Working-Memory (head -c 1800) + letzte 5 Brain-Commits deterministisch in den HANDOFF-Eintrag (kein LLM nötig → nie leer). Re-Injektion via session-start.sh (lädt HANDOFF). Pfade env-überschreibbar für Tests. Backup `pre-compact.sh.bak-20260604`. Smoke-Test 7/7. **Status: IMPLEMENTIERT.** **Offen/Folge**: HANDOFF.md wächst (schon 113KB, Bootstrap truncated auf 12KB) — Rotation ist ein separates Thema (nicht KAR-686). Optional kann Aria die „Aria-Ergänzung"-Zeilen vor Compaction noch füllen. ### 3. Skill = Markdown-Dataclass + async Discovery → Skill-Index **AgentScope**: `Skill(name, description, dir, content, updated_at)` + `SkillLoaderBase.list_skills()` für dynamisches Discovery. **Aria heute**: 77 Skills als Verzeichnisse mit `SKILL.md` (Frontmatter `name` + `description`), plus `aria-skill-curator.sh` + `create-aria-skill.sh`. Aber **kein maschinen-lesbarer Index** — Skill-Discovery passiert nur über die Harness-Skill-Liste, nicht brain-search-integriert. **Adoption**: `aria-skill-index.py` scannt Skill-Dirs, parst SKILL.md-Frontmatter (name/description/dir/mtime), emittiert JSON-Index (`state/skill-index.json`) → brain-search-integrierbar + Curator-Input (stale via mtime). Modi: default (Index schreiben), `--search Q`, `--check`. **Status: IMPLEMENTIERT** — 77 Skills indexiert, Test 12/12. **Lesson (wichtig)**: strict-`yaml.safe_load` zerbricht an Arias realem Frontmatter (ASCII-Quotes IN quotierten Strings, Wiki-Link-Doppelklammern) → lieferte False-Negatives (4 Skills fälschlich „ohne description"). Fix: yaml-Versuch + toleranter Regex-Fallback der name+description rettet. Gilt für jeden künftigen Frontmatter-Parser im Aria-Stack. ### 4. PermissionMode/Behavior-Enum → aria-mode-toggle formalisieren (optional) AgentScope hat `PermissionMode` + `PermissionBehavior` als Enum-Paar + Permission-Rules pro Modus. Arias assist/auto/yolo ist ein Freitext-String in `/root/aria/state/mode`. Könnte zu expliziten Permission-Rules pro Modus formalisiert werden. **Status: OPTIONAL/Backlog.** ### 5. Event-Stream mit RequireUserConfirmEvent → Pause/Resume mid-tool (optional) AgentScope kann mid-tool-execution pausieren (Human-in-the-Loop) ohne State-Verlust. Arias Gate dafür wäre aria-mode-toggle + pre-tool-safety. **Status: OPTIONAL/Backlog** (Runtime-Constraint ähnlich #1). ## Security-Notizen Apache-2.0 (Distribution unproblematisch). DashScope (Alibaba-LLM) nur explizit wählbar — kein Default- China-Routing. Beim Pattern-Bau ReAct-Standard-Injection mitdenken (Tool-Output→nächster-Input), aber da wir nur Patterns übernehmen und auf Claude Code bleiben, kein neuer Vektor. ## Reihenfolge der Umsetzung 1 (Manifest, Fundament/Legibilität) → 3 (Skill-Index, self-contained) → 2 (Compaction-Summary, braucht Sorgfalt um Night-Consolidation nicht zu brechen) → 4/5 optional.