astrbot_plugin_private_comp.../docs/统一人物系统开发回执-20260727.md

58 行
4.8 KiB
Markdown

# OPS Unified Person System Development Receipt
## Scope and starting point
- Repository: `astrbot_plugin_private_companion-main`
- Actual branch and commit: `ops-main`, `54b4aa297a0f27791d9e677c598094457c67c64a`
- Scope completed here: P0 shared contract, identity key normalization, read-only producer endpoints, fixed projection sample, and a non-automatic reversible legacy migration foundation.
- No code from the memory repository, root documentation, `peiban`, deployment scripts, VM, or remote was modified.
## Contract
- Name/version: `ops.unified_person.v1` / `1.0`
- Sample version: `1.0`
- Descriptor keys: `name`, `version`, `sample_version`, `required_fields`, `enums`, `identity_key_fields`
- Deterministic fingerprint: `633e2d235345d5c1bb72f8e6247e61932c5215ad2817242eefb709b502aefe03`
- Fingerprint algorithm: SHA-256 of canonical JSON with `sort_keys=True` and `separators=(',', ':')`.
- Identity key: `ops-origin-v1:<sha256(canonical normalized five-part identity)>`. It requires `companion_instance_id`, `bot_account_id`, `adapter_instance_id`, `subject_namespace`, and `platform_subject_id`; it never emits a bare platform identifier or raw canonical identity JSON.
- Identity normalization accepts strings and non-boolean integers only, rejects booleans, floats (including NaN/Infinity), and containers, applies NFC and edge trimming only, preserves internal whitespace, rejects NUL and values longer than 160 characters, and lowercases only `subject_namespace`.
- The fingerprinted enum includes all frozen relationship capabilities, including `comfort`, `proactive_care`, `hugging`, `public_favoritism`, and `nsfw`; legal configured capabilities are preserved in the projection.
- Fixed consumer sample: `docs/unified_person_projection_v1.sample.json`.
## Data and migration
- New persisted root: `unified_person`, with `profiles`, `identity_links`, `relation_policies`, `group_overlays`, and scoped migration metadata.
- Store initialization only installs empty containers. It never performs a migration at startup.
- `preview_unified_person_migration` is non-mutating. Incomplete companion/Bot/adapter/namespace context returns `legacy_unresolved` and applies no change. `apply_unified_person_migration` retains a scoped, non-recursive pre-migration backup and is idempotent by `migration_id`. `rollback_unified_person_migration` restores that scoped backup while retaining the current backup registry, without deleting legacy `users`, `groups`, scores, or configuration.
- Legacy `relationship_score` is preserved only as `affinity_baseline`; no event history is fabricated.
- Legacy `private_user_aliases` become `legacy_alias_candidates`, not identity links. They require explicit owner confirmation before any binding.
- Legacy `relationship_role=owner` is only a warning unless an explicit backend owner ID is supplied to the migration call.
## Read-only producer bridge
`PrivateCompanionExtensionAPI` now exposes:
- `get_unified_person_contract()`
- `get_unified_person_projection(person_id)`
- `resolve_unified_person_identity(identity)`
Resolution requires the exact complete identity. An unregistered identity returns `state=pending_companion`; it creates nothing. Invalid or incomplete input returns `state=quarantined` with `error_code=invalid_identity`.
## Hook order
No request Hook order was changed in this P0-only patch. Firewall classification, prompt sanitation, affinity ledger settlement, confinement, owner commands, and memory write/recall gates remain deliberately unimplemented and must not be considered enabled.
## Verification
- Directed: `C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe -m unittest tests.test_unified_person_contract -v` - 9 tests passed.
- Full: `C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe -m unittest discover -s tests -q` - 259 tests passed.
- The directed tests are counterfactual for the old unsafe behavior: a raw/missing namespace key, auto-linking legacy aliases, a mutable unresolved resolve, an invalid sample, or a non-idempotent migration makes them fail.
## Remaining work and cross-plugin dependency
- The companion side must still implement explicit administrator merge/split, person creation from real message identity, relation policies, owner-profile configuration, affinity event ledger, confinement/recovery state machine, command authorization, firewall, and page/API controls.
- Memory must compare the descriptor fingerprint before consuming a projection, call only the read-only bridge methods above, and map unavailable/unresolved input to the frozen coordination states. It must not construct `person_id` from an identity key.
- The scoped migration backup is a compatibility rollback mechanism, not a substitute for an operator's normal persisted-store backup before a production migration.
No commit, push, or deployment was performed.