wyuc 550c43a3f3
fix(generation): unify languageDirective across outline + scene pipeline (#472) (#474)
* fix(generation): unify languageDirective across outline + scene pipeline (#472)

Root issue: languageDirective was dropped, renamed, or hardcoded at several
points in the scene-generation pipeline, silently degrading prompt-level
language control. Slide paths survived because their fallback happened to
hint requirement-language; widget paths degraded to zh-CN default.

Fix plan (all code-only threading + prompt hygiene, no schema changes):

1. Thread languageDirective through every buildPrompt in scene-generator.ts:
   - Add param to generateSlideContent / generateQuizContent / generatePBLSceneContent
   - Forward from generateSceneContent's slide / quiz / pbl branches
   - Include key in the four generateSceneActions buildPrompt calls
   - Demote generatePBLSceneContent's hardcoded English to a fallback
   - Drop the dishonest `as 'zh-CN' | 'en-US'` cast on the widget path

2. Unify variable naming across widget templates + callers:
   - Rename {{language}} → {{languageDirective}} in 6 widget templates
     (simulation / diagram / code / game / visualization3d / widget-teacher-actions)
   - generateWidgetContent and generateWidgetTeacherActions now pass
     `languageDirective: languageDirective || ''` instead of a locale-code shim

3. Make the outline LLM reliably emit the wrapper object:
   - requirements-to-outlines/system.md + user.md restructured so the
     "top-level JSON object with languageDirective + outlines" contract is
     surfaced up-front, short, and unambiguous — drowning-by-scene-examples
     removed. Important Reminders reordered: top-level shape first.
   - interactive-outlines/system.md + user.md aligned with main outliner:
     adds full Language Inference section, requires wrapper output, drops
     the orphan {{language}} placeholder that never had a value source.

4. Remove lib/prompts/loader.ts prompt/snippet caches:
   - Disk reads for prompt templates are not on any hot path (LLM call
     dominates by 5 orders of magnitude). The cache's only observable
     effect was blocking prompt edits from taking effect without restart
     — which masked the wrapper bug during this investigation.

Verification:
- 7 new regression tests in tests/generation cover directive threading at
  each buildPrompt site plus the PBL caller-forwarding guarantee.
- outline-language eval (50 scenarios, gemini-3-flash-preview inference,
  qwen-3.5-flash judge): 48/50 (96%). The 2 persistent failures are in
  the proxy-request category (teacher / tutor preparing lessons for
  students) where the system prompt's rule 5 has genuine ambiguity —
  orthogonal to this fix.
- Curl burst tests: 8/8 runs each for regular-mode and interactive-mode
  outline endpoints emit the wrapper object and extract a detailed
  inferred directive.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* style: apply prettier formatting to loader.ts and new test file

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: thread languageDirective in scene-builder and classroom-generation

Code review caught two additional sites missing the directive:
- lib/server/classroom-generation.ts:371 — generateSceneActions call
  was missing languageDirective, reproducing the issue #472 symptom
  in the shareable-classroom server generation path.
- lib/generation/scene-builder.ts:114 — buildSceneFromOutline's
  generateSceneActions call had the same miss; latent (no current
  live caller) but wrong for consistency.

Also renumber duplicate `8.` in requirements-to-outlines/system.md
scene-level rules.

Extend regression tests with a buildSceneFromOutline end-to-end case
that captures both the content and actions prompts via a stub aiCall
and asserts the directive reaches both phases — this would have
caught the scene-builder miss.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* review: widget-path test + docs + fallback constant (PR #474)

Address @cosarah's review feedback:

- Add widget-path regression test (tests/generation/...): interactive
  scene with widgetType=simulation captures both widget content and
  widget-teacher-actions prompts, asserts the directive reaches each
  and no `{{language}}` / `{{languageDirective}}` placeholder leaks.
  This is exactly the path issue #472 was filed for.

- Rewrite lib/prompts/README.md "Caching" section: the cache was
  removed in this PR; README still instructed callers to use a
  clearPromptCache() function that no longer exists.

- Sync interactive-outlines/user.md with the main outliner's
  "## Language Context" reminder block (line 13-19) so both outline
  paths give the LLM the same language-inference reminders.

- Hoist 'Teach in the language that matches the user requirement.'
  into DEFAULT_LANGUAGE_DIRECTIVE, exported from outline-generator.
  Replaces 4 copies across outline-generator, scene-generator, and
  the scene-outlines-stream route.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-23 23:00:06 +08:00
..