菜单
Scaffold a provider abstraction layer for agent cognition with mock default, per-agent routing, secret-safe logging, failure hardening, and validation tests
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/vortsghost2025/Genesis-Kernel-First-Humans-World-Sim --skill provider-routing-scaffold命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | provider-routing-scaffold |
| description | Scaffold a provider abstraction layer for agent cognition with mock default, per-agent routing, secret-safe logging, failure hardening, and validation tests |
| source | auto-skill |
| extracted_at | 2026-05-30T05:22:10.682Z |
| updated_at | 2026-05-30T05:33:00.000Z |
When building agent-based simulations that will eventually use real LLM providers (NVIDIA NIM, OpenAI, etc.), scaffold the provider layer early with mock mode as the default. This keeps the project runnable without API keys while preparing the architecture for real integration.
backend/providers/
├── __init__.py
├── base.py # BaseProvider, MockProvider, NvidiaNimProvider, test providers
└── validation.py # ProviderOutputValidator, ProviderOutputQuarantine
base.py contains:
BaseProvider — abstract class with generate(prompt, agent, tick) -> strMockProvider — returns valid JSON {"thought": ..., "action": ...}, no external calls, default for developmentNvidiaNimProvider_real_mode = TrueProviderCallLog — structured call logger that records provider name, agent, tick, success, latency_ms — never logs API keys or auth headersProviderOutputQuarantine — quarantines invalid provider outputs to data/quarantine_provider_outputs.jsonlTest providers (Phase 1C):
FailingProvider — always raises RuntimeError, tests fallback behaviorMalformedProvider — returns invalid JSON, missing fields, empty, or null fieldsBoundaryViolatingProvider — tries to force CANON_ANCHOR without source_anchorEach agent gets a provider: BaseProvider field and a set_provider() method. The agent's decide() method uses _safe_generate():
def _safe_generate(self, prompt, world):
try:
raw_response = self.provider.generate(prompt, self.name, self.tick)
except Exception as e:
# Provider failed — fallback to safe mock
logger.warning("Provider %s failed for %s tick %s: %s", ...)
call_log.record(provider=..., agent=..., tick=..., success=False, error=...)
return self._mock_think_action(world) + (None, "Provider failed — fallback.")
# Validate output
parsed = validator.validate_and_parse(raw_response, self.provider.name, self.name, self.tick)
if parsed["valid"]:
return parsed["thought"], parsed["action"], parsed["label_suggestion"], parsed["simulation_note"]
# Output invalid — fallback
logger.warning("Provider %s returned invalid output: %s", ...)
return self._mock_think_action(world) + (None, f"Invalid output — fallback. Reason: {parsed['repair_reason']}")
Critical: Fallback actions must use generic language that avoids canon keywords (no "creature", "boundary", "command", "tree", "garden") to prevent accidental CANON_ANCHOR classification by the consequence engine.
providers/validation.py — ProviderOutputValidator:
thought and action fields — quarantine if missingCANON_ANCHOR without source_anchor — override to SIMULATION_EVENT + quarantinebackend/config.py — GenesisConfig dataclass with:
provider_mode: str — global mode ("mock", "nim-dry-run", "nim-live-disabled", "nim-live-adam-single"), default "mock"adam_provider: str, eve_provider: str — per-agent provider selectionadam_nim_model: str, eve_nim_model: str — per-agent NIM model selectionget_api_key(agent) — reads from env var, returns empty string if not set, never logs the keyget_agent_config(agent) — returns AgentProviderConfig with provider, model, key_envvalidate() — returns warnings (e.g., "NIM mode but key not set")from_env() — loads from os.environ with defaultsCritical: The _setup_providers() function must include ALL NIM modes in its condition, not just dry-run:
def _setup_providers() -> None:
adam_cfg = config.get_agent_config("Adam")
if adam_cfg.provider in ("nim-dry-run", "nim-live-disabled", "nim-live-adam-single"):
adam.set_provider(NvidiaNimProvider(
name="adam_nim",
api_key_env=config.nvidia_nim_key_adam_env,
model=config.adam_nim_model,
base_url=config.nvidia_nim_base_url,
mode=adam_cfg.provider,
))
else:
adam.set_provider(MockProvider(name="adam_mock"))
If you add a new NIM mode and forget to add it to this condition, the agent will silently fall back to mock — the live call will never happen.
.env.example — variable names only, no real values:
GENESIS_PROVIDER_MODE=mock
ADAM_PROVIDER=mock
EVE_PROVIDER=mock
NVIDIA_NIM_KEY_ADAM=
NVIDIA_NIM_KEY_EVE=
.gitignore — protect:
.env
.env.local
.env.production
*.key
*.pem
*.secret
secrets/
data/private/
Every generate() call logs:
Never log: API keys, auth headers, raw request/response bodies.
tests/test_provider_routing.py — Phase 1B:
tests/test_provider_failure.py — Phase 1C:
Add /api/providers endpoint returning:
GENESIS_PROVIDER_MODE=mock alwaysNvidiaNimProvider._real_mode = False means it returns mock responsesos.environ.get(), never hardcodedif not key: warn())