docs:更新mem契约文档

docs/a_memorix_sync.md

@@ -5,7 +5,9 @@
 - A_Memorix 主线源码位于 `src/A_memorix`
 - 宿主接入层位于 `src/services/memory_service.py`、`src/webui/routers/memory.py` 与 dashboard 长期记忆页面
 - 运行配置位于 `config/a_memorix.toml`
-- 运行数据位于 `data/plugins/a-dawn.a-memorix/`
+- 运行数据由 `storage.data_dir` 决定（当前配置模板默认 `data/a-memorix/`）
+- 旧离线脚本默认目录仍可能落在 `data/plugins/a-dawn.a-memorix/`（见脚本注释/参数说明）
+- Web 上传暂存目录为 `data/memory_upload_staging/`
 - 上游同步方式固定为 `git subtree`
 
 ## 首次接入
@@ -40,6 +42,7 @@ git subtree pull --prefix=src/A_memorix https://github.com/A-Dawn/A_memorix.git
 
 ## 同步后检查
 
-1. 确认 `config/a_memorix.toml` 仍指向 `data/plugins/a-dawn.a-memorix`
+1. 确认 `config/a_memorix.toml` 中 `storage.data_dir` 与你的运行目录规划一致（默认模板为 `data/a-memorix`）
 2. 运行 `python src/A_memorix/scripts/runtime_self_check.py --help`
-3. 运行 A_memorix 相关测试或最少执行一次针对性导入验证
+3. 运行 `python -m pytest pytests/A_memorix_test/test_memory_service.py`
+4. 运行 `cd dashboard && npm run test -- src/routes/resource/__tests__/knowledge-base.test.tsx`

src/A_memorix/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 更新日志 (Changelog)
 
+## [Unreleased]
+
+### 📚 文档口径同步
+
+- 补充并统一“运行时目录”和“离线脚本默认目录”的说明：
+  - 运行时主目录由 `storage.data_dir` 决定（当前模板默认 `data/a-memorix`）；
+  - 部分离线脚本仍以 `data/plugins/a-dawn.a-memorix` 作为默认处理目录。
+- 修正文档中的导入示例参数，`memory_import_admin.create_paste` 的 `input_mode` 示例统一为 `text`/`json`。
+- 更新 `README.md` 关于元数据 schema 的描述，和当前代码 `SCHEMA_VERSION = 9` 保持一致。
+
 ## [2.0.0] - 2026-03-18
 
 本次 `2.0.0` 为架构收敛版本，主线是 **SDK Tool 接口统一**、**管理工具能力补齐**、**元数据 schema 升级到 v8** 与 **文档口径同步到 2.0.0**。

src/A_memorix/CONFIG_REFERENCE.md

@@ -17,7 +17,7 @@
 enabled = true
 
 [storage]
-data_dir = "data/plugins/a-dawn.a-memorix"
+data_dir = "data/a-memorix"
 
 [embedding]
 model_name = "auto"
@@ -126,9 +126,14 @@ default_sample_size = 24
 
 ### `storage`
 
-- `storage.data_dir` (代码默认 `./data`；当前内置配置推荐 `data/plugins/a-dawn.a-memorix`)
+- `storage.data_dir` (当前配置模板默认 `data/a-memorix`)
 : 数据目录。相对路径按 MaiBot 仓库根目录解析。
 
+补充说明：
+
+- 部分离线脚本若未显式覆盖路径，会回退到 `A_memorix.paths.default_data_dir()`（当前为 `data/plugins/a-dawn.a-memorix`）。
+- 建议在运维侧统一目录策略，避免“控制台写入目录”和“脚本处理目录”不一致。
+
 ### `embedding`
 
 - `embedding.model_name` (默认 `auto`)

src/A_memorix/IMPORT_GUIDE.md

@@ -29,6 +29,11 @@ python src/A_memorix/scripts/runtime_self_check.py --json
 data/plugins/a-dawn.a-memorix/raw/
 ```
 
+说明：
+
+- `process_knowledge.py` 当前默认扫描上述目录。
+- 若你的运行配置使用 `storage.data_dir = "data/a-memorix"`，请在执行脚本前统一目录，避免脚本导入目录与运行目录不一致。
+
 执行：
 
 ```bash
@@ -52,7 +57,7 @@ python src/A_memorix/scripts/import_lpmm_json.py <json文件或目录>
 ## 2.3 LPMM 数据转换
 
 ```bash
-python src/A_memorix/scripts/convert_lpmm.py -i <lpmm数据目录> -o data/plugins/a-dawn.a-memorix
+python src/A_memorix/scripts/convert_lpmm.py -i <lpmm数据目录> -o data/a-memorix
 ```
 
 ## 2.4 历史数据迁移
@@ -115,7 +120,7 @@ python src/A_memorix/scripts/audit_vector_consistency.py --json
   "arguments": {
     "action": "create_paste",
     "content": "今天完成了检索调优回归。",
-    "input_mode": "plain_text",
+    "input_mode": "text",
     "source": "manual:worklog"
   }
 }

src/A_memorix/MODIFICATION_POLICY.md

@@ -27,9 +27,13 @@
 - `src/services/memory_service.py`
 - `src/webui/routers/memory.py`
 - `dashboard/src/routes/resource/knowledge-base.tsx`
+- `dashboard/src/routes/resource/__tests__/knowledge-base.test.tsx`
 - `dashboard/src/routes/resource/knowledge-graph/`
+- `dashboard/src/lib/memory-api.ts`
 - `config/a_memorix.toml`
-- `data/plugins/a-dawn.a-memorix/`
+- `data/a-memorix/`
+- `data/plugins/a-dawn.a-memorix/`（旧脚本默认路径）
+- `data/memory_upload_staging/`（Web 上传暂存）
 - `pytests/A_memorix_test/`
 - 同步脚本与同步文档，例如 `scripts/sync_a_memorix_subtree.sh`
 

src/A_memorix/QUICK_START.md

@@ -42,7 +42,7 @@ pip install -r requirements.txt --upgrade
 enabled = true
 
 [storage]
-data_dir = "data/plugins/a-dawn.a-memorix"
+data_dir = "data/a-memorix"
 
 [embedding]
 model_name = "auto"
@@ -157,12 +157,14 @@ python src/A_memorix/scripts/runtime_self_check.py --json
 
 ### 4.1 文本批量导入
 
-把文本放到：
+`process_knowledge.py` 当前默认扫描目录为：
 
 ```text
 data/plugins/a-dawn.a-memorix/raw/
 ```
 
+若你当前运行目录使用 `storage.data_dir = "data/a-memorix"`，建议先把文本同步到脚本默认目录再执行，避免导入目录与运行目录不一致。
+
 执行：
 
 ```bash
@@ -181,7 +183,7 @@ python src/A_memorix/scripts/process_knowledge.py --chat-log --chat-reference-ti
 
 ```bash
 python src/A_memorix/scripts/import_lpmm_json.py <json文件或目录>
-python src/A_memorix/scripts/convert_lpmm.py -i <lpmm数据目录> -o data/plugins/a-dawn.a-memorix
+python src/A_memorix/scripts/convert_lpmm.py -i <lpmm数据目录> -o data/a-memorix
 python src/A_memorix/scripts/migrate_chat_history.py --help
 python src/A_memorix/scripts/migrate_maibot_memory.py --help
 python src/A_memorix/scripts/migrate_person_memory_points.py --help

src/A_memorix/README.md

@@ -21,7 +21,7 @@ A_Memorix 是 MaiBot 内置的长期记忆子系统。
 
 - 旧 `components/commands/*`、`components/tools/*` 与 `server.py` 已移除。
 - 统一入口为宿主侧 host service + [`core/runtime/sdk_memory_kernel.py`](core/runtime/sdk_memory_kernel.py)。
-- 元数据 schema 为 `v8`，新增外部引用与运维操作记录（如 `external_memory_refs`、`memory_v5_operations`、`delete_operations`）。
+- 元数据 schema 为 `v9`，支持外部引用与运维操作记录（如 `external_memory_refs`、`memory_v5_operations`、`delete_operations`）。
 
 如果你还在使用旧版 slash 命令（如 `/query`、`/memory`、`/visualize`），需要按本文的 Tool 接口迁移。
 
@@ -140,6 +140,7 @@ enabled = true
 ### 配置方式
 
 - 默认配置文件：`config/a_memorix.toml`
+- 运行目录主路径：`storage.data_dir`（当前模板默认 `data/a-memorix`）
 - 长期记忆控制台：适合修改常用高频项，如 embedding、检索、Episode、人物画像、导入与调优开关。
 - 原始 TOML：适合复制整份配置、批量粘贴参数，或编辑未在可视化表单中展示的高级项。
 - 配置参考：请结合 [CONFIG_REFERENCE.md](CONFIG_REFERENCE.md) 查看各键的运行时语义与默认值。
@@ -171,7 +172,7 @@ python src/A_memorix/scripts/process_knowledge.py
 - `web/import.html`（导入中心）
 - `web/tuning.html`（检索调优）
 
-当前分支不再内置独立 `server.py`，页面路由与 API 暴露由宿主侧 React 页面和 `/api/webui/memory/*` 接口承接。
+当前分支不再内置独立 `server.py`，页面路由与 API 暴露由宿主侧 React 页面和 `/api/webui/memory/*` 接口承接（并保留 `/api/*` 兼容路由）。
 
 ### WebUI 验证脚本