[Feature] 拆分 #207：长期记忆注入不破坏 prompt 缓存

[EterUltimate]

来源：拆分自 #207 第 3 项「长期记忆注入方式导致缓存命中率趋近于 0」。

当前证据 / 背景

• 综合：近期群内技术讨论汇总 —— 人格隔离、缓存优化、注入位置与安全修复 #207 明确记录：当前长期记忆注入在特定场景下可能导致 prompt 缓存命中率接近 0，需要审查记忆注入方式。
• 当前 main HEAD：2d85684c。
• 现有相关路径：
  • services/hooks/llm_hook_handler.py：_fetch_v2(req.prompt, group_id) 获取 V2 记忆上下文；_memory_delegated() 检测 LivingMemory 委托；_inject(...) 统一注入动态上下文。
  • config.py：存在 delegate_memory_to_livingmemory、livingmemory_plugin_name、disable_local_memory_when_delegated、memory_engine、llm_hook_injection_target 等配置。
  • services/response/intelligent_responder.py：仍存在构建 enhanced system/prompt 的旧路径，可能与 hook 路径并存。
  • services/learning/remember_service.py 与 services/integration/mem0_memory_manager.py 涉及记忆写入/检索集成。
  • tests/unit/test_config.py、tests/unit/test_config_service.py 已覆盖部分 LivingMemory/LightRAG 配置警告。

本 issue 不假设所有路径都有问题；目标是把长期记忆注入的 cache-friendly 行为补成可验证契约。

范围

审查并约束长期记忆相关的注入路径：V2 本地记忆、LivingMemory 委托、mem0 集成、legacy intelligent responder prompt 构建。优先小修和测试，不做记忆系统重构。

独立验收标准

• 列出现有长期记忆注入路径，并在代码注释、测试名或文档中标明哪条路径负责最终注入，避免本地记忆与 LivingMemory 重复注入。
• 当 delegate_memory_to_livingmemory=True 且 disable_local_memory_when_delegated=True 时，本地长期记忆内容不得再次注入 LLM prompt；相关行为有单测覆盖。
• 记忆内容尽量进入动态 late section，例如 extra_user_content_parts 或等价 late user/content part；不得无条件拼入稳定 persona/system prompt 前缀。
• no-memory、stable-memory、changed-memory 三种场景都有测试：稳定 system prompt/base prompt 前缀保持一致，变化只出现在记忆动态段。
• 记忆动态段的排序可预测，例如按相关度/时间/id 的明确规则排序；同一输入重复构建不会改变顺序。
• 原始记忆文本不得被永久写回 persona/system prompt；若需要学习为人格变更，必须走现有审查/快照机制。
• 兼容旧版 AstrBot fallback：不支持 late part API 时，可以回退，但必须有日志或测试说明其 cache 影响。

非目标

• 不要求实现 cache 预热，除非后续有实测数据证明收益。
• 不要求替换 LivingMemory、LightRAG 或 mem0。
• 不要求改变记忆检索算法，只约束注入位置、重复注入和可测试行为。

建议测试覆盖

• services/hooks/llm_hook_handler.py 的 hook 单测：覆盖 LivingMemory 委托、本地 V2 记忆存在/不存在、fallback 注入。
• services/response/intelligent_responder.py 回归测试：确认旧路径不会把短期/长期动态记忆永久混进 persona prompt。
• tests/unit/test_config.py / tests/unit/test_config_service.py：继续覆盖高成本组合警告与默认安全配置。

[github-actions]

🤖 Issue 审查报告

优先级: 🟠 high

📋 用户处理意见

问题摘要: 这是关于“长期记忆注入位置/重复注入/顺序稳定性”以提升 prompt 缓存命中率的行为契约与测试补齐，属于代码层面的改进需求，无法通过用户侧配置完全解决。

问题分类: 代码问题

该问题需要开发者修复，请等待后续版本更新。

---

🔧 开发者修复建议（点击展开）

技术摘要: 需要把长期记忆统一注入到“动态 late section”（而非稳定 system/persona 前缀），并在 LivingMemory 委托开启时严格禁止本地 V2 记忆再次注入，同时为 no-memory/stable-memory/changed-memory 场景增加可验证测试契约。

相关模块: services/hooks, services/response, services/learning, services/integration, utils/cache_manager

相关文件: services/hooks/llm_hook_handler.py, services/response/intelligent_responder.py, services/learning/remember_service.py, services/integration/mem0_memory_manager.py, config.py, tests/unit/test_config.py, tests/unit/test_config_service.py

根因分析: 当前存在多条可能改写 prompt 结构的路径：services/hooks/llm_hook_handler.py 负责 V2 记忆获取与统一注入（_fetch_v2/_memory_delegated/_inject），而 services/response/intelligent_responder.py 仍保留 legacy 的 enhanced system/prompt 构建路径；若两者在不同 AstrBot 版本/配置下并存，长期记忆可能被拼进稳定前缀（system/persona/prompt）或发生“LivingMemory 委托 + 本地记忆”重复注入，从而导致缓存 key 高度抖动、命中率接近 0。此外，记忆段的排序若依赖非稳定遍历/非确定性字段，也会导致同输入重复构建 prompt 不一致。

修复建议: 1) 明确“最终注入点”的单一权威路径：以 services/hooks/llm_hook_handler.py 为准，在文件头/函数 docstring 标注注入契约；在 intelligent_responder 的 legacy 构建中增加硬性保护（当 hook 可用/开启时不再把长期记忆拼入 system/persona/prompt 前缀），或将 legacy 仅作为不支持 late-part API 的 fallback。
2) 在 services/hooks/llm_hook_handler.py：

• 在 _inject(...) 内部实现注入分层：优先写入 req.extra_user_content_parts（或等价 late user/content part）；仅当检测到 AstrBot/adapter 不支持 late part 时，才回退到拼接 prompt，并记录 warning 日志（注明 cache 影响）。
• 在注入前统一做“委托互斥”判定：若 _memory_delegated()==True 且 config.disable_local_memory_when_delegated==True，则 _fetch_v2(...) 直接返回空/跳过注入；并确保 mem0/LivingMemory 只走一条注入链路。
• 对记忆条目排序固定化：在 _fetch_v2 或 _inject 前对记忆列表按明确键排序（例如 score desc, created_at desc, id asc；若无 score 则 time/id），避免 Python dict/DB 返回顺序造成抖动。

3. 在 services/response/intelligent_responder.py：增加回归测试所需的“不得写回 persona/system prompt”的保护：长期/短期动态记忆只能进入动态段（如果 legacy 必须拼接，也要拼到末尾并通过注释/日志说明），人格学习必须走现有 persona snapshot/review 机制（不要把原始记忆文本直接持久化到 persona prompt 字段）。
4. 测试补齐（建议新增 tests/unit/test_llm_hook_memory_injection.py 或同目录文件）：
   • 用 stub 的 req 对象（含 prompt/system_prompt/extra_user_content_parts）验证：no-memory/stable-memory/changed-memory 下，system_prompt/base prompt 前缀 hash 不变，变化只出现在 extra_user_content_parts（或 fallback late section）。
   • 覆盖 delegate_memory_to_livingmemory=True + disable_local_memory_when_delegated=True 时，本地 V2 记忆不注入（断言注入段为空，且仅 LivingMemory 路径发生）。
   • 覆盖排序稳定性：同一输入重复构建 2 次，注入段文本/条目顺序完全一致。
   • 覆盖 fallback：当 req 不支持 extra_user_content_parts 时会拼接 prompt 末尾，并产生可断言的 warning 日志（或在测试中标注 cache impact）。

---

_{🤖 此报告由 AI 自动生成，已分析仓库源码，仅供参考。开发者会尽快审阅您的 issue。}

[EterUltimate]

Fixed in 39a7cefc (fix: keep memory injection cache friendly) and merged to main.

Evidence:

• services/hooks/llm_hook_handler.py now documents the long-term memory injection contract and normalizes V2 related_memories into the dynamic late section only.
• LivingMemory delegation continues to strip local V2 memories before injection.
• services/response/intelligent_responder.py documents that legacy context enhancement does not consume related_memories into the stable persona/system prompt.
• Added regression coverage in tests/unit/test_feature_delegation.py and tests/unit/test_intelligent_responder_memory_contract.py for no-memory/stable-memory/changed-memory, deterministic memory ordering, LivingMemory delegation, and legacy fallback behavior.

Validation:

• python -m py_compile services\hooks\llm_hook_handler.py services\response\intelligent_responder.py tests\unit\test_feature_delegation.py tests\unit\test_intelligent_responder_memory_contract.py
• python -m pytest tests\unit\test_feature_delegation.py tests\unit\test_intelligent_responder_memory_contract.py -q -> 16 passed
• python -m pytest tests\unit\test_config.py tests\unit\test_config_service.py -q -> 78 passed
• python -m pytest tests\unit\test_learning_chain_regressions.py -q -> 38 passed
• GitHub CI for main / 39a7cefc passed: https://github.com/NickCharlie/astrbot_plugin_self_learning/actions/runs/27875493068