Back to Details

doppler-debug

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

DOPPLER Debug Skill

DOPPLER 调试技能

Use this skill when generation fails, outputs drift, or Node/browser parity breaks. Use this skill with 
doppler-bench
when investigating performance regressions.
当生成失败、输出偏移或Node/browser一致性被破坏时，可使用该技能。在调查性能回归问题时，可结合
doppler-bench
使用本技能。

Mandatory Style Guides

强制遵循的风格指南

Read these before non-trivial debug-flow, parity, or harness-contract changes:
  • docs/style/general-style-guide.md
  • docs/style/javascript-style-guide.md
  • docs/style/config-style-guide.md
  • docs/style/command-interface-design-guide.md
  • docs/style/harness-style-guide.md
在进行非琐碎的调试流程、一致性或测试框架契约修改前，请阅读以下内容：
  • docs/style/general-style-guide.md
  • docs/style/javascript-style-guide.md
  • docs/style/config-style-guide.md
  • docs/style/command-interface-design-guide.md
  • docs/style/harness-style-guide.md

Developer Guide Routing

开发者指南导航

When debugging turns into extension work, also open:
  • docs/developer-guides/README.md
Common routes:
  • new manifest/runtime knob or missing contract field: 
    docs/developer-guides/07-manifest-runtime-field.md
  • command-surface parity fix that becomes a new command or contract surface: 
    docs/developer-guides/12-command-surface.md
  • missing kernel or runtime path: 
    docs/developer-guides/11-wgsl-kernel.md
  • attention-path bug that requires a new implementation: 
    docs/developer-guides/13-attention-variant.md
  • cache/layout bug that requires a new layout strategy: 
    docs/developer-guides/15-kvcache-layout.md
  • family-level onboarding gap: 
    docs/developer-guides/composite-model-family.md
    or 
    docs/developer-guides/composite-pipeline-family.md
当调试工作拓展为功能扩展时，还需打开：
  • docs/developer-guides/README.md
常见场景对应的指南：
  • 新增清单/运行时控制项或缺少契约字段：
    docs/developer-guides/07-manifest-runtime-field.md
  • 需要新增命令或契约接口的命令面一致性修复：
    docs/developer-guides/12-command-surface.md
  • 缺少内核或运行时路径：
    docs/developer-guides/11-wgsl-kernel.md
  • 需要新实现的注意力路径bug：
    docs/developer-guides/13-attention-variant.md
  • 需要新布局策略的缓存/布局bug：
    docs/developer-guides/15-kvcache-layout.md
  • 模型族/流水线族的入门文档缺失：
    docs/developer-guides/composite-model-family.md
    或 
    docs/developer-guides/composite-pipeline-family.md

Execution Plane Contract

执行平面契约

  • Contract and tunables are declared in JSON (
    runtime
    + harness contract); do not substitute behavior in-place.
  • JS coordinates deterministic execution: resolve/validate config, dispatch pipelines, and collect artifacts.
  • WGSL executes resolved kernels; any policy branch belongs to config/rule selection before dispatch.
  • For parity checks, command intent must match: unknown/mismatched intent is a failure, not an alternate path.
  • 契约和可调参数通过JSON声明（
    runtime
    + 测试框架契约）；请勿直接替换现有行为。
  • JS负责协调确定性执行：解析/验证配置、调度流水线、收集工件。
  • WGSL执行已解析的内核；任何策略分支都应在调度前的配置/规则选择阶段完成。
  • 进行一致性检查时，命令意图必须匹配：未知/不匹配的意图视为失败，而非备选路径。

Fast Triage

快速诊断

bash
undefined
bash
undefined

Primary debug run (auto surface = node-first transport; browser fallback only when node transport is unavailable)

主要调试运行（自动选择执行面 = 优先Node传输；仅当Node传输不可用时才回退到浏览器）

npm run debug -- --config '{"request":{"modelId":"MODEL_ID","runtimePreset":"modes/debug"},"run":{"surface":"auto"}}' --json
npm run debug -- --config '{"request":{"modelId":"MODEL_ID","runtimePreset":"modes/debug"},"run":{"surface":"auto"}}' --json

Verify pass/fail with inference suite

用推理套件验证结果是否通过

npm run verify:model -- --config '{"request":{"suite":"inference","modelId":"MODEL_ID","runtimePreset":"modes/debug"},"run":{"surface":"auto"}}' --json
npm run verify:model -- --config '{"request":{"suite":"inference","modelId":"MODEL_ID","runtimePreset":"modes/debug"},"run":{"surface":"auto"}}' --json

Force browser relay for mobile/WebGPU parity checks

强制使用浏览器中继以进行移动/WebGPU一致性检查

npm run debug -- --config '{"request":{"modelId":"MODEL_ID","runtimePreset":"diagnostics/debug-logits"},"run":{"surface":"browser","browser":{"channel":"chrome","console":true}}}' --json
undefined
npm run debug -- --config '{"request":{"modelId":"MODEL_ID","runtimePreset":"diagnostics/debug-logits"},"run":{"surface":"browser","browser":{"channel":"chrome","console":true}}}' --json
undefined

Runtime Overrides (Config-First)

运行时覆盖（配置优先）

Use runtime JSON patches instead of ad-hoc flags:
bash
npm run debug -- \
  --config '{"request":{"modelId":"MODEL_ID"},"run":{"surface":"auto"}}' \
  --runtime-config '{"shared":{"tooling":{"intent":"investigate"},"debug":{"trace":{"enabled":true,"categories":["attn","ffn"],"maxDecodeSteps":2}}},"inference":{"batching":{"maxTokens":8},"sampling":{"temperature":0}}}' \
  --json
使用运行时JSON补丁而非临时标志：
bash
npm run debug -- \
  --config '{"request":{"modelId":"MODEL_ID"},"run":{"surface":"auto"}}' \
  --runtime-config '{"shared":{"tooling":{"intent":"investigate"},"debug":{"trace":{"enabled":true,"categories":["attn","ffn"],"maxDecodeSteps":2}}},"inference":{"batching":{"maxTokens":8},"sampling":{"temperature":0}}}' \
  --json

Perf-Focused Investigation

性能聚焦的调查

bash
undefined
bash
undefined

Investigate-mode profile run (trace/profiler enabled by preset)

调查模式性能分析运行（预设已启用追踪/性能分析器）

npm run debug -- --config '{"request":{"modelId":"MODEL_ID","runtimePreset":"experiments/gemma3-profile"},"run":{"surface":"auto"}}' --json
npm run debug -- --config '{"request":{"modelId":"MODEL_ID","runtimePreset":"experiments/gemma3-profile"},"run":{"surface":"auto"}}' --json

Fast readback sensitivity checks

快速回读敏感度检查

npm run bench -- --config '{"request":{"modelId":"MODEL_ID","runtimePreset":"experiments/gemma3-investigate-readback-r1","cacheMode":"warm"},"run":{"surface":"browser"}}' --json npm run bench -- --config '{"request":{"modelId":"MODEL_ID","runtimePreset":"experiments/gemma3-investigate-readback-r8","cacheMode":"warm"},"run":{"surface":"browser"}}' --json
npm run bench -- --config '{"request":{"modelId":"MODEL_ID","runtimePreset":"experiments/gemma3-investigate-readback-r1","cacheMode":"warm"},"run":{"surface":"browser"}}' --json npm run bench -- --config '{"request":{"modelId":"MODEL_ID","runtimePreset":"experiments/gemma3-investigate-readback-r8","cacheMode":"warm"},"run":{"surface":"browser"}}' --json

Direct override for decode cadence tuning

直接覆盖解码节奏调优参数

npm run bench --
--config '{"request":{"modelId":"MODEL_ID","cacheMode":"warm"},"run":{"surface":"browser"}}'
--runtime-config '{"shared":{"tooling":{"intent":"investigate"}},"inference":{"batching":{"batchSize":4,"readbackInterval":4,"stopCheckMode":"per-token","maxTokens":128},"sampling":{"temperature":0}}}'
--json

Notes:
- `runtime.shared.tooling.intent="calibrate"` forbids trace/profiler instrumentation.
- Set `runtime.shared.tooling.intent="investigate"` for profiling/tracing runs.
npm run bench --
--config '{"request":{"modelId":"MODEL_ID","cacheMode":"warm"},"run":{"surface":"browser"}}'
--runtime-config '{"shared":{"tooling":{"intent":"investigate"}},"inference":{"batching":{"batchSize":4,"readbackInterval":4,"stopCheckMode":"per-token","maxTokens":128},"sampling":{"temperature":0}}}'
--json

注意事项：
- `runtime.shared.tooling.intent="calibrate"` 会禁用追踪/性能分析器 instrumentation。
- 进行性能分析/追踪运行时，请设置`runtime.shared.tooling.intent="investigate"`。

Cache and Surface Control

缓存与执行面控制

bash
undefined
bash
undefined

Cold browser run (wipe OPFS cache before launch)

浏览器冷启动运行（启动前清空OPFS缓存）

npm run debug -- --config '{"request":{"modelId":"MODEL_ID","cacheMode":"cold"},"run":{"surface":"browser"}}' --json
npm run debug -- --config '{"request":{"modelId":"MODEL_ID","cacheMode":"cold"},"run":{"surface":"browser"}}' --json

Warm browser run (reuse OPFS cache)

浏览器热启动运行（复用OPFS缓存）

npm run debug -- --config '{"request":{"modelId":"MODEL_ID","cacheMode":"warm"},"run":{"surface":"browser"}}' --json
undefined
npm run debug -- --config '{"request":{"modelId":"MODEL_ID","cacheMode":"warm"},"run":{"surface":"browser"}}' --json
undefined

What to Inspect in Results

结果中需检查的内容

  • result.metrics.modelLoadMs
    , 
    result.metrics.firstTokenMs
  • result.metrics.prefillTokensPerSecTtft
    (preferred) and 
    result.metrics.prefillTokensPerSec
  • result.metrics.decodeTokensPerSec
  • result.metrics.gpu
    (if available)
  • result.memoryStats
  • result.deviceInfo
  • result.reportInfo
    (report backend/path)
  • result.metrics.modelLoadMs
    、
    result.metrics.firstTokenMs
  • result.metrics.prefillTokensPerSecTtft
    （首选指标）和
    result.metrics.prefillTokensPerSec
  • result.metrics.decodeTokensPerSec
  • result.metrics.gpu
    （若可用）
  • result.memoryStats
  • result.deviceInfo
  • result.reportInfo
    （报告后端/路径）

Canonical Files

核心文件

  • tools/doppler-cli.js
  • src/tooling/command-api.js
  • src/tooling/node-command-runner.js
  • src/tooling/node-browser-command-runner.js
  • src/inference/browser-harness.js
  • src/config/presets/runtime/modes/debug.json
  • docs/developer-guides/README.md
  • tools/doppler-cli.js
  • src/tooling/command-api.js
  • src/tooling/node-command-runner.js
  • src/tooling/node-browser-command-runner.js
  • src/inference/browser-harness.js
  • src/config/presets/runtime/modes/debug.json
  • docs/developer-guides/README.md

Related Skills

相关技能

  • doppler-bench
    for perf regression quantification
  • doppler-convert
    when conversion integrity is suspected
  • doppler-bench
    ：用于量化性能回归
  • doppler-convert
    ：当怀疑转换完整性有问题时使用