From 48ad59b1cca8f0d1ce93b29e1e549209ee65b4d6 Mon Sep 17 00:00:00 2001 From: Rin Date: Sat, 7 Feb 2026 05:20:11 +0800 Subject: [PATCH] docs(minecraft): document query.self/snapshot helpers and remove degraded environment sentinel references Update SKILL.md and mcp-surface.md to recommend compact value reads (query.self/snapshot/inventory helpers), document query runtime shortcuts (self/count/has/summary/snapshot) in mcp-surface.md, add query.self/snapshot usage examples to brain-prompt.md composable patterns, remove degraded environment sentinel warnings now that inject_chat refreshes reflex context first --- .../codex-skills/minecraft-debug-mcp/SKILL.md | 6 +++++- .../minecraft-debug-mcp/references/mcp-surface.md | 11 +++++++++-- .../src/cognitive/conscious/prompts/brain-prompt.md | 7 ++++++- 3 files changed, 20 insertions(+), 4 deletions(-) diff --git a/services/minecraft/codex-skills/minecraft-debug-mcp/SKILL.md b/services/minecraft/codex-skills/minecraft-debug-mcp/SKILL.md index cbb032111..4e1201e4f 100644 --- a/services/minecraft/codex-skills/minecraft-debug-mcp/SKILL.md +++ b/services/minecraft/codex-skills/minecraft-debug-mcp/SKILL.md @@ -49,7 +49,11 @@ Read `references/mcp-surface.md` for exact tool/resource names and argument sche - `get_logs(limit=10)` is enough to verify whether an injected event reached planner/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. -- If environment summary shows `"SOMETHING WENT WRONG, YOU SHOULD NOTIFY THE USER OF THIS"`, treat it as degraded runtime context and avoid high-confidence world actions. +- 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. diff --git a/services/minecraft/codex-skills/minecraft-debug-mcp/references/mcp-surface.md b/services/minecraft/codex-skills/minecraft-debug-mcp/references/mcp-surface.md index ccebea414..d0523253a 100644 --- a/services/minecraft/codex-skills/minecraft-debug-mcp/references/mcp-surface.md +++ b/services/minecraft/codex-skills/minecraft-debug-mcp/references/mcp-surface.md @@ -71,6 +71,12 @@ The bot starts this server during normal runtime from: - `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?)` - Log verification pattern that worked reliably: 1. `inject_chat(...)` 2. `get_logs(limit: 10)` @@ -103,6 +109,7 @@ To validate read->action behavior: 2. Confirm first planner 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 Seen Live +## Runtime Caveat -- If a turn includes `Environment: SOMETHING WENT WRONG, YOU SHOULD NOTIFY THE USER OF THIS`, treat the world snapshot as degraded and avoid issuing risky autonomous actions until context stabilizes. +- 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. diff --git a/services/minecraft/src/cognitive/conscious/prompts/brain-prompt.md b/services/minecraft/src/cognitive/conscious/prompts/brain-prompt.md index 2c49e7477..6fbdafc81 100644 --- a/services/minecraft/src/cognitive/conscious/prompts/brain-prompt.md +++ b/services/minecraft/src/cognitive/conscious/prompts/brain-prompt.md @@ -51,17 +51,22 @@ You cannot make up tools. - Compose heuristic signals with chained filters, then act with tools. Core query entrypoints: +- `query.self()`: one-shot self snapshot (`pos`, `health`, `food`, `heldItem`, `gameMode`, `isRaining`, `timeOfDay`) +- `query.snapshot(range?)`: compact world snapshot (`self`, `inventory`, `nearby.blocks/entities/ores`) - `query.blocks()`: nearby block records with chain methods (`within`, `limit`, `isOre`, `whereName`, `sortByDistance`, `names`, `first`, `list`) - `query.blockAt({ x, y, z })`: single block snapshot at coordinate (or `null`) - `query.entities()`: nearby entities with chain methods (`within`, `limit`, `whereType`, `names`, `first`, `list`) -- `query.inventory()`: inventory stacks (`whereName`, `names`, `countByName`, `list`) +- `query.inventory()`: inventory stacks (`whereName`, `names`, `countByName`, `count`, `has`, `summary`, `list`) - `query.craftable()`: craftable item names (supports `uniq`, `whereIncludes`, `list`) Composable patterns: - `const ores = query.blocks().within(24).isOre().names().uniq().list()` +- `const me = query.self(); return me` +- `const snap = query.snapshot(20); return snap.inventory.summary` - `const nearestLog = query.blocks().whereName(["oak_log", "birch_log"]).first()` - `const nearbyPlayers = query.entities().whereType("player").within(32).list()` - `const inv = query.inventory().countByName(); const hasFood = (inv.bread ?? 0) > 0` +- `const hasPickaxe = query.inventory().has("stone_pickaxe", 1)` - `const craftableTools = query.craftable().whereIncludes("pickaxe").uniq().list()` Heuristic composition examples (encouraged):