From d52bf1034a6921d968a5fab2c75a376e681f837c Mon Sep 17 00:00:00 2001 From: Soar Qin Date: Sun, 11 Oct 2026 03:10:50 +0800 Subject: [PATCH] docs: clarify agent guidance and release documentation rules --- AGENTS.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7f8893b..2422446 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,8 +2,11 @@ ## Rules -- Update `AGENTS.md` after each task by editing current guidance directly. Keep only project standards and durable architecture references; do not retain investigation evidence, task histories, completed plans, or implementation snapshots. -- Write documentation and code comments in English, except for the Chinese sections of bilingual changelogs. +- Keep `AGENTS.md` concise: record important project standards, recurring pitfalls, and short durable architecture references. Add guidance only when useful for future work; omit details that can be read directly from code. +- Keep investigation evidence, work history, completed plans, and implementation snapshots out of `AGENTS.md`. If work history needs to be retained, put it in a separate document and add only a brief link here. +- Changelogs describe only user-visible changes relative to the previous release. Group changes by feature; omit implementation details, validation history, and fixes to defects introduced and corrected within the same version. Consolidate unreleased work into the feature's final behavior instead of listing its development iterations. +- Unless the user explicitly requests a version bump, add changelog notes only to the latest existing version and do not change version numbers. +- Write code comments and non-localized documentation in English. Keep English and Chinese sections of bilingual READMEs and changelogs synchronized; update README feature and usage descriptions when release changes affect them. - Inspect the original DSP game DLL, never the stripped publicized copy in `AssemblyFromGame/`, when method bodies are required. Locate DSP using the Steam registry and `steamapps/libraryfolders.vdf` as `UpdateGameDlls.ps1` does, then decompile `/DSPGAME_Data/Managed/Assembly-CSharp.dll`. - Resolve in-game terminology from `/Locale/`: `Names` contains keys, `1033` is English, and `2052` is Simplified Chinese. @@ -21,15 +24,15 @@ - Normal validation: `dotnet build /.csproj -c Release --no-restore`. If NuGet assets are missing, run `dotnet restore /.csproj` before retrying the build. - Keep temporary verification projects under the mod's excluded root `obj/` directory. Remove abandoned generated outputs when their source project is gone so the SDK source glob cannot compile them into the mod. - Refresh game references explicitly with `dotnet build UpdateGameDlls/UpdateGameDlls.csproj`; the script publicizes installed DLLs in staging and compares generated content hashes so checkout timestamps cannot hide game updates. Missing DSP or the publicizer is a warning, not a build failure. If `assembly-publicizer` requires an unavailable .NET runtime, retry with process-local `DOTNET_ROLL_FORWARD=Major` rather than changing global runtime settings. Verify discovery warnings against the actual configured library directories and original managed DLLs; absence from the VDF `apps` list alone does not establish that DSP is uninstalled. -- Package main mods with `dotnet build -t:ZipMod -c Release`; package preloaders with `dotnet build -t:CopyToParentPackage -c Release`. The mod `.csproj` `` is the single version source and packaging synchronizes `package/manifest.json`. Keep the latest English and Chinese `CHANGELOG.md` release headings and notes aligned with ``. Group user-visible changes by feature, state relevant triggers for fixes, and omit implementation-only details. Carry forward existing unreleased notes; document fixes to released regressions under the new version without rewriting historical entries. +- Package main mods with `dotnet build -t:ZipMod -c Release`; package preloaders with `dotnet build -t:CopyToParentPackage -c Release`. The mod `.csproj` `` is the single version source and packaging synchronizes `package/manifest.json`. Keep the latest English and Chinese changelog headings and notes aligned with ``; preserve existing unreleased notes and historical entries. Describe relevant triggers when documenting fixes to previously released behavior. - Treat warnings as errors except the intentional obsolete API warning `0618`; do not weaken this policy to hide new warnings. - Export Thunderstore package icons as 256x256 PNG files and verify their format and dimensions. For circular exports, apply an antialiased alpha mask to the approved artwork instead of regenerating it; preserve RGB pixels and make the exterior fully transparent. Convey the mod's function through familiar, conventionally oriented symbols rather than lettering. Preserve DSP motifs and consistent materials across related mod icons. During localized edits, preserve all unrequested geometry, placement and styling from the chosen reference; do not redesign surrounding structures to produce an overlap. Use clear foreground occlusion for intersecting forms without losing the main symbol's silhouette, and check contrast in 64x64 and 32x32 side-by-side previews. Keep unselected icon candidates under `artifacts/`, outside release package directories. ## Architecture - UXAssist Dark Fog buy-out belt signals keep each item ID, per-Metaverse rate, localization key, and embedded icon path in one definition. Name embedded icon files after the current English item names and synchronize resource includes and loader paths when renaming them. Preserve the legacy signal and saved-stock order. Rates represent equivalent single-material value: a native bundle of 10 Silicon-based Neurons, 10 Negentropy Singularities, and 10 Matter Recombinators per Metaverse corresponds to 30 of any one selected material per Metaverse. -- CheatEnabler's tech upgrade / downgrade feature lives under `Patches/Tech`; `TechTweaksPatch` owns the config (reusing `General/UnlockTech`), the `[ModFeature]` lifecycle, the `UITechTree` UI patches and the `UITechNode.OnPointerDown` transpiler, while the click decision, key-modifier decoding, downgrade recursion, UI and the per-function inverse of `GameHistoryData.UnlockTechFunction` stay in their own classes. Per-frame input goes through the registry's `OnInputUpdate`, so no separate `VFInput.OnUpdate` patch is added. `TechFuncRevert` must keep covering every `UnlockTechFunction` case: functions without a drift-free inverse are recomputed from the `Configs.freeMode` base values plus the levels still applied across all techs, never by replaying the whole tech tree, because a replay would re-apply the `func 30/31` station rescaling and the `func 5/38` package resize instead of restoring them. -- CheatEnabler's custom critical-warning texts are a single string behind two gates, and every feature that wants one takes part in both priority chains: `WarningSystem_hasCriticalWarning_Transpiler` (an OR chain deciding whether the banner appears at all) and `WarningSystem_UpdateCriticalWarningText_Transpiler` (deciding which text it shows). Tech downgrade mode is first in both so it displays on its own, without either build toggle being on; previously the banner could only appear while `Build without condition` or `No collision` was enabled. Extend the chains instead of overwriting `criticalWarningTexts` from another patch. +- Tech downgrades must validate the full dependency cascade and capacity reductions before changing game state. Recompute non-invertible bonuses from native defaults and surviving levels; replaying unrelated unlock side effects can corrupt inventory geometry and station limits. +- Custom critical-warning text must participate in both `WarningSystem.hasCriticalWarning` and `WarningSystem.UpdateCriticalWarningText`; preserve native warnings and use one shared display priority. - `ModFeatureRegistry` discovers dependent-mod features during `Awake`; feature initialization is eager, while UXAssist alone drives the deferred start, input, update, and uninitialization lifecycle. Keep dispatchers internal and idempotent. - Apply config-controlled patches from their owning feature's `Start` and `SettingChanged` handlers. Shared lifecycle helpers must only manage always-on patches and must not override saved option states. - Proto-dependent features must tolerate calls before preload completes and retry via `UXAssist.Common.GameLogic.OnDataLoaded`. Mark changes applied only after capturing valid originals and successfully mutating the proto.