57 行
4.8 KiB
Markdown
57 行
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.
|