ADR 0001: Hidden Revision Pass for AI Analysis

⚠️ 已归档（2026-08-21）：本文是历史决策记录，其中的“实现状态”已过时；当前实现以代码和 PLAN_ai_analysis_v2.md 为准，正文不再更新。

Date: 2026-07-06

Status

Proposed

Context

The AI analysis feature sends player operation logs to an LLM and displays the analysis in AIChatPanel. LLM output is inherently unreliable — the model may make contradictory claims, use incorrect game knowledge, or miss alternative interpretations.

We considered several approaches to handle problematic output:

Show raw output, let the user judge. Simplest, but puts the burden on the user to spot errors.
Show a corrected version alongside the original. Transparent, but confusing — two competing analyses.
Reject the entire segment and retry from scratch. Wastes the prior reasoning; may produce similar mistakes.
Hidden revision pass: Send the draft, validation issues, and replay facts back to the AI, asking for a clean corrected version without apology text.

We chose option 4 because:

The user sees only one coherent analysis.
Prior reasoning is preserved and refined, not discarded.
The user is not exposed to "sorry, my previous answer was wrong" chatter.

Decision

Implement a hidden revision pass for segments that have Contradiction or Fatal validation issues.
The revision prompt includes: the original draft, the list of validation issues (with severity and kind), and relevant replay facts for the affected claims.
The model is instructed to output a clean corrected analysis (natural language + machine-readable claims) without acknowledging the revision.
Limit to one revision pass per segment to avoid infinite loops.
If the revision still has Fatal issues, fall back to displaying the original with a warning.
Per-segment content is buffered during validation — the user sees the final content only after validation and optional revision complete.

Consequences

Positive: User sees a single, cleaner analysis.
Positive: Prior reasoning is reused, saving tokens vs. re-analyzing from scratch.
Negative: Adds latency (one extra round trip) for segments that need revision.
Negative: Increases token usage for revised segments (draft + revision prompt + corrected output).
Negative: Hidden correction may reduce user trust if they discover it — consider a subtle indicator like "验证器发现并修正 N 个问题".

Implementation Status

Not yet implemented. Validation issues are detected and logged in AIChatPanel, but no automatic revision pass is triggered. The revision prompt construction and retry orchestration still need to be wired in.

2.7 KiB Raw Blame History