chore: narrow graphify scope

.gitignore

@@ -79,6 +79,8 @@ yarn-error.log*
 **/graphify-out/obsidian.meta
 **/graphify-out/graph.json
 **/graphify-out/converted/
+**/graphify-out/.graphify_python
+**/graphify-out/needs_update
 
 #Graphify保留文件（仅保留分析报告和元信息）
 !**/graphify-out/GRAPH_REPORT.md

.graphifyignore

@@ -0,0 +1,53 @@
+# TH1 graphify scope: keep the graph focused on business code, docs, and repo tools.
+
+# Graphify outputs
+graphify-out
+Unity/graphify-out
+
+# Unity generated/build state
+Library
+Logs
+Temp
+Obj
+Build
+Builds
+HybridCLRData
+StreamingAssets
+Bundles
+UserSettings
+WebGL
+
+# Unity package/vendor/runtime noise
+Unity/Assets/Plugins
+Unity/Assets/ThirdParty
+Unity/Assets/Steamworks.NET
+Unity/Assets/TextMesh Pro
+Unity/Assets/Settings
+Unity/Assets/Scenes
+Unity/Assets/Resources
+Unity/Assets/BundleResources
+Unity/Packages
+Unity/ProjectSettings
+
+# Generated or exported project data
+Unity/Assets/Scripts/TH1_Config/GenerateCS
+ExcelExport/Excel
+ExcelExport/bin
+ExcelExport/obj
+
+# Office/export tables generate graphify-out/converted sidecars and drown code signals.
+*.xlsx
+*.xls
+*.xlsm
+*.docx
+*.pptx
+*.csv
+
+# Repo-local auxiliary output
+DOC
+Docs
+Pack
+Publish
+Tools/MongoDB
+Tools/MultilingualBackups
+Tools/Dashboard/data

AGENTS.md

@@ -5,7 +5,7 @@ This repository is a Unity 2022.3 LTS / ET Framework turn-based strategy game. T
 ## First Reads
 
 - For architecture questions, read the `MD/GameMDFramework/00-*` overview document and the relevant subsystem document before editing.
-- For code navigation, read `Unity/graphify-out/GRAPH_REPORT.md` for Unity code and `graphify-out/GRAPH_REPORT.md` for whole-repository context.
+- For broad code navigation or unfamiliar subsystem discovery, optionally consult `Unity/graphify-out/GRAPH_REPORT.md` for Unity code and `graphify-out/GRAPH_REPORT.md` for whole-repository context. Treat Graphify as a secondary macro index; prefer `rg`, subsystem docs, and the relevant `.codex/skills` for ordinary bug fixes and focused edits.
 - If a task touches action execution, networking, localization, online errors, backend upload, or CrashSight reports, use the matching `.codex/skills/th1-*` skill first.
 - For severe incidents, postmortems, root-cause attribution, or requests to maintain an incident log, use `.codex/skills/th1-serious-incident` and update `MD/SeriousIncidentLog/index.md`.
 - For repeated defects, problems the user says happened again, or requests to 根治 / add to 癌症清单, use `.codex/skills/th1-chronic-issue` and update `MD/ChronicIssueList/index.md` before treating the issue as fixed.
@@ -55,14 +55,25 @@ This repository is a Unity 2022.3 LTS / ET Framework turn-based strategy game. T
 - There are two graphify scopes:
   - Root `graphify-out/`: whole repository overview.
   - `Unity/graphify-out/`: Unity client code overview.
+- Graphify is useful for macro navigation, cross-subsystem exploration, and onboarding a fresh agent into unfamiliar code. It is not the default source of truth for small edits, dependency safety, config inspection, or code review findings.
+- Graphify input scope is narrowed by `.graphifyignore` and `Unity/.graphifyignore` to keep generated code, Unity packages, export data, art/resource assets, and previous graph outputs out of the graph.
 - Large graphify files such as `graph.json`, `cache/`, `converted/`, and `obsidian/` are intentionally ignored. Commit only lightweight reports and metadata such as `GRAPH_REPORT.md`, `manifest.json`, and `cost.json`.
-- After code changes, the git `post-commit` hook runs `Tools/GraphifyPostCommit.ps1` in the background to refresh code graphs without LLM cost.
+- Graphify post-commit refresh is opt-in because full rebuilds are expensive on this repository. Set `GRAPHIFY_POST_COMMIT=1` in the shell before committing if you want the local post-commit hook to refresh graphs in the background.
+- The post-commit script only reacts to narrowed graph-worthy paths such as `Unity/Assets/Scripts/*`, selected repo tools, Graphify config files, and architecture docs. Architecture doc edits mark `graphify-out/needs_update` for a manual semantic update instead of running LLM extraction automatically.
 - To run the hook manually:
 
 ```powershell
 Tools/GraphifyPostCommit.ps1
 ```
 
+- To run an opt-in local post-commit refresh for one commit:
+
+```powershell
+$env:GRAPHIFY_POST_COMMIT = "1"
+git commit
+Remove-Item Env:\GRAPHIFY_POST_COMMIT
+```
+
 - To reinstall the local git hook after cloning or moving the repository:
 
 ```powershell

Tools/CommitTH1.ps1

@@ -41,10 +41,14 @@ $protectedPatterns = @(
     'Build/*',
     'Builds/*',
     'graphify-out/graph.json',
+    'graphify-out/.graphify_python',
+    'graphify-out/needs_update',
     'graphify-out/cache/*',
     'graphify-out/converted/*',
     'graphify-out/obsidian/*',
     'Unity/graphify-out/graph.json',
+    'Unity/graphify-out/.graphify_python',
+    'Unity/graphify-out/needs_update',
     'Unity/graphify-out/cache/*',
     'Unity/graphify-out/converted/*',
     'Unity/graphify-out/obsidian/*'

Tools/GitCheckpoint.ps1

@@ -53,10 +53,14 @@ $buildArtifactPatterns = @(
 
 $largeGraphifyPatterns = @(
     'graphify-out/graph.json',
+    'graphify-out/.graphify_python',
+    'graphify-out/needs_update',
     'graphify-out/cache/*',
     'graphify-out/converted/*',
     'graphify-out/obsidian/*',
     'Unity/graphify-out/graph.json',
+    'Unity/graphify-out/.graphify_python',
+    'Unity/graphify-out/needs_update',
     'Unity/graphify-out/cache/*',
     'Unity/graphify-out/converted/*',
     'Unity/graphify-out/obsidian/*'
@@ -94,7 +98,19 @@ if ($StagedOnly) {
 
 $advisoryGenerated = @($paths | Where-Object { Test-PathLike $_ $advisoryExportPatterns } | Sort-Object -Unique)
 $artifacts = @($paths | Where-Object { Test-PathLike $_ $buildArtifactPatterns } | Sort-Object -Unique)
-$graphifyLarge = @($paths | Where-Object { Test-PathLike $_ $largeGraphifyPatterns } | Sort-Object -Unique)
+$stagedDeletes = @(git diff --cached --name-status | Where-Object { $_ -match '^D\s+' } | ForEach-Object {
+    ($_ -replace '^D\s+', '') -replace '\\', '/'
+})
+$stagedDeleteSet = @{}
+foreach ($path in $stagedDeletes) {
+    $stagedDeleteSet[$path] = $true
+}
+$graphifyLarge = @($paths | Where-Object {
+    (Test-PathLike $_ $largeGraphifyPatterns) -and -not $stagedDeleteSet.ContainsKey($_)
+} | Sort-Object -Unique)
+$graphifyLargeDeletes = @($paths | Where-Object {
+    (Test-PathLike $_ $largeGraphifyPatterns) -and $stagedDeleteSet.ContainsKey($_)
+} | Sort-Object -Unique)
 
 $touchedScripts = @($paths | Where-Object { $_ -like 'Unity/Assets/Scripts/*' })
 $touchedAot = @($paths | Where-Object { $_ -like 'Unity/Assets/Scripts/*AOT*' -or $_ -like 'Unity/Assets/Scripts/*HybridCLR*' -or $_ -like 'Unity/Assets/Scripts/*YooAsset*' })
@@ -163,6 +179,10 @@ if ($graphifyLarge.Count -gt 0) {
     Write-Host "  WARNING: large graphify artifacts changed:"
     $graphifyLarge | ForEach-Object { Write-Host "    $_" }
 }
+if ($graphifyLargeDeletes.Count -gt 0) {
+    Write-Host "  NOTICE: large graphify artifacts are being removed from Git tracking:"
+    $graphifyLargeDeletes | ForEach-Object { Write-Host "    $_" }
+}
 if (-not $hasAdvisoryIssue -and -not $hasBlockingIssue) {
     Write-Host "  no generated/export or artifact paths detected"
 }

Tools/GraphifyPostCommit.ps1

@@ -90,6 +90,47 @@ function Get-ChangedFiles {
     }
 }
 
+function Test-GitPathLike {
+    param(
+        [string]$Path,
+        [string[]]$Patterns
+    )
+
+    foreach ($pattern in $Patterns) {
+        if ($Path -like $pattern) {
+            return $true
+        }
+    }
+    return $false
+}
+
+function Get-MatchingGitPaths {
+    param(
+        [string[]]$Paths,
+        [string[]]$Patterns
+    )
+
+    return @($Paths | Where-Object { Test-GitPathLike -Path $_ -Patterns $Patterns })
+}
+
+function Set-GraphifyNeedsUpdate {
+    param(
+        [string]$RelativePath,
+        [string]$Reason
+    )
+
+    $target = Join-Path $script:RepoRoot $RelativePath
+    $out = Join-Path $target "graphify-out"
+    if (-not (Test-Path $out)) {
+        return
+    }
+
+    $flag = Join-Path $out "needs_update"
+    $timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
+    Add-Content -Path $flag -Value "[$timestamp] $Reason" -Encoding UTF8
+    Write-HookLog "Marked $RelativePath graph for manual semantic update: $Reason"
+}
+
 function Invoke-GraphifyRebuild {
     param(
         [string]$Label,
@@ -129,17 +170,26 @@ function Invoke-GraphifyRebuild {
     }
 }
 
+function Invoke-HookMain {
 Set-Location $script:RepoRoot
 
-$changedFiles = @(Get-ChangedFiles)
+$changedFiles = @(
+    Get-ChangedFiles |
+        ForEach-Object { $_ -replace '\\', '/' } |
+        Where-Object {
+            -not [string]::IsNullOrWhiteSpace($_) -and
+            $_ -notlike "graphify-out/*" -and
+            $_ -notlike "Unity/graphify-out/*"
+        }
+)
 if ($changedFiles.Count -eq 0) {
     Write-HookLog "No changed files detected; nothing to rebuild."
-    exit 0
+    return 0
 }
 
 $codeExtensions = @(
     ".cs", ".asmdef", ".shader", ".hlsl", ".cginc",
-    ".py", ".js", ".ts", ".json", ".toml", ".yaml", ".yml"
+    ".py", ".js", ".ts", ".ps1", ".json", ".toml", ".yaml", ".yml"
 )
 
 $changedCode = @(
@@ -149,26 +199,105 @@ $changedCode = @(
     }
 )
 
-if ($changedCode.Count -eq 0) {
-    Write-HookLog "$($changedFiles.Count) changed file(s), but no code/config files for AST graph rebuild."
-    exit 0
+$rootCodePatterns = @(
+    "Unity/Assets/Scripts/*",
+    "Tools/*.ps1",
+    "Tools/*.py",
+    "Tools/*.js",
+    "Tools/OSS/*",
+    "Tools/Dashboard/*.py",
+    "ExcelExport/*"
+)
+
+$unityCodePatterns = @(
+    "Unity/Assets/Scripts/*"
+)
+
+$graphifyConfigPatterns = @(
+    ".graphifyignore",
+    ".gitignore",
+    "AGENTS.md",
+    "Unity/.graphifyignore",
+    "Tools/GraphifyPostCommit.ps1",
+    "Tools/InstallGraphifyHook.ps1"
+)
+
+$semanticDocPatterns = @(
+    "MD/GameMDFramework/*.md",
+    "MD/GameMDFramework/*/*.md"
+)
+
+$rootChangedCode = @(Get-MatchingGitPaths -Paths $changedCode -Patterns $rootCodePatterns)
+$unityChangedCode = @(Get-MatchingGitPaths -Paths $changedCode -Patterns $unityCodePatterns)
+$changedGraphifyConfig = @(Get-MatchingGitPaths -Paths $changedFiles -Patterns $graphifyConfigPatterns)
+$changedSemanticDocs = @(Get-MatchingGitPaths -Paths $changedFiles -Patterns $semanticDocPatterns)
+
+if ($changedSemanticDocs.Count -gt 0) {
+    Set-GraphifyNeedsUpdate -RelativePath "." -Reason "Architecture docs changed; run graphify update manually for semantic edges."
+}
+
+$shouldRebuildRoot = ($rootChangedCode.Count -gt 0 -or $changedGraphifyConfig.Count -gt 0)
+$shouldRebuildUnity = ($unityChangedCode.Count -gt 0 -or ($changedGraphifyConfig | Where-Object { $_ -eq "Unity/.graphifyignore" }).Count -gt 0)
+
+if (-not $shouldRebuildRoot -and -not $shouldRebuildUnity) {
+    Write-HookLog "$($changedFiles.Count) changed file(s), but none are in the narrowed graphify AST scopes."
+    return 0
 }
 
 $python = Get-GraphifyPython
 if (-not $python) {
     Write-HookLog "No Python interpreter with graphify installed was found."
-    exit 0
+    return 0
 }
 
-Write-HookLog "$($changedCode.Count) code/config file(s) changed; using Python: $python"
+Write-HookLog "$($changedFiles.Count) changed file(s); root scope: $($rootChangedCode.Count), Unity scope: $($unityChangedCode.Count), graphify config: $($changedGraphifyConfig.Count). Using Python: $python"
 
-$touchesUnity = @($changedCode | Where-Object { $_ -like "Unity/*" -or $_ -like "Unity\*" }).Count -gt 0
+if ($shouldRebuildRoot) {
+    Invoke-GraphifyRebuild -Label "root" -RelativePath "." -PythonPath $python
+}
+else {
+    Write-HookLog "Skipping root graph: no narrowed root-scope code/config changed."
+}
 
-Invoke-GraphifyRebuild -Label "root" -RelativePath "." -PythonPath $python
-
-if ($touchesUnity) {
+if ($shouldRebuildUnity) {
     Invoke-GraphifyRebuild -Label "Unity" -RelativePath "Unity" -PythonPath $python
 }
 else {
-    Write-HookLog "Skipping Unity graph: no Unity path changed."
+    Write-HookLog "Skipping Unity graph: no narrowed Unity-scope code/config changed."
+}
+
+return 0
+}
+
+$mutexName = "Local\TH1-GraphifyPostCommit"
+$mutex = $null
+$hasLock = $false
+
+try {
+    $mutex = [System.Threading.Mutex]::new($false, $mutexName)
+    $hasLock = $mutex.WaitOne(0)
+    if (-not $hasLock) {
+        Write-HookLog "Another graphify rebuild is already running; skipping this post-commit run."
+        exit 0
+    }
+
+    $exitCode = Invoke-HookMain
+    exit $exitCode
+}
+catch {
+    Write-HookLog "Graphify hook failed: $($_.Exception.Message)"
+    exit 1
+}
+finally {
+    if ($hasLock -and $mutex) {
+        try {
+            $mutex.ReleaseMutex() | Out-Null
+        }
+        catch {
+        }
+    }
+
+    if ($mutex) {
+        $mutex.Dispose()
+    }
 }

Tools/InstallGraphifyHook.ps1

@@ -16,6 +16,12 @@ if (-not (Test-Path $hooksDir)) {
 $hook = @'
 #!/bin/sh
 # Runs the repository-owned graphify post-commit updater.
+#
+# Graphify full rebuilds are expensive on this repo and can make the
+# workstation sluggish. Keep automatic post-commit rebuilds opt-in.
+if [ "$GRAPHIFY_POST_COMMIT" != "1" ]; then
+    exit 0
+fi
 
 REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
 CHANGED=$(git diff --name-only HEAD~1 HEAD 2>/dev/null || git diff --name-only HEAD 2>/dev/null)

Unity/.graphifyignore

@@ -0,0 +1,27 @@
+# Unity graphify scope: code navigation only.
+
+graphify-out
+Library
+Logs
+Temp
+Obj
+Build
+Builds
+HybridCLRData
+StreamingAssets
+Bundles
+UserSettings
+WebGL
+
+Assets/Plugins
+Assets/ThirdParty
+Assets/Steamworks.NET
+Assets/TextMesh Pro
+Assets/Settings
+Assets/Scenes
+Assets/Resources
+Assets/BundleResources
+Packages
+ProjectSettings
+
+Assets/Scripts/TH1_Config/GenerateCS

Unity/graphify-out/.graphify_python

@@ -1 +0,0 @@
-C:\Users\daixiawu\AppData\Local\Programs\Python\Python312\python.exe