完善客户端功能并加入40250一致性审计
This commit is contained in:
shen
@@ -0,0 +1,77 @@
|
||||
---
|
||||
name: metin2-40250-parity-audit
|
||||
description: Audit, implement, fix, or verify behavioral parity between the Metin2 40250 Windows C++ client and this Godot client. Use whenever a request mentions 40250 comparison, 1:1 parity, missing original-client behavior, parity regressions, or continuing the client audit. Do not use for unrelated features that have no 40250 compatibility requirement.
|
||||
---
|
||||
|
||||
# Metin2 40250 parity audit
|
||||
|
||||
Treat the reachable 40250 implementation semantics and its observable behavior as the reference contract. The Godot architecture and APIs may differ, but its gameplay algorithms, branch conditions, state-transition order, constants, units, timing/event sources, resource/data sources, protocol side effects, and failure/cleanup behavior must not differ unless the difference is a documented platform adapter with evidence of semantic equivalence. Compare complete call chains, not filenames or similarly named functions.
|
||||
|
||||
## Persistent state
|
||||
|
||||
The audit ledger is the source of truth:
|
||||
|
||||
- `audit/manifest.json`: current contract states and evidence links.
|
||||
- `audit/history.jsonl`: append-only state-change history.
|
||||
- `audit/contracts/`: detailed evidence for individual contracts.
|
||||
- `audit/reports/`: generated summaries; never treat these as the source of truth.
|
||||
|
||||
Before auditing, fixing, or claiming parity:
|
||||
|
||||
1. Run `python3 .agents/skills/metin2-40250-parity-audit/scripts/audit_ledger.py refresh --write`.
|
||||
2. Run `python3 .agents/skills/metin2-40250-parity-audit/scripts/audit_ledger.py report`.
|
||||
3. Read the relevant existing contract and tests. Do not repeat a still-valid `TEST_VERIFIED` audit unless the user explicitly requests revalidation.
|
||||
4. If no contract exists, add one with a stable behavior ID before marking work complete.
|
||||
|
||||
Read [references/audit-schema.md](references/audit-schema.md) whenever creating or changing ledger entries. Read [references/project-map.md](references/project-map.md) when locating reference code, current implementation, existing gap documents, or test runners.
|
||||
|
||||
## Audit method
|
||||
|
||||
For each behavior:
|
||||
|
||||
1. Define the external trigger, preconditions, state transitions, outputs, timing, interruption, failure, and cleanup behavior.
|
||||
2. Trace the complete reachable 40250 call chain, including resource-driven branches and compile-time feature flags.
|
||||
3. Build a branch-by-branch equivalence table mapping the reference preconditions, decisions, formulas, state writes, ordering, timing sources, resource reads, outputs, and cleanup paths to the current native extension, GDScript, resources, protocol handling, and UI.
|
||||
4. Classify every difference as missing, partial, wrong order, wrong value/unit, wrong algorithm, wrong timing/event source, wrong resource/data source, duplicate, platform adapter, or intentionally excluded.
|
||||
5. Treat automated output equality as necessary but not sufficient: tests can miss branches, so a different algorithm cannot be approved merely because sampled outputs currently match.
|
||||
6. Fix root mechanisms rather than coordinates, entity IDs, individual assets, one-off timing constants, or simplified approximations.
|
||||
7. Add or strengthen an automated test that fails before the fix and covers the reference behavior. Include boundary, rejection, interruption, and cleanup paths when they materially affect the behavior.
|
||||
8. Run the narrow test first, then related subsystem tests, then `git diff --check`.
|
||||
9. Update the contract's implementation-equivalence matrix, manifest, fingerprints, and history in the same change. Never mark `STATIC_VERIFIED` or `TEST_VERIFIED` without complete equivalence evidence.
|
||||
|
||||
## Implementation-equivalence gate
|
||||
|
||||
Source text and engine-facing APIs do not need to be identical, but the implementation must be semantically unified with 40250. Before verification, prove all of these independently:
|
||||
|
||||
- identical effective preconditions and early-return rules;
|
||||
- identical reachable branch structure and branch outcomes;
|
||||
- equivalent algorithms and formulas, without simplified substitutes;
|
||||
- identical state mutations and mutation order;
|
||||
- identical constants, tolerances, coordinate conversions, and units after explicit platform conversion;
|
||||
- identical timing authority and event source, such as `.msa` events rather than replacement timers;
|
||||
- identical resource, table, and protocol data authority rather than hardcoded substitutes;
|
||||
- identical network and externally visible side effects and their ordering;
|
||||
- identical interruption, rejection, rollback, failure, and cleanup behavior.
|
||||
|
||||
Permitted differences are limited to documented platform adapters such as C++ containers to Godot collections, DirectX matrices to `Transform3D`, or Windows input APIs to Godot input APIs. For every adapter, document both sides, the conversion invariant, and a focused equivalence test. If any material item differs or lacks proof, status must remain `PARTIAL` or `MAPPED`.
|
||||
|
||||
## Evidence rules
|
||||
|
||||
- `MAPPED` means only that both sides were located.
|
||||
- `STATIC_VERIFIED` requires a documented call-chain and implementation-equivalence matrix covering every material branch. Similar output alone is insufficient.
|
||||
- `TEST_VERIFIED` additionally requires meaningful automated behavior tests with a recorded passing result; tests do not waive the implementation-equivalence gate.
|
||||
- Engine/platform replacement may be `EXCLUDED` only when the replacement and externally observable verification are documented.
|
||||
- A source or test fingerprint change makes prior verification `STALE`; investigate only the affected contracts.
|
||||
- Existing prose in `docs/CLIENT-GAP.md` and similar documents is useful evidence, but it is not a current verification state unless represented in the ledger.
|
||||
- Do not claim that code inspection proves visual, timing, input-feel, driver, or Windows-specific parity. Record those limits explicitly.
|
||||
|
||||
## Scope and safety
|
||||
|
||||
- Preserve unrelated dirty-worktree changes.
|
||||
- Prefer the active files from the 40250 Visual Studio build; do not audit disabled, third-party, or obsolete code as product behavior without evidence that it is reachable.
|
||||
- Keep credentials, live-server data, copyrighted binary dependencies, generated captures, and local run outputs out of the ledger.
|
||||
- Do not change live servers or external systems unless the user requested it.
|
||||
|
||||
## Completion report
|
||||
|
||||
Report the contract IDs changed, reference and implementation call chains, discrepancies fixed, tests run, remaining unverified branches, and resulting ledger status. A subsystem is complete only when its in-scope contracts have no unexplained `UNMAPPED`, `PARTIAL`, `STALE`, or `REGRESSION` entries.
|
||||
Reference in New Issue
Block a user