MAS Code Standards

Objective

Reproduce the practical implementation style used in current dev without copying obsolete behavior or broadening scope unnecessarily.

Scope

Primary style reference samples:

1. frontend/electron/services
2. frontend/electron/ipc
3. frontend/src/views/Initialization

Use these samples as style lenses only. For frontend engineering or UI decisions, prefer mas-frontend-standards and mas-frontend-ui; for Python modules, carry over the same values of explicit orchestration, compatibility-first changes, and operational logging, but always compare nearby files before applying style assumptions.

Workflow

1. Read references/style-observations.md, with priority on commit lenses e541fa5f, 727aafb, and e5d72bdb.
2. Sample 2 to 3 sibling files in the same module before editing.
3. Keep the main execution path obvious; extract helpers only when they make the flow easier to follow.
4. Match nearby naming, logging tone, comment style, and result contracts.
5. Prefer minimal edits that blend into surrounding code rather than style-driven rewrites.
6. If recent maintainer review comments are available for the same area, treat them as the strongest style signal.
7. Before completing a user-visible feature or fix, add exactly one changelog fragment under changelog.d/ (<PR number or branch>.<feat|change|fix|breaking|remove|security|dev>.md; first line project: <key> from the project table in changelog.d/README.md — 14 adapters plus home / scheduler / emulator / notify / tools / settings / update / runtime, no catch-all, pick the nearest per the README; only dev fragments may omit it; then one user-facing sentence of at most 50 characters without project prefix, PR number or signature; python scripts/changelog.py add <type> <project> "<sentence>" creates it, with - as the project for dev). Before writing a fix or change fragment, decide which release introduced the feature you touch: a feature absent from the previous stable release's notes was introduced in the current X.Y.0 cycle (for 5.5.0: Runtime initialization, virtual display, Emulator 2.0, MFW, BetterGI, BAAH, ZZZ-OD, config restore, operator cultivation). Every later fix, maintenance or supplementary change to such a feature (bug fixes, turning something into a prompt, extra hints, default tweaks, layout changes, i18n wiring, cleanup) is beta-only: if the feature's entry is still in the top ## [未发布] section or its fragment is still in changelog.d/, add no fragment and label the PR skip-changelog (describe any wording change in the PR for a maintainer to apply); if it shipped in an earlier beta of the cycle, add the header line beta-only: true so the entry is dropped from the stable roll-up. Sub-features added to it later are beta-only as well: in the stable notes a new adapter is exactly one line (【bgi】新增 bgi 专项) and a new feature is its single introduction entry; fixes and changes to features that shipped in the previous stable are normal. Project keys use the short names bgi (BetterGI) and end (MaaEnd). A PR with several human authors lists them all in the header line author: a, b (the script never reads Co-authored-by). Maintainers may add highlight: true to route an entry into 「本次亮点」; treat it as part of the implementation rather than a reminder. Condense all changes of the PR into that one sentence. Never edit CHANGELOG.md, res/version.json or any version number: they are written only by the release PR.

Commit Lenses

1. e541fa5f: small cleanup. Keep logic local, remove one-off indirection, simplify conditions without changing outcome.
2. 727aafb: feature landing. Extend existing books, models, managers, routes, forms, and logs in parallel instead of inventing a separate architecture for the new type.
3. e5d72bdb: dev integration. Preserve the feature branch structure, then consolidate at integration points instead of rewriting during merge.

Core Traits

1. Use clear file sections such as // ==================== 类型定义 ====================.
2. Keep module headers and comments short, Chinese, and purpose-driven.
3. Prefer explicit orchestration over generic abstractions or clever helpers.
4. Use getLogger('中文名') and short operational log lines.
5. Allow light duplication when it keeps each step readable and local.
6. Respect file-local formatting; do not normalize unrelated code.
7. When adding a new script or domain type, extend config model, schema, routing, task registration, frontend types, composables, and edit views together.
8. Prefer compatibility edits at registration points such as BOOK, union types, routing branches, and progress payloads before deeper refactors.
9. For finite variants, prefer a small dict/registry mapping instead of many near-identical branches.
10. Keep frequently edited task-configuration logic visible in the owning flow with a short comment instead of hiding it behind one-off helpers.
11. Do not copy another script/domain's special-case logs, timeout exemptions, ignore lists, or workaround branches into a new module until that behavior is confirmed locally.
12. If a new capability is used only once, default to an inline block or local helper; split into builder, loader, or extra services only after real reuse or boundary pressure appears.
13. Trust existing validators, config containers, and task bases when they already guarantee an invariant; do not add a second layer of fallback or correction.
14. For new Python-heavy flows, keep signatures and call sites compatible with at least basic static type checking.
15. Prefer deleting redundant imports, waits, and wrappers over preserving "explicit" but noisy scaffolding.
16. Use Conventional Commits for commit messages: <type>(<scope>): <subject>, with documented types such as feat, fix, docs, style, refactor, perf, test, chore, build, and ci.
17. Choose commit scope from the touched file name when one file changes, or from the parent folder name when multiple related files change.
18. For backend docstrings, use Google-style sections for summary, Args, Returns, and Raises when a function needs explanation.
19. For ConfigBase subclasses, comment every ConfigItem and group config items by clear section markers before super().__init__().

Comment Preservation

Do not treat cleanup as permission to strip comments. Preserve comments that explain business intent, operational steps, compatibility decisions, non-obvious invariants, maintainer context, or config-field meaning.

Only remove or rewrite a comment when it is stale, misleading, mechanically restates the next token of code, or refers to code that is being deleted in the same edit. When rewriting, keep the useful intent and make it shorter or more accurate instead of dropping it.

Protect these comments especially:

1. ConfigItem comments and section markers in ConfigBase subclasses.
2. Ordered workflow comments such as "第一步" and "第二步" in long service flows.
3. Task-injection, config-swap, log-monitoring, and compatibility notes in runtime code.
4. Frontend section comments that help scan large edit pages or distinguish type-specific logic.

Avoid

1. Do not introduce framework-heavy abstractions or generic factories unless the surrounding module already uses them.
2. Do not hide the main workflow inside too many helper layers.
3. Do not switch comment or logging language inconsistently inside a file.
4. Do not turn a small fix into a broad refactor for stylistic purity.
5. Do not confuse "explicit" with "verbose".
6. Do not modify OpenAPI-generated files. Ask the developer to regenerate them manually when updates are required.
7. Do not split equivalent behavior into multiple methods or API routes when a dict selector or type field represents the difference directly.
8. Do not leave dead support paths for future detailed/raw config when there is no complete UI-to-runtime path yet.
9. Do not add maintainer-facing "safety" code that only repeats guarantees already enforced by base classes or validators.
10. Do not complete a user-visible feature or fix without adding its changelog fragment under changelog.d/.
11. Do not delete useful comments just to make a diff look cleaner.

Review Checklist

1. The new code reads like neighboring project-standard files.
2. Logs and comments are concise, operational, and consistent with the touched module.
3. The main path is still easy to trace top-to-bottom.
4. Compatibility and existing behavior were preserved unless the task explicitly changed them.
5. The chosen style lens matches the task: cleanup, feature landing, or dev integration.
6. Finite variant selection uses existing books/registries/dicts where that is clearer than method proliferation.
7. Config choices have one source of truth and do not duplicate existing mode/tab selectors.
8. New special cases were verified for this domain instead of cargo-culted from another module.
9. New code would survive basic static type checking without relying on None or fallback branches that conflict with declared types.
10. Commit messages and scopes follow the project convention when preparing commits.
11. Backend comments and config-class annotations use the project style rather than ad hoc prose.
12. Existing useful comments were preserved or updated accurately, not removed as noise.
13. User-visible features and fixes include exactly one changelog fragment under changelog.d/; CHANGELOG.md, res/version.json and version numbers stay untouched.