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

4.8 KiB

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.