菜单
Reactive Agents framework architecture — layer stack, dependency graph, build order, and package structure. Use when planning work, understanding package relationships, or determining build dependencies.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Agentic harness diagnostic + improvement loop. Probes the framework with real model runs, uses the rax-diagnose CLI to root-cause failures from structured trace data, ships ONE coordinated architectural fix, verifies via before/after diff, commits with empirical evidence. Use at the start of any harness improvement session — replaces ad-hoc grep + log-spelunking with a deterministic feedback loop.
Use when the architecture may have drifted from documentation, packages have grown complex, dead code or disabled systems are suspected, or before planning a major refactor — scoped to the reactive-agents-ts 22-package monorepo.
Use when analyzing the Reactive Agents codebase for architectural improvements, abstraction opportunities, composability gaps, or Effect-TS engineering quality — before proposing refactors, during design reviews, or when codebase complexity is growing.
LLMService API contract — the correct signatures for complete(), stream(), embed(), and response types. Use when calling LLMService from any layer, writing reasoning strategies, or building LLM-dependent features.
LLM provider streaming patterns and per-provider quirks. Use when adding a new provider, implementing adapter hooks, or debugging streaming tool call behavior in packages/llm-provider.
Configure a ReactiveAgentBuilder with the correct layer composition for any agent use case.
| name | architecture-reference |
| description | Reactive Agents framework architecture — layer stack, dependency graph, build order, and package structure. Use when planning work, understanding package relationships, or determining build dependencies. |
| user-invocable | false |
For complete framework orientation, see
NAVIGATION.md(repo structure + file mapping) andQUICK_START.md(5-minute quickstart).For architectural questions, prefer
claude-obsidian:wiki-query "<topic>"over reading individual files. The wiki has MOCs, decisions, mechanism validations, and design specs that surface in semantic queries. See [[wiki/Development/Wiki-Workflow|Wiki-Workflow.md]] for the canonical pattern.
| Question | Where to look |
|---|---|
| "What's the kernel structure?" | wiki/Architecture/Specs/05-DESIGN-NORTH-STAR.md §Cognitive Architecture |
| "Why was decision X made?" | wiki/Decisions/Decision Index.md |
| "What package contains Y?" | wiki/Packages/00 Package Index.md |
| "Has mechanism Z been validated?" | wiki/Experiments/M*.md (or wiki/Experiments/by-verdict.base) |
| "What failure modes apply here?" | wiki/Failure-Modes/by-severity.base |
| "Current empirical state?" | wiki/Architecture/Specs/04-PROJECT-STATE.md |
| "Roadmap for v1.0?" | wiki/Architecture/Specs/07-ROADMAP-v1.0.md |
Zero internal deps:
@reactive-agents/core — EventBus, types, Agent/Task services@reactive-agents/runtime-shim — unified Bun/Node.js primitives; consumed by memory, tools, health, judge-serverDepends on core only:
@reactive-agents/llm-provider → core@reactive-agents/observability → core@reactive-agents/identity → core@reactive-agents/a2a → core@reactive-agents/interaction → core@reactive-agents/observe → core — OpenInference/OTel span exporterDepends on core + llm-provider:
@reactive-agents/memory → core, llm-provider@reactive-agents/tools → core, llm-provider@reactive-agents/guardrails → core, llm-provider@reactive-agents/cost → core, llm-provider@reactive-agents/eval → core, llm-provider@reactive-agents/prompts → core, llm-providerHigher layers:
@reactive-agents/reasoning → core, llm-provider, memory, tools@reactive-agents/verification → core, llm-provider, memory@reactive-agents/gateway → core, llm-provider, tools@reactive-agents/reactive-intelligence → core, llm-provider@reactive-agents/replay → core, trace, runtime — deterministic trace replay@reactive-agents/compose → core, runtime — harness composition + 6 killswitchesPlanned (branch feat/channels-package, not merged to main):
@reactive-agents/channels → core, gateway (external triggers, session bridge, webhook adapter); consumed by @reactive-agents/runtime via .withChannels() and optional dynamic import at start(). Gateway channels → accessControl rename separates sender policy from chat/task mode. See wiki/Research/Debriefs/2026-05-03-channels-phase1-development-debrief.md.Facade (depends on ALL):
@reactive-agents/runtime → all packages (composes layers via createRuntime())reactive-agents → runtime (public API re-export)Private (never published):
@reactive-agents/testing → core, llm-provider@reactive-agents/benchmarks → runtime@reactive-agents/health → coreBuild runs in dependency order. Lower layers must build before higher layers.
Phase 1: core → llm-provider
Phase 2: memory, tools, guardrails, cost, identity, observability, interaction, prompts, eval, a2a (parallel)
Phase 3: reasoning, verification, orchestration, gateway, reactive-intelligence (parallel)
Phase 4: runtime → reactive-agents (facade)
Phase 5: testing, benchmarks, health, cli, docs (parallel)
Phase 1: BOOTSTRAP MemoryService.bootstrap(agentId)
Phase 2: GUARDRAIL GuardrailService.checkInput(input)
Phase 3: STRATEGY-SELECT AdaptiveStrategy or config.defaultStrategy
Phase 4: THINK ReasoningService.execute() → kernel loop
Phase 5: ACT (synthetic — extracted from reasoning steps)
Phase 6: OBSERVE (synthetic — extracted from reasoning steps)
Phase 7: MEMORY-FLUSH MemoryExtractor + MemoryService.snapshot()
Phase 8: VERIFY VerificationService.verify(result) [optional]
Phase 9: AUDIT AuditService.log() [optional]
Phase 10: COMPLETE EventBus.publish("AgentCompleted") + DebriefSynthesizer
All 6 strategies delegate to runKernel(reactKernel, input, options) in packages/reasoning/src/kernel/.
makeKernel({ phases?: Phase[] })
↓
kernel-runner.ts: runKernel() loop
↓ per turn:
1. context-builder.ts — buildSystemPrompt, toProviderMessage, buildConversationMessages, buildToolSchemas (pure data, no LLM)
2. think.ts — LLM stream, FC parsing, fast-path, loop detection, oracle hard gate
3. guard.ts — Guard[] pipeline, checkToolCall(guards), defaultGuards[]
4. act.ts — MetaToolHandler registry, final-answer gate, tool dispatch
packages/reasoning/src/kernel/
kernel-state.ts — KernelState, Phase type, KernelContext, ThoughtKernel
kernel-runner.ts — the loop: runKernel() — DO NOT add per-turn logic here directly
kernel-hooks.ts — KernelHooks lifecycle hooks
react-kernel.ts — makeKernel() factory + reactKernel + executeReActKernel
phases/
context-builder.ts — pure data: builds what the LLM sees this turn
think.ts — LLM decision: stream, FC parsing, loop detection
guard.ts — Guard[] pipeline: is this tool call allowed?
act.ts — MetaToolHandler registry: what happens when tools run?
utils/
ics-coordinator.ts, reactive-observer.ts, loop-detector.ts
tool-utils.ts, tool-execution.ts, termination-oracle.ts, strategy-evaluator.ts
stream-parser.ts, context-utils.ts, quality-utils.ts, service-utils.ts, step-utils.ts
state.messages[] ← What the LLM sees (multi-turn FC conversation thread)
state.steps[] ← What systems observe (entropy, metrics, debrief)
Do NOT conflate these. Debugging LLM behavior → inspect messages[]. Debugging metrics/entropy → inspect steps[].
phases/<name>.ts, insert into makeKernel({ phases: [...] })Guard fn to guard.ts, add to defaultGuards[]metaToolRegistry in act.tsmakeKernel({ phases: [myThink, act] })See .agents/skills/kernel-extension/SKILL.md for full patterns.
context-manager.ts — ContextManager.build(state, input) returns { systemPrompt, messages } (pure, deterministic)context-builder.ts — assembles raw conversation messages (buildConversationMessages), tool schemas, system prompt basethink.ts — invokes buildGuidanceSection(state.pendingGuidance) and appends Guidance: block to system promptcontext-engine.ts — retains only buildStaticContext, buildEnvironmentContext, buildRules; all dynamic/scoring code removedLocation: packages/tools/src/mcp/mcp-client.ts
| Pattern | Examples | Behavior |
|---|---|---|
| stdio MCP | GitHub MCP, filesystem | Container reads JSON-RPC from stdin |
| HTTP-only | mcp/context7 | Container starts HTTP server, ignores stdin |
Both handled transparently via auto-detection.
docker rm -f <containerName> is the ONLY reliable container stop. subprocess.kill() leaves the container alive in the Docker daemon.rax-probe-<name>-<pid> (initial stdio probe) → rax-mcp-<name>-<pid> (port-mapped HTTP if HTTP detected)command → "stdio", endpoint /mcp → "streamable-http", other endpoint → "sse"transport field is optional in MCPServerConfig — auto-inferred at runtimeSee .agents/skills/mcp-integration/SKILL.md for full patterns.
| Decision | Choice |
|---|---|
| Language | TypeScript (strict mode) |
| Runtime | Bun >= 1.1 |
| FP framework | Effect-TS (^3.10) |
| Database | bun:sqlite (WAL mode), FTS5, sqlite-vec |
| LLM providers | Anthropic, OpenAI, Ollama, Gemini, LiteLLM (40+) |
| Module system | ESM ("type": "module") |
| Build | tsup (ESM + DTS) |
| Test | bun:test |
| Versioning | Changesets (fixed group) |
| What you need | Where to look |
|---|---|
| Full file-level system map | wiki/Architecture/Framework-Architecture-Index.md |
| Coding standards | CODING_STANDARDS.md |
| Effect-TS patterns | .agents/skills/effect-ts-patterns/SKILL.md |
| LLM API signatures | .agents/skills/llm-api-contract/SKILL.md |
| Memory/SQLite patterns | .agents/skills/memory-patterns/SKILL.md |
| Spec documents | spec/docs/ |
| Build commands | AGENTS.md (Build & Test Cycle) and README.md (quickstart/dev commands) |
| Extending the kernel | .agents/skills/kernel-extension/SKILL.md |
| Debugging agent behavior | .agents/skills/kernel-debug/SKILL.md |
| Provider streaming patterns | .agents/skills/provider-streaming/SKILL.md |
| MCP client patterns | .agents/skills/mcp-integration/SKILL.md |
| Full feature workflow | .agents/skills/reactive-feature-dev/SKILL.md |