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

12 KiB

OPS Unified Person Development Receipt (2026-07-27)

P2 Memory Person Layer and Firewall (2026-07-28)

  • Scope: P2 is implemented in this memory repository only. It adds independent ops.person_memory.v2/2.0; P0 ops.unified_person.v1/1.0 remains a read-only nested projection with frozen descriptor, fixture, and fingerprint.
  • Facts: additive fact status, observed/current person provenance, origin scope, correction/projection/firewall/fact event IDs, and firewall state. Current person_id may be reprojected; historical evidence and origin are retained.
  • Migration: preview, physical pre-apply backup, idempotent apply, transaction interruption recovery, data rollback, and correction rollback are provided. Logical rollback retains additive schema; the backup is disaster recovery.
  • Firewall/visibility: direct writes, structured envelopes, timeline, import, summaries, embeddings, relationship/knowledge edges, retrieval, and injection are gated. Blocked/rejected/quarantined/superseded content never enters ordinary FTS, embedding, edges, summaries, or injection.
  • Authority: relationship-phase automatic advancement and phase-derived naming authority are retired from runtime; legacy phase state is compatibility evidence only. Person/relation/affinity/confinement authority remains companion-side.
  • Verification: bundled-Python P2/P0/P1 directed suite last reported 24 passed; compile, diff check, and P0 fingerprint checks passed. Existing .pytest_cache WinError 5 is environmental; final full-suite audit is pending main-program review.
  • Limits: no multimodal/tool gate, affinity/confinement work, pages, deployment, companion-repository changes, commit, push, or deployment.

Scope and status

  • Actual start: ops-main at fde001a9c959880e11868b6cc7082b491e6c90ac, clean working tree.
  • Actual end: P0 unified-person contract consumer and migration-safe coordination foundation implemented in this repository only.
  • No commit, push, deployment, VM change, root documentation change, or companion-repository write was performed.

Changed files

  • core/unified_person_contract.py: frozen contract descriptor, deterministic fingerprint, namespaced origin identity key, projection consumer, stable coordination results, and legacy-unresolved reference helper.
  • core/bridge.py: read-only capability probe and explicit projection-consumer entry point.
  • tests/test_unified_person_contract.py: fixed-sample, identity, error matrix, range, derived-band, Bridge-missing, and identity-conflict coverage.
  • tests/fixtures/unified_person_projection_v1.json: byte-semantic JSON fixture aligned with the companion sample.
  • docs/错题本.md: reusable contract-consumer lesson.

Contract and fixture

  • Contract: ops.unified_person.v1 / 1.0; sample version: 1.0.
  • Canonical descriptor keys: name, version, sample_version, required_fields, enums, identity_key_fields.
  • Fingerprint: 633e2d235345d5c1bb72f8e6247e61932c5215ad2817242eefb709b502aefe03.
  • Fingerprint algorithm: SHA-256 over UTF-8 canonical JSON with sorted keys and compact separators; no timestamp, path, instance ID, random value, or fixture body participates.
  • The local fixture is JSON-deep-equal to astrbot_plugin_private_companion-main/docs/unified_person_projection_v1.sample.json; it uses person_d301001be7a1ce40df26a3eb, revision 1, Alice, score 12, hugging, and the shared resolved identity key.

Data, migration, and coordination

  • This P0 change does not alter SQLite schemas and does not migrate, delete, merge, split, or create any existing person data.
  • The normalized source identity requires all five fields: companion_instance_id, bot_account_id, adapter_instance_id, subject_namespace, and platform_subject_id. It accepts only str or non-boolean int, normalizes Unicode NFC, trims only leading and trailing whitespace, preserves internal whitespace, rejects NUL and values longer than 160 characters, and lowercases only subject_namespace. Float, NaN, and Infinity values are rejected so one numeric identity cannot acquire multiple key encodings. Its origin key is immutable and never falls back to a bare platform ID.
  • relationship_capabilities is fingerprinted in the shared enums and accepts only the frozen capability values. Required projection strings, aliases, and resolved identity keys are strictly rejected when malformed, NUL-containing, or overlong; accepted person_id values are returned unchanged.
  • Consumer statuses are resolved, pending_companion, contract_mismatch, identity_conflict, quarantined, and legacy_unresolved.
  • Bridge absence returns pending_companion with bridge_unavailable; malformed or mismatched inputs return a stable error and no person_id.
  • P1 persistent identity/reference columns, a durable pending queue, dry-run/backup/rollback migration, and write/recall firewall integration remain pending. They require a separately reviewed schema plan.

Runtime and verification

  • Existing memory request hook priority remains -20; this change adds no hook and does not alter capture, retrieval, injection, or existing bridge write paths.
  • Directed: C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe -m pytest tests/test_unified_person_contract.py -q -> 7 passed.
  • Full: the same Python runtime with -m pytest -q -> 338 passed, 8 subtests passed.
  • Fixture equality: a JSON deep comparison against the companion sample passed.
  • C:\Users\Administrator\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe -m compileall -q . passed. It reported only that the existing .pytest_cache directory could not be listed.
  • git diff --check passed.
  • Pytest emitted the pre-existing .pytest_cache permission warning (WinError 5); it did not affect results.

Counterexamples and cross-plugin dependencies

  • Counterexamples prove rejection of bad name/version/fingerprint, missing fields, unknown enums, float/out-of-range affinity, inconsistent affinity band, zero/string revision, invalid required text, invalid optional-string types, unknown capability, identity conflict, and Bridge absence. They also prove NFC identity equivalence, internal-whitespace preservation, scalar rejection, zero identity preservation, and strict NUL/length/key-format rejection.
  • The companion side must keep exposing exactly probe_unified_person_contract() compatible descriptor data and a projection with the frozen fields, capability values, strict integer affinity/revision semantics, and ops-origin-v1: resolved identity key. It remains the only authority for person creation, identity link changes, relation policy, owner state, affinity, warnings, confinement, and final safety decisions.
  • Memory-side consumers must remain read-only until the next reviewed migration and firewall phase; the master controller should compare this descriptor, fingerprint, fixture, and Bridge behavior before enabling cross-plugin flow.

P1 persistence implementation and audit

  • Scope: this repository now persists only the companion-authoritative person_id reference. It does not create, merge, split, or infer people, and it does not access the companion database.
  • core/unified_person_persistence.py adds additive SQLite schema installation, five-field source identities, immutable origin_identity_key, a durable coordination queue, lease-based replay, and a previewable reference migration.
  • MemoryRecord persists person_id, origin_identity_key, coordination_status, and projection_revision. New in-process records default to pending_companion; pre-existing SQLite rows receive the conservative schema default legacy_unresolved.
  • A successful companion projection is validated through the frozen P0 consumer and records the five-field source identity. Merge, split, and revision events only reproject the current person_id and revision. They never rewrite evidence or an existing origin key.
  • Bridge absence, contract mismatch, identity conflict, and invalid identity are queued or quarantined with stable error state. Queue keys use the supplied operation ID, or the stable (memory_id, origin_identity_key) fallback; status changes do not create new work rows. A confirmed queue row and an already resolved memory cannot be downgraded by a later failed retry.
  • Queue claims require a retryable status and an expired or absent lease. Replay requires the exact queue ID and token, an unexpired lease, and a retryable state; expired tokens and confirmed rows are rejected. New databases use memory_id ... REFERENCES memories(id) ON DELETE CASCADE; existing tables also receive explicit queue cleanup on single deletion, bulk clear, and import rollback paths.
  • Source identities have both the immutable origin-key primary key and five-field unique constraint. A SQLite trigger rejects direct changes to a nonempty origin_identity_key.
  • UnifiedPersonReferenceMigration supports dry-run, pre-apply database backup, transaction rollback on simulated interruption, idempotent completed runs, and data rollback. Normal rollback restores saved row values but intentionally leaves the additive P1 columns, tables, indexes, and trigger in place; the full pre-apply backup is the physical-disaster-recovery artifact.
  • P1 tests cover schema constraints and trigger behavior, revision monotonicity, queue deduplication, concurrent claiming, expired lease rejection, confirmed-state preservation, mismatch isolation, deletion cleanup, migration interruption, backup, idempotence, and rollback.

P1 verification

  • Directed P0+P1 tests: 15 passed.
  • Independent final full suite: 346 passed, 8 subtests passed.
  • python -m compileall -q . and git diff --check passed. Compileall could not list the pre-existing .pytest_cache; pytest emitted the same WinError 5 cache-write warning. Neither affected test execution.
  • P0 contract fingerprint remains exactly 633e2d235345d5c1bb72f8e6247e61932c5215ad2817242eefb709b502aefe03.
  • No commit, push, deployment, VM change, root-document write, or companion-repository write was performed.

P2 记忆人物层与文本防火墙(2026-07-28)

  • 范围:新增独立 ops.person_memory.v2/2.0 envelope,P0 ops.unified_person.v1/1.0 仅作为可选只读嵌套投影,未修改 P0 descriptor、fixture 或指纹。
  • 数据:memories additive 增加 fact/provenance/origin scope/correction/projection/firewall 字段、不可变 observed person 触发器、纠错事件唯一索引和 P2 migration journal/backup。
  • 门禁:Store 统一消费结构化 P2 envelope;blocked/rejected/quarantined/superseded 记录不进入 FTS、embedding、关系边或普通召回。私聊同源召回允许,私聊到群聊、跨群和低保证路径保守拒绝。
  • 纠错:纠错事件幂等,新事实 supersede 旧事实而不改写旧 evidence/origin;旧 FTS、embedding、relationship edge、knowledge edge 同步失效。
  • 权威:relationship phase 自动推进和基于阶段的称呼注入退役为 no-op;legacy state 只读兼容。记忆仓不创建、合并或拆分 person。
  • 迁移:preview/apply/backup/idempotence/rollback 已提供;中断返回稳定 interrupted,事务回滚数据 journal,物理备份仅用于灾难恢复,常规 rollback 保留 additive schema。
  • 验证:主程序独立复跑 tests/test_person_memory_p2.py tests/test_unified_person_contract.py tests/test_unified_person_persistence.py -q 为 27 passed;最终全量为 358 passed, 8 subtests passed。python -m compileall -q . 与 git diff --check 均成功退出;仅有既有 .pytest_cache 的 WinError 5 缓存写入/列举警告,未影响执行。P0 指纹仍为 633e2d235345d5c1bb72f8e6247e61932c5215ad2817242eefb709b502aefe03。
  • 限制:未涉及多模态/工具门、好感/禁闭、页面或部署;陪伴仓已通过 _memory_companion_unified_person_authority -> session_context -> bridge.compose_context -> service.session_context_from_bridge 提供真实 direct compose P0 projection source,默认配置为空时 fail closed。event attribute 注入尚未实现,且非本轮必需范围;没有提交、推送或部署。