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

4.7 KiB

OPS Unified Person P1 Development Receipt

Scope

  • Repository: astrbot_plugin_private_companion-main
  • Start: ops-main at 54b4aa297a0f27791d9e677c598094457c67c64a, with the approved P0 worktree changes present.
  • P0 descriptor and fingerprint remain unchanged: 633e2d235345d5c1bb72f8e6247e61932c5215ad2817242eefb709b502aefe03.
  • This P1 patch implements companion-owned person registry and identity lifecycle only. It does not implement affinity, confinement, firewall, commands, pages, deployment, or memory-plugin writes.

Schema and Service

  • unified_person now persists registry_version, audit_events, idempotent operations, and reversible merge_operations alongside P0 profiles and identity links.
  • unified_person_registry.py uses copy-on-write under a process-local lock. One complete five-part identity has one active link; concurrent observations cannot create duplicate profiles or links.
  • upsert_observed_identity creates a separate deterministic person only for the exact observed five-part identity. It never follows aliases or names.
  • link_identity, unlink_identity, merge_people, and split_merged_people require explicit authorization, actor, reason, and operation ID. Owner profiles additionally require owner_authorized.
  • Merge suspends rather than deletes the source profile, snapshots exact source/target profile, active-link, and group-overlay state, and split restores that recorded mapping rather than guessing from current identities.
  • Merge sets both affected profiles to max(source_revision, target_revision) + 1; split sets both to a value strictly higher than the merge-time maximum. Consumers therefore never observe a cross-person identity mapping change at a stale or repeated projection revision.
  • DEV-003 correction: split restores only the merge-owned source profile, moved identity links, merge-added aliases, and the group-overlay person_id/merge-provenance fields. It deliberately preserves any later unrelated target-profile and overlay state. A moved link or merge-owned overlay whose person, origin, or merge provenance no longer matches rejects split with split_conflict before any write. Split revisions are higher than the recorded merge revision and both current profile revisions.
  • Unlink rejects the final active identity. If it unlinks the resolved primary while another active link exists, it picks the lexicographically first remaining key and updates the profile revision.

API

  • Internal companion wrappers: _unified_person_registry_status, _unified_person_audit_events, and _apply_unified_person_lifecycle with a fixed lifecycle-method allowlist.
  • Read-only Extension API additions: get_unified_person_registry_status() and get_unified_person_audit_events(limit=...).
  • Lifecycle writes are deliberately not exposed over the cross-plugin Extension API.
  • Every result includes ok, code, operation_id, changed, person_id, affected_person_ids, projection_revision, and audit_event_id. Retrying the same operation ID with the identical payload returns the stored result with idempotent=true; a changed payload yields operation_id_conflict.

Verification

  • Directed: C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe -m unittest tests.test_unified_person_contract tests.test_unified_person_registry -v - 16 tests passed.
  • Full: C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe -m unittest discover -s tests -q - 266 tests passed.
  • compileall and git diff --check passed. compileall emitted only the pre-existing unreadable .pytest_cache notice and exited 0.
  • Counterfactual coverage includes a cross-thread same-identity upsert, weak/unauthorized binding refusal, owner authorization refusal, last-identity refusal, exact split restoration, operation-ID conflict, and no-change assertions after failed mutations.
  • DEV-003 directed regression adds post-merge unrelated target-profile and group-overlay updates that survive split while the overlay's prior provenance is restored, plus changed/deleted moved-link cases that fail with zero state changes. P0 fingerprint and projection fixture remain unchanged.

Risks and Next Steps

  • The lock is process-local because this plugin's JSON StoreManager is process-local. Multi-process shared-store deployment is outside current architecture and must not be added without a transactional backend.
  • P1 has no owner profile administration UI; owner_authorized is an internal trusted-caller gate that P2 must bind to the configured owner profile and audit policy.
  • Memory must continue to consume only P0 read APIs and P1 projection revisions; it must never call lifecycle write methods or invent a person_id.

No commit, push, or deployment was performed.