chore: migrate services to integration folder

2026-08-02 20:12:13 +08:00
parent 4ccde2c96e
commit d5a241b10e
344 changed files with 62 additions and 58 deletions
@@ -0,0 +1,76 @@
+---
+name: minecraft-debug-mcp
+description: Operate and debug the live Minecraft bot through its built-in MCP REPL server. Use when work requires starting the bot with `pnpm dev`, connecting to the local MCP endpoint, inspecting cognitive state/logs/history, injecting synthetic chat/events, or running targeted REPL code against the running brain during investigation and development.
+---
+
+# Minecraft Debug MCP
+
+## Overview
+
+Use this skill to run the local bot and interact with its MCP debug interface safely and quickly.
+
+## Quick Start Workflow
+
+1. Run `pnpm dev` from `/path/to/project/root/integrations/minecraft` and keep it running.
+2. Wait for `MCP REPL server running at http://localhost:3001` in logs.
+3. Connect MCP client to `http://localhost:3001/sse`.
+4. Verify readiness with a read-only call:
+   - Read resource `brain://state`, or
+   - Call tool `get_state`.
+5. Continue with the smallest tool/action that answers the task.
+
+## Execution Rules
+
+- Start read-only, then escalate to mutation tools only when needed.
+- Prefer `get_state`, `get_last_prompt`, and `get_logs` for diagnostics before `execute_repl`.
+- Prefer `get_llm_trace` for structured per-attempt reasoning/content inspection.
+- Keep `execute_repl` snippets minimal and reversible.
+- Use `inject_chat` for conversational simulation and `inject_event` only when specific event-shape testing is required.
+- Treat `inject_chat` as side-effectful: it can trigger actual in-game bot replies/actions.
+- If MCP connection fails, check that `pnpm dev` is still running and port `3001` is free.
+
+## Tooling Strategy
+
+- Use `get_state` to inspect queue/processing state and available tools/actions (skips REPL builtins by default; pass `{ includeBuiltins: true }` to include them).
+- Use `get_logs` with a small `limit` first.
+- Use `get_last_prompt` to inspect latest LLM input.
+- Use `execute_repl` for deep object inspection or one-off targeted calls on the running brain.
+- Use `inject_chat` to simulate player chat and verify behavior loop.
+- Use `get_llm_trace` to assert REPL behavior in automation (for example, detect repeated `await skip()` on specific events).
+- Use `execute_repl("forget_conversation()")` to clear conversation memory before prompt-engineering tests.
+
+Read `references/mcp-surface.md` for exact tool/resource names and argument schemas.
+
+## Live-Tested Notes
+
+- `get_state` returns available tools/actions and runtime state (skips REPL builtins like `skip`, `use`, `log` by default to reduce noise; pass `{ includeBuiltins: true }` if you need to inspect them).
+- `get_last_prompt` can return very large payloads; call only when prompt-level debugging is needed.
+- `execute_repl` returns a structured result where `returnValue` is stringified; parse mentally as display output, not typed JSON.
+- `get_logs(limit=10)` is enough to verify whether an injected event reached REPL/executor.
+- `get_llm_trace(limit, turnId?)` gives structured attempt-level trace data (messages, content, reasoning, usage, duration).
+- `get_last_prompt` and `get_llm_trace` are compacted for MCP: system prompt/system-role messages are omitted to reduce token cost.
+- Prefer compact value reads in REPL:
+  - `query.self()` for bot status.
+  - `query.inventory().has(name, n)` / `query.inventory().count(name)` for checks.
+  - `query.inventory().summary()` for stable aggregated item output.
+  - `query.snapshot(range?)` for one-shot world+inventory capture.
+- `forget_conversation()` is available as a runtime function in REPL/global context and clears only conversation memory.
+- Current prompt behavior supports two-turn value-first flows: read/query turn returns concrete data first, follow-up turn performs chat/action using that returned value.
+
+## Live Testing Workflow
+
+1. Confirm MCP health:
+   - Call `get_state`.
+2. Capture baseline inventory:
+   - `execute_repl` with `query.inventory().list().map(i => ({ name: i.name, count: i.count }))`.
+3. Trigger a task through normal cognition path:
+   - Call `inject_chat` with a clear instruction (example: "please gather 3 dirt blocks").
+4. Verify execution trace:
+   - Call `get_logs(limit=10)` and check for:
+     - bot acknowledgement chat
+     - action tool feedback (for example `collectBlocks`)
+     - REPL result summary
+   - Call `get_llm_trace(limit=5)` when you need exact model output/reasoning for assertions.
+5. Re-check inventory using the same REPL snippet and compare against baseline.
+
+Use this workflow when validating behavior changes, tool wiring, or regressions in planning/execution loops.
@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Minecraft Debug MCP'
+  short_description: 'Operate the live Minecraft debug MCP bot safely'
+  default_prompt: 'Start the bot with pnpm dev, connect to the minecraft-debug MCP, inspect brain state/logs, and execute focused debug actions.'
@@ -0,0 +1,120 @@
+# Minecraft Debug MCP Surface
+
+Implementation source: `/path/to/project/root/integrations/minecraft/src/debug/mcp-repl-server.ts`.
+
+## Endpoint
+
+- Base server: `http://localhost:3001`
+- MCP endpoint: `http://localhost:3001/sse`
+- SSE fallback endpoint: `GET /sse` + `POST /messages`
+
+The bot starts this server during normal runtime from:
+- `/path/to/project/root/integrations/minecraft/src/cognitive/index.ts`
+
+## Resources
+
+- `brain://state`
+  - Summary state: processing, queue length, turn, give-up timer.
+- `brain://context`
+  - Current context view text.
+- `brain://history`
+  - Conversation history JSON.
+- `brain://logs`
+  - Latest LLM log entries JSON (last 50 in resource output).
+
+## Tools
+
+- `get_state()`
+  - Returns current REPL/brain state JSON.
+
+- `get_last_prompt()`
+  - Returns latest LLM input JSON.
+  - Returns error when no prompt exists yet.
+  - Compacted payload: omits `systemPrompt` and drops `messages` items with `role: "system"`.
+
+- `get_logs(limit?: number)`
+  - Returns recent LLM logs; start with small limits.
+
+- `get_llm_trace(limit?: number, turnId?: number)`
+  - Returns structured LLM trace entries captured per attempt.
+  - Includes: turn/source metadata, messages, generated content, reasoning (if available), token usage, and duration.
+  - Use `turnId` to isolate trace for one injected test event.
+  - Compacted payload: drops `messages` items with `role: "system"` to save tokens.
+
+- `execute_repl(code: string)`
+  - Executes debug REPL code in running brain context.
+  - Use for focused inspection/action only.
+  - Runtime global includes `forget_conversation()` for conversation-memory reset.
+
+- `inject_chat(username: string, message: string)`
+  - Injects a synthetic chat perception event.
+
+- `inject_event(type, payload, source)`
+  - `type`: `perception | feedback | world_update | system_alert`
+  - `source.type`: `minecraft | airi | system`
+  - `source.id`: string
+  - Use only with deliberate, test-specific payloads.
+
+## Troubleshooting
+
+- Connection refused:
+  - Ensure `pnpm dev` is running in the service directory.
+  - Confirm logs include `MCP REPL server running at http://localhost:3001`.
+- 404/invalid endpoint:
+  - Use `/sse` as MCP entrypoint.
+- Empty prompt/logs:
+  - Trigger activity first (for example via `inject_chat`) and retry `get_last_prompt` or `get_logs`.
+
+## Live-Tested Behavior Notes
+
+- `inject_chat` is not a passive write: it enters the normal cognition pipeline and can cause the bot to send chat/actions.
+- `get_last_prompt` may be very large (full system prompt + history); avoid repeated calls unless needed.
+- `get_last_prompt` is now MCP-compacted (no raw system prompt text), which makes it cheaper for automation checks.
+- `execute_repl` response includes metadata (`source`, `durationMs`, `actions`, `logs`) and a stringified `returnValue`.
+- Query runtime now has LLM-friendly shortcuts for deterministic reads:
+  - `query.self()`
+  - `query.inventory().count(name)`
+  - `query.inventory().has(name, atLeast?)`
+  - `query.inventory().summary()`
+  - `query.snapshot(range?)`
+- REPL runtime exposes a read-only `patterns` helper for known working recipes:
+  - `patterns.get(id)`
+  - `patterns.find(query, limit?)`
+  - `patterns.ids()`
+  - `patterns.list(limit?)`
+- Log verification pattern that worked reliably:
+  1. `inject_chat(...)`
+  2. `get_logs(limit: 10)`
+  3. Confirm sequence: `turn_input` -> `llm_attempt` -> `feedback` -> `repl_result`
+
+## Repeatable Smoke Test Recipe
+
+Use this exact sequence for fast live validation:
+
+1. Baseline
+   - `get_state()`
+   - `execute_repl("query.inventory().list().map(i => ({ name: i.name, count: i.count }))")`
+   - Optional clean slate:
+     - `execute_repl("forget_conversation()")`
+2. Task trigger
+   - `inject_chat({ username: \"codex-live-test\", message: \"please gather 3 dirt blocks\" })`
+3. Execution proof
+   - `get_logs({ limit: 10 })`
+   - Expect acknowledgement chat + `collectBlocks` success feedback + REPL summary.
+   - `get_llm_trace({ limit: 5 })`
+   - Assert expected LLM behavior (for example response code, or repeated `await skip()`).
+   - Assert trace payload does not include `role: "system"` entries.
+4. Outcome proof
+   - Run the same inventory `execute_repl` call again and compare item counts.
+
+## Prompt-Behavior Check (Value-First)
+
+To validate read->action behavior:
+1. Inject a query-style chat (for example inventory question).
+2. Confirm first REPL result is no-action with concrete return value (via `get_logs`/`get_llm_trace`).
+3. Confirm follow-up turn uses that returned value to perform chat/action.
+
+## Runtime Caveat
+
+- The degraded environment sentinel can appear only when context has not been refreshed yet.
+- With the current fix, `inject_chat` refreshes reflex context first, so this should not appear in normal MCP chat-injection tests.