wip deepseek

WIP.md

@@ -133,6 +133,42 @@ Reasoning:
 - A custom line format would be easier for a trivial parser but would become fragile once nested data is needed.
 - The app can tolerate partial or missing JSON by logging validation issues instead of failing the whole analysis.
 
+### Knowledge Architecture Decisions (2026-07-07)
+
+We conducted a `/grilling` session (via `/domain-modeling` skill) to address the growing split between prompt knowledge and validation knowledge.
+
+**Recognised problems:**
+
+- Prompt knowledge lives in `BuildDefaultSystemPrompt()` as large hardcoded strings.
+- Validation knowledge lives in `AIAnalysisValidation.cs` as hardcoded string matching (`claimLooksLikeBuilder` checks `"MCV"`, `"基地车"`, `"Nanocore"` etc.).
+- The two are not synchronised — adding a unit type requires editing both places.
+- Users can only override the entire system prompt or append text.
+
+**Decisions reached (recorded in ADR 0002):**
+
+1. **KnowledgeSet as the single source of truth.** Game knowledge is organised into named KnowledgeSets keyed by mod (e.g., `"default"`, `"corona"`). Each set is self-contained and complete — no cross-set inheritance or conditional sharing. The mod name from the replay directly selects which set to load, replacing the current `[MOD:]` inline tag system.
+
+2. **KnowledgeEntry is the unified format.** Every entry has an `id`, `tags[]`, and `text` (markdown). Same format for built-in and user-supplied entries — no separate internal/external format.
+
+3. **Predefined finite tag taxonomy.** Tags are the bridge between prompt knowledge and validation. Three categories: capability (`builder`, `pack`, `unpack`, `amphibious`, `returnToProducer`, ...), type (`infantry`, `vehicle`, `aircraft`, `naval`, `structure`, ...), combat role (`antiInfantry`, `antiVehicle`, `antiAir`, ...), plus `specialPower:*` references. No ad-hoc tags.
+
+4. **Prompt rendering order:** global entries → faction entries (per player) → map entries. User `AdditionalRules` appended at the end.
+
+5. **Validation consumes tags instead of hardcoded strings.** Validators query `entries.WithTag("builder")` instead of `claim.IndexOf("MCV") >= 0`.
+
+6. **User extensibility via JSON.** User knowledge file (`AnotherReplayReader.user_knowledge.json`) overlays built-in entries by matching `id`. No code changes needed to add map/faction/mod knowledge.
+
+7. **Storage format:** JSON container with markdown text in `text` fields. The existing `AiPromptSettings` text fields remain as a simpler escape hatch.
+
+**Refinement — mods are independent complete sets:** Initially the ADR described mod knowledge sets as "overlaying or extending" the base set. After further discussion, this was corrected: each mod is a self-contained game version with its own complete knowledge set. There is no `[MOD:]`-style conditional sharing because:
+- Users editing a mod's JSON should see only that mod's entries, not conditional inclusion logic.
+- The replays already identify the mod; loading the right set is a simple name lookup.
+- Duplication between mod sets is acceptable for clarity — the deduplication cost of `[MOD:]` tags is not worth it in a structured data format.
+
+**Reversal from earlier statement:** The user noted that mods are game versions and should not be a separate scope dimension. This was accepted: the mod selects which KnowledgeSet to load, and within a set only `global`, `faction`, and `map` scopes exist.
+
+**Reversal from earlier assumption:** I (the agent) initially claimed that Z-coordinate rules were duplicated across faction sections. After re-reading the full prompt, the user was correct — Z rules are in the `generalDescriptions` (global) section only. No duplication.
+
 ### Evidence Format Decision (2026-07-06)
 
 We decided to move from free-form evidence text to a **structured pipe-delimited format**:
@@ -324,7 +360,50 @@ Build status:
 - `dotnet build AnotherReplayReader.csproj --no-restore` succeeds.
 - Remaining warnings are existing nullable warnings in `AIAnalyze.cs` stream response handling and a `System.Text.Encoding.CodePages` support warning for `net461`.
 
-## Open Questions
+## Current Progress (continued)
+
+This session (2026-07-07 knowledge architecture grilling):
+
+- Conducted `/grilling` session via `/domain-modeling` skill to analyse knowledge split between prompt and validation.
+- Reached consensus on knowledge architecture (see "Knowledge Architecture Decisions" above, recorded in ADR 0002):
+  - KnowledgeSet as single source of truth, keyed by mod.
+  - KnowledgeEntry as unified format (id + tags + text), scope inherited from path.
+  - Predefined finite tag taxonomy (capability, type, combat role, specialPower:*).
+  - Prompt rendering order: global → factions → map.
+  - Validation consumes tags instead of hardcoded string matching.
+  - User extensibility via JSON overlay file.
+  - Storage: JSON container with markdown text.
+- Updated CONTEXT.md glossary with refined KnowledgeScope, plus new KnowledgeSet, KnowledgeEntry, and KnowledgeTag terms.
+- Created ADR 0002 documenting the structured game knowledge decision.
+- Updated WIP.md with discussion notes and migration plan.
+- **Wrote `tools/expand_knowledge.py`** — Python script that extracts the 5 `@""` knowledge strings from `AIAnalyze.cs`, expands all `[MOD:]` / `[MOD:NO:]` tags (both line-level and inline), and outputs per-mod knowledge files.
+- **Generated `knowledge_default.md`** (732 lines, 22427 chars) — base game knowledge with `[MOD:CORONA]` content stripped, `[MOD:NO:CORONA]` content retained.
+- **Generated `knowledge_corona.md`** (743 lines, 23177 chars) — Corona mod knowledge with `[MOD:CORONA]` content retained, `[MOD:NO:CORONA]` content stripped.
+- Verified all 27 `[MOD:]` tag locations across all content sections; confirmed correct expansion for line-level tags, inline tags, and double consecutive inline tags.
+- **Created `Utils/AiKnowledge.cs`** with core data types:
+  - `KnowledgeTag` — static class with predefined tag constants (capability, type, combat role, `SpecialPower()` helper).
+  - `KnowledgeScope` / `KnowledgeScopeKind` — scope identification (global, faction, map).
+  - `KnowledgeEntry` — record with `Id`, `Tags[]`, `Text`; query methods `HasTag()`, `HasAnyTag()`.
+  - `KnowledgeSet` — collection with `ByScope()`, `ByTag()`, `ByAnyTag()` queries, `RenderAsPrompt()` rendering, and `ForMod()`/`ForReplay()` factory methods that load from `knowledge_{mod}.md` files.
+- **Updated `AIAnalyze.GetSystemPrompt()`** — tries `KnowledgeSet.ForMod()` with file-based loading first, falls back to legacy `BuildDefaultSystemPrompt()` if file not found.
+- **Updated `AnotherReplayReader.csproj`** — added `knowledge_*.md` as `<Content>` with `CopyToOutputDirectory=PreserveNewest`.
+- Build verified: `dotnet build AnotherReplayReader.csproj --no-restore` succeeds (5 pre-existing nullable warnings).
+- **Created `knowledge_units.json`** — structured JSON knowledge for 盟军 (20 units, 8 buildings), each with assetName, tags, specialPowers, producedBy, and text. First pilot faction.
+- **Added `UnitKnowledge`/`BuildingKnowledge` records** + `StructuredKnowledge` class to `AiKnowledge.cs` — lazy-loaded singleton, queries by tag, special power, and asset name.
+- **Updated `ValidateTimelineConsistency()`** — `claimLooksLikeBuilder` now queries `StructuredKnowledge.Instance.UnitsWithTag("builder")` first, falls back to heuristic string matching.
+- Added `knowledge_units.json` to `.csproj` as `<Content>`.
+- **Merged `UnitKnowledge`/`BuildingKnowledge` → `EntityKnowledge`** — unified record with nullable `Tier` and `IsBuilding`/`IsUnit` helpers via tag check.
+- **Added `SpecialPowerInfo`** record (`Name` + `Description`) — special powers now carry descriptions for prompt rendering.
+- **`knowledge_units.json` format 1.1** — `specialPowers` changed from string array to `[{name, description}]`; `text` de-duplicated (no longer repeats assetName, displayName, specialPowers, producedBy); `produces` field removed (production type expressed via tags); corrected tag semantics (removed `naval` from amphibious land units).
+- **Structured field-based rendering** — units now render as multi-line entries with explicit `类型`/`技能`/`生产`/`描述` fields instead of dumping raw `text`. Buildings render as `displayName(assetName): text`. Added `TagDisplayName()` helper for Chinese tag labels.
+- **Refined tag taxonomy** — split type tags from capability/role tags; fixed misapplied `naval` tag on AlliedMiner, AlliedMCV, 激流ACV (these are amphibious vehicles, not naval vessels).
+
+## Resolved Open Questions
+
+- "How much game-unit knowledge should live in code versus prompt text?" — **Resolved by ADR 0002.** Knowledge lives in KnowledgeSets (structured data), not in code strings or prompt text. Code renders it to prompt; validation queries it by tag.
+- "Should the first verifier use hardcoded RA3/Corona knowledge, or should it load a small unit capability table from data files?" — **Resolved by ADR 0002.** The first verifier uses the same KnowledgeSet as the prompt builder, queried by tag.
+
+## Remaining Open Questions
 
 - Should AI natural-language output continue streaming live, or should content be buffered until validation and possible revision are complete?
 - Should reasoning chunks remain visible during hidden revision, or should only final content be shown?
@@ -332,9 +411,6 @@ Build status:
   - Current behavior: warning log only.
   - Possible future behavior: one hidden repair request asking the model to append valid claims.
 - Should validation issues be visible by default, or only in an advanced/debug foldout?
-- How much game-unit knowledge should live in code versus prompt text?
-- Should the first verifier use hardcoded RA3/Corona knowledge, or should it load a small unit capability table from data files?
-- How should free-form evidence strings be programmatically validated? (See "Known Limitation" above.)
 
 ## Suggested Next Steps
 
@@ -345,6 +421,18 @@ Build status:
    - ✅ UnitId used as builder — done (builder consistency check in `ValidateTimelineConsistency`).
    - ✅ special power contradictions — done (special power verification in `ValidateTimelineConsistency`).
    - ⬜ first production time vs first operation time — needs game knowledge of unit type names (e.g., "which names are bombers").
-3. Decide whether to buffer per-segment content before display.
-4. Add one hidden revision pass for `Contradiction` issues.
-5. Add validation summary UI, such as "验证器发现并修正 N 个问题".
+3. ✅ **Knowledge migration** — implement the KnowledgeSet/KnowledgeEntry model planned in ADR 0002:
+   - ✅ Extract built-in knowledge from `BuildDefaultSystemPrompt()` strings into mod-specific text files (`knowledge_default.md`, `knowledge_corona.md`). `[MOD:]` tags expanded by `tools/expand_knowledge.py`.
+   - ✅ Define C# records (`KnowledgeSet`, `KnowledgeEntry`, `KnowledgeScope`, `KnowledgeTag` constants) in `Utils/AiKnowledge.cs`.
+   - ✅ Wire `KnowledgeSet.ForReplay()` / `ForMod()` into `AIAnalyze.GetSystemPrompt()` — loads `knowledge_{mod}.md` at runtime if available, falls back to legacy `BuildDefaultSystemPrompt()`.
+   - ✅ Added `knowledge_*.md` as `<Content>` in `.csproj` with `CopyToOutputDirectory=PreserveNewest`.
+   - ✅ **Step 3: Structured data participates in rendering.** `KnowledgeSet.ForMod()` now merges flat text (`knowledge_*.md`) with structured entries (`knowledge_units.json`). Unit/building sections are automatically stripped from flat text (via `StripUnitSections()`) and replaced by structured entries rendered by tier. `RenderAsPrompt()` outputs both clean global text and structured faction entries in correct order.
+   - ✅ **Step 2: More validation rules migrated.** `ClaimLooksLikeBuilder()` now queries `StructuredKnowledge.Instance.UnitsWithTag("builder")` first; falls back to heuristic string matching if structured data is unavailable.
+   - ✅ **Step 1: Pilot faction (盟军) in `knowledge_units.json`.** 20 units + 8 buildings with assetName, tags, specialPowers, producedBy. Includes `aliases` support for multi-source units (e.g., 激流ACV).
+   - ✅ **EntityKnowledge unification.** `UnitKnowledge`/`BuildingKnowledge` merged into single `EntityKnowledge` record; `SpecialPowerInfo` added for name+description pairs.
+   - ✅ **JSON format 1.1.** `specialPowers` → object array with `name`/`description`; `text` de-duplicated; `produces` removed; tag semantics corrected.
+   - ✅ **Field-based structured rendering.** Units render with `类型`/`技能`/`生产`/`描述` fields; `TagDisplayName()` maps tags to Chinese labels.
+   - ⬜ Add user knowledge JSON file loading in `AiSettings.Load()`.
+4. Decide whether to buffer per-segment content before display.
+5. Add one hidden revision pass for `Contradiction` issues.
+6. Add validation summary UI, such as "验证器发现并修正 N 个问题".