refactor: 将 A_Memorix 重构为主线长期记忆子系统并重建管理界面

- 将 A_Memorix 从旧 submodule / 插件形态迁入主线源码，主体落到 src/A_memorix - 调整主程序接入方式，使 A_Memorix 作为源码内长期记忆子系统运行 - 回收父项目插件体系中针对 A_Memorix 的特判，减少对 plugin 通用层的侵入 - 将长期记忆配置、运行时、自检、导入、调优等能力收口到 memory 路由与主线服务层 - 重做长期记忆控制台与图谱页面，按 MaiBot 现有 dashboard 风格接入 - 补充实体关系图与证据视图双视图能力，支持查看节点、关系、段落及其证据链路 - 新增长期记忆配置编辑器与 memory-api，支持主线内配置管理 - 补齐删除管理能力：删除预览、混合删除、来源批量删除、删除操作恢复 - 优化删除预览与删除操作详情的前端展示，支持分页、检索，并以实体名/关系内容/段落摘要替代单纯 hash 展示 - 修复图谱与控制台相关前端问题，包括证据视图切换、查询触发时机、删除弹层空值保护等 - 新增或更新 A_Memorix 相关测试、WebUI 路由测试、前端 vitest 测试与辅助验证脚本 - 移除旧 plugins/A_memorix、.gitmodules 及相关历史维护文档
2026-04-03 08:08:24 +08:00
parent bf5eb45709
commit 15d436b3a1
136 changed files with 52533 additions and 629 deletions
--- a/src/A_memorix/CONFIG_REFERENCE.md
+++ b/src/A_memorix/CONFIG_REFERENCE.md
@@ -0,0 +1,359 @@
+# A_Memorix 配置参考 (v2.0.0)
+
+本文档对应当前仓库代码（`__version__ = 2.0.0`、`SCHEMA_VERSION = 9`）。
+
+说明：
+
+- 本文只覆盖 **当前运行时实际读取** 的配置键。
+- 默认配置文件路径为 `config/a_memorix.toml`。
+- 旧版 `/query`、`/memory`、`/visualize` 命令体系相关配置，不再作为主路径说明。
+- 未配置的键会回退到代码默认值。
+- 长期记忆控制台已可视化高频常用字段；未展示的长尾高级项仍然有效，请通过“源码模式 / 原始 TOML”编辑。
+
+## 常用完整配置
+
+```toml
+[plugin]
+enabled = true
+
+[storage]
+data_dir = "data/plugins/a-dawn.a-memorix"
+
+[embedding]
+model_name = "auto"
+dimension = 1024
+batch_size = 32
+max_concurrent = 5
+enable_cache = false
+quantization_type = "int8"
+
+[embedding.fallback]
+enabled = true
+probe_interval_seconds = 180
+allow_metadata_only_write = true
+
+[embedding.paragraph_vector_backfill]
+enabled = true
+interval_seconds = 60
+batch_size = 64
+max_retry = 5
+
+[retrieval]
+top_k_paragraphs = 20
+top_k_relations = 10
+top_k_final = 10
+alpha = 0.5
+enable_ppr = true
+ppr_alpha = 0.85
+ppr_timeout_seconds = 1.5
+ppr_concurrency_limit = 4
+enable_parallel = true
+
+[retrieval.sparse]
+enabled = true
+backend = "fts5"
+mode = "auto"
+tokenizer_mode = "jieba"
+candidate_k = 80
+relation_candidate_k = 60
+
+[threshold]
+min_threshold = 0.3
+max_threshold = 0.95
+percentile = 75.0
+min_results = 3
+enable_auto_adjust = true
+
+[filter]
+enabled = true
+mode = "blacklist"
+chats = []
+
+[episode]
+enabled = true
+generation_enabled = true
+pending_batch_size = 20
+pending_max_retry = 3
+max_paragraphs_per_call = 20
+max_chars_per_call = 6000
+source_time_window_hours = 24
+segmentation_model = "auto"
+
+[person_profile]
+enabled = true
+refresh_interval_minutes = 30
+active_window_hours = 72
+max_refresh_per_cycle = 50
+top_k_evidence = 12
+
+[memory]
+enabled = true
+half_life_hours = 24.0
+prune_threshold = 0.1
+freeze_duration_hours = 24.0
+
+[advanced]
+enable_auto_save = true
+auto_save_interval_minutes = 5
+debug = false
+
+[web.import]
+enabled = true
+max_queue_size = 20
+max_files_per_task = 200
+max_file_size_mb = 20
+max_paste_chars = 200000
+default_file_concurrency = 2
+default_chunk_concurrency = 4
+
+[web.tuning]
+enabled = true
+max_queue_size = 8
+poll_interval_ms = 1200
+default_intensity = "standard"
+default_objective = "precision_priority"
+default_top_k_eval = 20
+default_sample_size = 24
+```
+
+### 可视化与原始 TOML 的分工
+
+- 长期记忆控制台：适合修改高频项，例如 embedding、检索、Episode、人物画像、导入与调优的常用开关。
+- 原始 TOML：适合复制整份配置、批量调整参数，或修改未在可视化表单中展示的高级项。
+- raw-only 高级项仍包括：`retrieval.fusion.*`、`retrieval.search.relation_intent.*`、`retrieval.search.graph_recall.*`、`retrieval.aggregate.*`、`memory.orphan.*`、`advanced.extraction_model`、`web.import.llm_retry.*`、`web.import.path_aliases`、`web.import.convert.*`、`web.tuning.llm_retry.*`、`web.tuning.eval_query_timeout_seconds`。
+
+## 1. 存储与嵌入
+
+### `storage`
+
+- `storage.data_dir` (代码默认 `./data`；当前内置配置推荐 `data/plugins/a-dawn.a-memorix`)
+: 数据目录。相对路径按 MaiBot 仓库根目录解析。
+
+### `embedding`
+
+- `embedding.model_name` (默认 `auto`)
+: embedding 模型选择。
+- `embedding.dimension` (默认 `1024`)
+: 唯一公开的维度控制项。A_Memorix 内部会自动映射为 provider 所需请求字段，并在运行时做真实探测与校验。
+- `embedding.batch_size` (默认 `32`)
+- `embedding.max_concurrent` (默认 `5`)
+- `embedding.enable_cache` (默认 `false`)
+- `embedding.retry` (默认 `{}`)
+: embedding 调用重试策略。
+- `embedding.quantization_type`
+: 当前主路径仅建议 `int8`。
+- `embedding.fallback.enabled` (默认 `true`)
+- `embedding.fallback.probe_interval_seconds` (默认 `180`)
+- `embedding.fallback.allow_metadata_only_write` (默认 `true`)
+- `embedding.paragraph_vector_backfill.enabled` (默认 `true`)
+- `embedding.paragraph_vector_backfill.interval_seconds` (默认 `60`)
+- `embedding.paragraph_vector_backfill.batch_size` (默认 `64`)
+- `embedding.paragraph_vector_backfill.max_retry` (默认 `5`)
+
+## 2. 检索
+
+### `retrieval` 主键
+
+- `retrieval.top_k_paragraphs` (默认 `20`)
+- `retrieval.top_k_relations` (默认 `10`)
+- `retrieval.top_k_final` (默认 `10`)
+- `retrieval.alpha` (默认 `0.5`)
+- `retrieval.enable_ppr` (默认 `true`)
+- `retrieval.ppr_alpha` (默认 `0.85`)
+- `retrieval.ppr_timeout_seconds` (默认 `1.5`)
+- `retrieval.ppr_concurrency_limit` (默认 `4`)
+- `retrieval.enable_parallel` (默认 `true`)
+- `retrieval.relation_vectorization.enabled` (默认 `false`)
+
+### `retrieval.sparse` (`SparseBM25Config`)
+
+常用键（默认值）：
+
+- `enabled = true`
+- `backend = "fts5"`
+- `lazy_load = true`
+- `mode = "auto"` (`auto`/`fallback_only`/`hybrid`)
+- 运行时若 embedding 进入 degraded，会强制按 `fallback_only` 执行读路径（不改用户配置文件）
+- `tokenizer_mode = "jieba"` (`jieba`/`mixed`/`char_2gram`)
+- `char_ngram_n = 2`
+- `candidate_k = 80`
+- `relation_candidate_k = 60`
+- `enable_ngram_fallback_index = true`
+- `enable_relation_sparse_fallback = true`
+
+### `retrieval.fusion` (`FusionConfig`)
+
+- `method` (默认 `weighted_rrf`)
+- `rrf_k` (默认 `60`)
+- `vector_weight` (默认 `0.7`)
+- `bm25_weight` (默认 `0.3`)
+- `normalize_score` (默认 `true`)
+- `normalize_method` (默认 `minmax`)
+
+### `retrieval.search.relation_intent` (`RelationIntentConfig`)
+
+- `enabled` (默认 `true`)
+- `alpha_override` (默认 `0.35`)
+- `relation_candidate_multiplier` (默认 `4`)
+- `preserve_top_relations` (默认 `3`)
+- `force_relation_sparse` (默认 `true`)
+- `pair_predicate_rerank_enabled` (默认 `true`)
+- `pair_predicate_limit` (默认 `3`)
+
+### `retrieval.search.graph_recall` (`GraphRelationRecallConfig`)
+
+- `enabled` (默认 `true`)
+- `candidate_k` (默认 `24`)
+- `max_hop` (默认 `1`)
+- `allow_two_hop_pair` (默认 `true`)
+- `max_paths` (默认 `4`)
+
+### `retrieval.aggregate`
+
+- `retrieval.aggregate.rrf_k`
+- `retrieval.aggregate.weights`
+
+用于聚合检索阶段混合策略；未配置时走代码默认行为。
+
+## 3. 阈值过滤
+
+### `threshold` (`ThresholdConfig`)
+
+- `threshold.min_threshold` (默认 `0.3`)
+- `threshold.max_threshold` (默认 `0.95`)
+- `threshold.percentile` (默认 `75.0`)
+- `threshold.std_multiplier` (默认 `1.5`)
+- `threshold.min_results` (默认 `3`)
+- `threshold.enable_auto_adjust` (默认 `true`)
+
+## 4. 聊天过滤
+
+### `filter`
+
+用于 `respect_filter=true` 场景（检索和写入都支持）。
+
+```toml
+[filter]
+enabled = true
+mode = "blacklist" # blacklist / whitelist
+chats = ["group:123", "user:456", "stream:abc"]
+```
+
+规则：
+
+- `blacklist`：命中列表即拒绝
+- `whitelist`：仅列表内允许
+- 列表为空时：
+  - `blacklist` => 全允许
+  - `whitelist` => 全拒绝
+
+## 5. Episode
+
+### `episode`
+
+- `episode.enabled` (默认 `true`)
+- `episode.generation_enabled` (默认 `true`)
+- `episode.pending_batch_size` (默认 `20`，部分路径默认 `12`)
+- `episode.pending_max_retry` (默认 `3`)
+- `episode.max_paragraphs_per_call` (默认 `20`)
+- `episode.max_chars_per_call` (默认 `6000`)
+- `episode.source_time_window_hours` (默认 `24`)
+- `episode.segmentation_model` (默认 `auto`)
+: 支持 `auto`，也支持填写 `utils/replyer/planner/tool_use` 或具体模型名。
+
+## 6. 人物画像
+
+### `person_profile`
+
+- `person_profile.enabled` (默认 `true`)
+- `person_profile.refresh_interval_minutes` (默认 `30`)
+- `person_profile.active_window_hours` (默认 `72`)
+- `person_profile.max_refresh_per_cycle` (默认 `50`)
+- `person_profile.top_k_evidence` (默认 `12`)
+
+## 7. 记忆演化与回收
+
+### `memory`
+
+- `memory.enabled` (默认 `true`)
+- `memory.half_life_hours` (默认 `24.0`)
+- `memory.base_decay_interval_hours` (默认 `1.0`)
+- `memory.prune_threshold` (默认 `0.1`)
+- `memory.freeze_duration_hours` (默认 `24.0`)
+
+### `memory.orphan`
+
+- `enable_soft_delete` (默认 `true`)
+- `entity_retention_days` (默认 `7.0`)
+- `paragraph_retention_days` (默认 `7.0`)
+- `sweep_grace_hours` (默认 `24.0`)
+
+## 8. 高级运行时
+
+### `advanced`
+
+- `advanced.enable_auto_save` (默认 `true`)
+- `advanced.auto_save_interval_minutes` (默认 `5`)
+- `advanced.debug` (默认 `false`)
+- `advanced.extraction_model` (默认 `auto`)
+
+## 9. 导入中心 (`web.import`)
+
+### 开关与限流
+
+- `web.import.enabled` (默认 `true`)
+- `web.import.max_queue_size` (默认 `20`)
+- `web.import.max_files_per_task` (默认 `200`)
+- `web.import.max_file_size_mb` (默认 `20`)
+- `web.import.max_paste_chars` (默认 `200000`)
+- `web.import.default_file_concurrency` (默认 `2`)
+- `web.import.default_chunk_concurrency` (默认 `4`)
+- `web.import.max_file_concurrency` (默认 `6`)
+- `web.import.max_chunk_concurrency` (默认 `12`)
+- `web.import.poll_interval_ms` (默认 `1000`)
+
+### 重试与路径
+
+- `web.import.llm_retry.max_attempts` (默认 `4`)
+- `web.import.llm_retry.min_wait_seconds` (默认 `3`)
+- `web.import.llm_retry.max_wait_seconds` (默认 `40`)
+- `web.import.llm_retry.backoff_multiplier` (默认 `3`)
+- `web.import.path_aliases` (默认内置 `raw/lpmm/plugin_data`)
+
+### 转换阶段
+
+- `web.import.convert.enable_staging_switch` (默认 `true`)
+- `web.import.convert.keep_backup_count` (默认 `3`)
+
+## 10. 调优中心 (`web.tuning`)
+
+- `web.tuning.enabled` (默认 `true`)
+- `web.tuning.max_queue_size` (默认 `8`)
+- `web.tuning.poll_interval_ms` (默认 `1200`)
+- `web.tuning.eval_query_timeout_seconds` (默认 `10.0`)
+- `web.tuning.default_intensity` (默认 `standard`，可选 `quick/standard/deep`)
+- `web.tuning.default_objective` (默认 `precision_priority`，可选 `precision_priority/balanced/recall_priority`)
+- `web.tuning.default_top_k_eval` (默认 `20`)
+- `web.tuning.default_sample_size` (默认 `24`)
+- `web.tuning.llm_retry.max_attempts` (默认 `3`)
+- `web.tuning.llm_retry.min_wait_seconds` (默认 `2`)
+- `web.tuning.llm_retry.max_wait_seconds` (默认 `20`)
+- `web.tuning.llm_retry.backoff_multiplier` (默认 `2`)
+
+## 11. 兼容性提示
+
+- 若你从 `1.x` 升级，请优先运行：
+
+```bash
+python src/A_memorix/scripts/release_vnext_migrate.py preflight --strict
+python src/A_memorix/scripts/release_vnext_migrate.py migrate --verify-after
+python src/A_memorix/scripts/release_vnext_migrate.py verify --strict
+```
+
+- 启动前再执行：
+
+```bash
+python src/A_memorix/scripts/runtime_self_check.py --json
+```
+
+以避免 embedding 维度与向量库不匹配导致运行时异常。